@riffdb/client 0.2.0 → 0.2.1

package/README.md

@@ -7,8 +7,8 @@ compiler IDs, storage keys, or an authorization bypass.
 ## Install
 
 ```bash
-npm install --save-dev @riffdb/cli@0.1.0
-npm install @riffdb/client@0.1.0
+npm install --save-dev @riffdb/cli@0.2.1
+npm install @riffdb/client@0.2.1
 ```
 
 ## Four-step application story
@@ -40,6 +40,6 @@ response must be resolved with the same idempotency key.
 
 ## Version compatibility
 
-This is a 0.1.x pre-1.0 package. It carries the exact durable-format statement
+This is a 0.2.x pre-1.0 package. It carries the exact durable-format statement
 from `release/durable-format-manifest-v1.json`; downgrade is unsupported and a
 breaking epoch requires symbolic export/reimport. Sealed and explicitly offline bundles retain vendored @riffdb/application, riffdb-application, riffdb.dev/application, and the source-contained Rust SDK.

package/dist/driver.d.ts

@@ -59,6 +59,18 @@ export interface ExactMoneyValue<Currency extends string = string> {
 export declare function exactDecimal(value: string, precision: number, scale: number): ExactDecimalValue;
 export declare function exactMoney<const Currency extends string>(currency: Currency, value: string): ExactMoneyValue<Currency>;
 export interface DriverApplicationIdentity {
+    readonly applicationManifestHash?: string;
+    readonly operationCatalogHash?: string;
+    readonly contractLineage: string;
+    readonly contractVersion: bigint;
+    readonly contractBundleHash: string;
+    readonly database?: string;
+    readonly role: string;
+    readonly roleDefinitionHash?: string;
+    readonly remoteIdentityHash?: string;
+    readonly tenant?: string;
+}
+export interface ResolvedDriverApplicationIdentity {
     readonly applicationManifestHash: string;
     readonly operationCatalogHash: string;
     readonly contractLineage: string;
@@ -75,6 +87,15 @@ export interface DriverApplicationTransportOptions {
     readonly identity: DriverApplicationIdentity;
     readonly tenant?: string;
 }
+export interface DriverConnectFromEnvOptions {
+    readonly socketPath?: string;
+    readonly identity?: Partial<DriverApplicationIdentity>;
+    readonly role?: string;
+    readonly database?: string;
+    readonly tenant?: string;
+    readonly prefix?: string;
+    readonly envPrefix?: string;
+}
 export interface DriverOperation {
     readonly name: string;
     readonly inputSchemaHash: string;
@@ -163,9 +184,13 @@ export declare class DriverApplicationTransport {
     private constructor();
     /** Returns the bound tenant identifier when this session is tenant-scoped. */
     get tenant(): string | undefined;
+    /** Returns the resolved application identity verified during driver handshake. */
+    get identity(): ResolvedDriverApplicationIdentity;
     static connect(options: DriverApplicationTransportOptions): Promise<DriverApplicationTransport>;
+    static connectFromEnv(options?: DriverConnectFromEnvOptions): Promise<DriverApplicationTransport>;
     invoke(operation: DriverOperation, input: Readonly<Record<string, DriverValue>>, options?: DriverInvokeOptions): Promise<DriverResult>;
     batch(operation: DriverOperation, items: ReadonlyArray<Readonly<Record<string, DriverValue>>>, concurrency: number, checkpoint: number, options?: DriverInvokeOptions): Promise<DriverBatchResult>;
     /** Stops new work, sends a clean local EOF, and rejects unfinished waits. */
     shutdown(): Promise<void>;
 }
+export declare function resolveTransportOptionsFromEnv(options?: DriverConnectFromEnvOptions): DriverApplicationTransportOptions;

package/dist/driver.js

@@ -63,10 +63,12 @@ export class DriverApplicationError extends Error {
 export class DriverApplicationTransport {
     #socket;
     #identity;
+    #resolvedIdentity;
     #tenant;
     #requestPrefix;
     #pending = new Map();
-    #input = Buffer.alloc(0);
+    #inputChunks = [];
+    #inputLength = 0;
     #nextRequest = 1;
     #closed = false;
     constructor(socket, identity, tenant) {
@@ -83,6 +85,13 @@ export class DriverApplicationTransport {
     get tenant() {
         return this.#tenant;
     }
+    /** Returns the resolved application identity verified during driver handshake. */
+    get identity() {
+        if (this.#resolvedIdentity === undefined) {
+            throw new Error("RiffDB driver session has not completed handshake");
+        }
+        return this.#resolvedIdentity;
+    }
     static async connect(options) {
         const tenant = resolveTransportTenant(options);
         validateTransportOptions(options);
@@ -102,6 +111,9 @@ export class DriverApplicationTransport {
             throw error;
         }
     }
+    static async connectFromEnv(options = {}) {
+        return DriverApplicationTransport.connect(resolveTransportOptionsFromEnv(options));
+    }
     async invoke(operation, input, options = {}) {
         validateOperation(operation);
         validateDriverRecord(input);
@@ -138,7 +150,7 @@ export class DriverApplicationTransport {
             checkpoint,
             options: lowerOptions(options),
         }, requestId, options.signal);
-        return decodeBatchResult(response);
+        return decodeBatchResult(response, items.length, checkpoint);
     }
     /** Stops new work, sends a clean local EOF, and rejects unfinished waits. */
     async shutdown() {
@@ -157,35 +169,63 @@ export class DriverApplicationTransport {
     async #handshake() {
         const requestId = this.#requestId("handshake");
         const identity = this.#identity;
+        const manifestHash = identity.applicationManifestHash ?? "";
+        const catalogHash = identity.operationCatalogHash ?? "";
+        const database = identity.database ?? "";
+        const roleDefinitionHash = identity.roleDefinitionHash ?? "";
+        const remoteIdentityHash = identity.remoteIdentityHash ?? "";
         const response = await this.#request({
             type: "handshake",
             request_id: requestId,
             protocol_version: DRIVER_PROTOCOL_VERSION,
-            application_manifest_hash: identity.applicationManifestHash,
-            operation_catalog_hash: identity.operationCatalogHash,
+            application_manifest_hash: manifestHash,
+            operation_catalog_hash: catalogHash,
             contract_lineage: identity.contractLineage,
             contract_version: identity.contractVersion,
             contract_bundle_hash: identity.contractBundleHash,
             value_registry_hash: DRIVER_VALUE_REGISTRY_HASH,
             error_registry_hash: DRIVER_ERROR_REGISTRY_HASH,
-            database: identity.database,
+            database,
             role: identity.role,
-            role_definition_hash: identity.roleDefinitionHash,
-            remote_identity_hash: identity.remoteIdentityHash,
+            role_definition_hash: roleDefinitionHash,
+            remote_identity_hash: remoteIdentityHash,
         }, requestId);
         if (response.type !== "handshake"
             || response.protocol_version !== DRIVER_PROTOCOL_VERSION
-            || response.application_manifest_hash !== identity.applicationManifestHash
-            || response.operation_catalog_hash !== identity.operationCatalogHash
+            || typeof response.application_manifest_hash !== "string"
+            || !HASH.test(response.application_manifest_hash)
+            || (manifestHash !== "" && response.application_manifest_hash !== manifestHash)
+            || typeof response.operation_catalog_hash !== "string"
+            || !HASH.test(response.operation_catalog_hash)
+            || (catalogHash !== "" && response.operation_catalog_hash !== catalogHash)
             || response.contract_lineage !== identity.contractLineage
             || requiredPositiveBigInt(response.contract_version) !== identity.contractVersion
             || response.contract_bundle_hash !== identity.contractBundleHash
-            || response.database !== identity.database
+            || typeof response.database !== "string"
+            || !SYMBOL.test(response.database)
+            || (database !== "" && response.database !== database)
             || response.role !== identity.role
-            || response.role_definition_hash !== identity.roleDefinitionHash
-            || response.remote_identity_hash !== identity.remoteIdentityHash) {
+            || typeof response.role_definition_hash !== "string"
+            || !HASH.test(response.role_definition_hash)
+            || (roleDefinitionHash !== "" && response.role_definition_hash !== roleDefinitionHash)
+            || typeof response.remote_identity_hash !== "string"
+            || !HASH.test(response.remote_identity_hash)
+            || (remoteIdentityHash !== "" && response.remote_identity_hash !== remoteIdentityHash)) {
             throw new Error("RiffDB driver identity mismatch");
         }
+        this.#resolvedIdentity = {
+            applicationManifestHash: response.application_manifest_hash,
+            operationCatalogHash: response.operation_catalog_hash,
+            contractLineage: identity.contractLineage,
+            contractVersion: identity.contractVersion,
+            contractBundleHash: identity.contractBundleHash,
+            database: response.database,
+            role: identity.role,
+            roleDefinitionHash: response.role_definition_hash,
+            remoteIdentityHash: response.remote_identity_hash,
+            ...(this.#tenant === undefined ? {} : { tenant: this.#tenant }),
+        };
+        this.#identity = this.#resolvedIdentity;
     }
     async #request(request, requestId, signal) {
         if (this.#closed || this.#socket.destroyed)
@@ -230,31 +270,37 @@ export class DriverApplicationTransport {
         }
     }
     #receive(chunk) {
-        if (this.#closed)
+        if (this.#closed || chunk.length === 0)
             return;
-        this.#input = Buffer.concat([this.#input, chunk]);
-        while (this.#input.length >= 4) {
-            const length = this.#input.readUInt32BE(0);
+        this.#inputChunks.push(chunk);
+        this.#inputLength += chunk.length;
+        while (this.#inputLength >= 4) {
+            const length = this.#peekFrameLength();
             if (length < 2 || length > MAX_FRAME_BYTES) {
+                this.#inputChunks.length = 0;
+                this.#inputLength = 0;
                 this.#fail(new Error("RiffDB driver returned an invalid frame"));
                 this.#socket.destroy();
                 return;
             }
-            if (this.#input.length < length + 4)
+            if (this.#inputLength < length + 4)
                 return;
-            const body = this.#input.subarray(4, length + 4);
-            this.#input = this.#input.subarray(length + 4);
+            const body = this.#consumeFrame(length);
             let response;
             try {
                 response = exactObject(decodeJson(UTF8_DECODER.decode(body)));
             }
             catch {
+                this.#inputChunks.length = 0;
+                this.#inputLength = 0;
                 this.#fail(new Error("RiffDB driver returned an invalid message"));
                 this.#socket.destroy();
                 return;
             }
             const requestId = response.request_id;
             if (typeof requestId !== "string" || !REQUEST_ID.test(requestId)) {
+                this.#inputChunks.length = 0;
+                this.#inputLength = 0;
                 this.#fail(new Error("RiffDB driver returned an invalid request identity"));
                 this.#socket.destroy();
                 return;
@@ -266,6 +312,80 @@ export class DriverApplicationTransport {
             pending.resolve(response);
         }
     }
+    #peekFrameLength() {
+        const first = this.#inputChunks[0];
+        if (first.length >= 4) {
+            return first.readUInt32BE(0);
+        }
+        let b0 = 0;
+        let b1 = 0;
+        let b2 = 0;
+        let b3 = 0;
+        let idx = 0;
+        outer: for (const chunk of this.#inputChunks) {
+            for (let i = 0; i < chunk.length; i += 1) {
+                const byte = chunk[i];
+                if (idx === 0)
+                    b0 = byte;
+                else if (idx === 1)
+                    b1 = byte;
+                else if (idx === 2)
+                    b2 = byte;
+                else {
+                    b3 = byte;
+                    break outer;
+                }
+                idx += 1;
+            }
+        }
+        return ((b0 << 24) | (b1 << 16) | (b2 << 8) | b3) >>> 0;
+    }
+    #consumeFrame(bodyLength) {
+        this.#skipBytes(4);
+        const first = this.#inputChunks[0];
+        if (first.length >= bodyLength) {
+            const body = first.subarray(0, bodyLength);
+            if (first.length === bodyLength) {
+                this.#inputChunks.shift();
+            }
+            else {
+                this.#inputChunks[0] = first.subarray(bodyLength);
+            }
+            this.#inputLength -= bodyLength;
+            return body;
+        }
+        const body = Buffer.allocUnsafe(bodyLength);
+        let offset = 0;
+        while (offset < bodyLength) {
+            const chunk = this.#inputChunks[0];
+            const take = Math.min(chunk.length, bodyLength - offset);
+            chunk.copy(body, offset, 0, take);
+            offset += take;
+            if (take === chunk.length) {
+                this.#inputChunks.shift();
+            }
+            else {
+                this.#inputChunks[0] = chunk.subarray(take);
+            }
+        }
+        this.#inputLength -= bodyLength;
+        return body;
+    }
+    #skipBytes(count) {
+        let remaining = count;
+        while (remaining > 0) {
+            const chunk = this.#inputChunks[0];
+            if (chunk.length <= remaining) {
+                remaining -= chunk.length;
+                this.#inputChunks.shift();
+            }
+            else {
+                this.#inputChunks[0] = chunk.subarray(remaining);
+                remaining = 0;
+            }
+        }
+        this.#inputLength -= count;
+    }
     #fail(error) {
         for (const pending of this.#pending.values())
             pending.reject(error);
@@ -675,20 +795,30 @@ function decodeResult(response) {
         ...(cursor === undefined ? {} : { cursor }),
     };
 }
-function decodeBatchResult(response) {
+function decodeBatchResult(response, expectedTotal, requestedCheckpoint) {
     if (response.type !== "batch_result" || !Array.isArray(response.items)
         || response.items.length > MAX_COLLECTION_ITEMS) {
         throw new Error("RiffDB driver returned an invalid batch result");
     }
     const checkpoint = boundedInteger(response.checkpoint, 0, MAX_COLLECTION_ITEMS);
     const total = boundedInteger(response.total, 1, MAX_COLLECTION_ITEMS);
-    if (checkpoint > total)
+    if (total !== expectedTotal || checkpoint < requestedCheckpoint || checkpoint > total
+        || response.items.length !== total - requestedCheckpoint) {
         throw new Error("RiffDB driver returned an invalid batch result");
+    }
+    const seenIndices = new Set();
     const items = response.items.map((raw) => {
         const item = exactObject(raw);
-        const index = boundedInteger(item.index, 0, total - 1);
+        const index = boundedInteger(item.index, requestedCheckpoint, total - 1);
+        if (seenIndices.has(index)) {
+            throw new Error("RiffDB driver returned an invalid batch item");
+        }
+        seenIndices.add(index);
         const outcome = exactObject(item.outcome);
         if (outcome.type === "result") {
+            if (index === checkpoint) {
+                throw new Error("RiffDB driver returned an invalid batch result");
+            }
             const value = validateDriverValue(outcome.value, 0);
             const commitSequence = optionalPositiveBigInt(outcome.commit_sequence);
             const outcomeUri = optionalBoundedString(outcome.outcome_uri, 16_384);
@@ -704,8 +834,12 @@ function decodeBatchResult(response) {
                 },
             };
         }
-        if (outcome.type === "error")
+        if (outcome.type === "error") {
+            if (index < checkpoint) {
+                throw new Error("RiffDB driver returned an invalid batch result");
+            }
             return { index, error: decodeError(outcome) };
+        }
         throw new Error("RiffDB driver returned an invalid batch item");
     });
     return { items, checkpoint, total };
@@ -740,8 +874,10 @@ function decodeError(response) {
         ...(incidentId === undefined ? {} : { incidentId }),
     });
 }
+const ENV_RESOLVED = Symbol("riffdb.envResolved");
 function resolveTransportTenant(options) {
-    const envTenant = process.env.RIFFDB_TENANT;
+    const allowEnvFallback = !(ENV_RESOLVED in options);
+    const envTenant = allowEnvFallback ? process.env.RIFFDB_TENANT : undefined;
     const candidate = options.tenant ?? options.identity.tenant ?? (envTenant && envTenant.length > 0 ? envTenant : undefined);
     if (candidate === undefined)
         return undefined;
@@ -750,19 +886,95 @@ function resolveTransportTenant(options) {
     }
     return candidate;
 }
+export function resolveTransportOptionsFromEnv(options = {}) {
+    if (options.prefix !== undefined &&
+        options.envPrefix !== undefined &&
+        options.prefix !== options.envPrefix) {
+        throw new Error("conflicting RiffDB environment prefixes");
+    }
+    const rawPrefix = options.prefix ?? options.envPrefix;
+    if (rawPrefix !== undefined &&
+        (typeof rawPrefix !== "string" ||
+            rawPrefix.trim().length === 0 ||
+            !/^[A-Za-z_][A-Za-z0-9_]*$/.test(rawPrefix))) {
+        throw new Error("invalid RiffDB environment prefix");
+    }
+    const normalizedPrefix = rawPrefix === undefined
+        ? "RIFFDB_"
+        : rawPrefix.endsWith("_")
+            ? rawPrefix
+            : `${rawPrefix}_`;
+    const candidatePrefixes = normalizedPrefix === "RIFFDB_" || normalizedPrefix.endsWith("RIFFDB_")
+        ? [normalizedPrefix]
+        : [`${normalizedPrefix}RIFFDB_`, normalizedPrefix];
+    const readEnv = (suffix) => {
+        for (const candidatePrefix of candidatePrefixes) {
+            const raw = process.env[`${candidatePrefix}${suffix}`];
+            if (raw !== undefined && raw.trim().length > 0) {
+                return raw.trim();
+            }
+        }
+        return undefined;
+    };
+    const socketPath = options.socketPath ?? readEnv("DRIVER_SOCKET") ?? "";
+    const base = options.identity ?? {};
+    const contractLineage = base.contractLineage ?? readEnv("LINEAGE") ?? "";
+    const rawVersion = base.contractVersion ?? readEnv("CONTRACT_VERSION");
+    let contractVersion = 0n;
+    if (typeof rawVersion === "bigint") {
+        contractVersion = rawVersion;
+    }
+    else if (typeof rawVersion === "string" && /^[0-9]+$/.test(rawVersion)) {
+        contractVersion = BigInt(rawVersion);
+    }
+    const contractBundleHash = base.contractBundleHash ?? readEnv("BUNDLE_HASH") ?? "";
+    const role = options.role ?? base.role ?? readEnv("ROLE") ?? "";
+    const database = options.database ?? base.database ?? readEnv("DATABASE");
+    const applicationManifestHash = base.applicationManifestHash ?? readEnv("MANIFEST_HASH");
+    const operationCatalogHash = base.operationCatalogHash ?? readEnv("CATALOG_HASH");
+    const roleDefinitionHash = base.roleDefinitionHash ?? readEnv("ROLE_HASH");
+    const remoteIdentityHash = base.remoteIdentityHash ?? readEnv("REMOTE_HASH");
+    const tenant = options.tenant ?? base.tenant ?? readEnv("TENANT");
+    const identity = {
+        contractLineage,
+        contractVersion,
+        contractBundleHash,
+        role,
+        ...(database !== undefined && database.length > 0 ? { database } : {}),
+        ...(applicationManifestHash !== undefined && applicationManifestHash.length > 0 ? { applicationManifestHash } : {}),
+        ...(operationCatalogHash !== undefined && operationCatalogHash.length > 0 ? { operationCatalogHash } : {}),
+        ...(roleDefinitionHash !== undefined && roleDefinitionHash.length > 0 ? { roleDefinitionHash } : {}),
+        ...(remoteIdentityHash !== undefined && remoteIdentityHash.length > 0 ? { remoteIdentityHash } : {}),
+        ...(tenant !== undefined && tenant.length > 0 ? { tenant } : {}),
+    };
+    const resolved = {
+        socketPath,
+        identity,
+        ...(tenant !== undefined && tenant.length > 0 ? { tenant } : {}),
+    };
+    Object.defineProperty(resolved, ENV_RESOLVED, { value: true, enumerable: false });
+    return resolved;
+}
 function validateTransportOptions(options) {
     if (!options.socketPath.startsWith("/") || options.socketPath.length > 4_096) {
         throw new Error("invalid RiffDB driver socket path");
     }
     const identity = options.identity;
+    if (!HASH.test(identity.contractBundleHash)) {
+        throw new Error("invalid RiffDB driver identity");
+    }
     for (const value of [
         identity.applicationManifestHash, identity.operationCatalogHash,
-        identity.contractBundleHash, identity.roleDefinitionHash, identity.remoteIdentityHash,
+        identity.roleDefinitionHash, identity.remoteIdentityHash,
     ]) {
-        if (!HASH.test(value))
+        if (value !== undefined && value !== "" && !HASH.test(value)) {
             throw new Error("invalid RiffDB driver identity");
+        }
+    }
+    if (identity.database !== undefined && identity.database !== "" && !SYMBOL.test(identity.database)) {
+        throw new Error("invalid RiffDB driver identity");
     }
-    if (!SYMBOL.test(identity.contractLineage) || !SYMBOL.test(identity.database)
+    if (!SYMBOL.test(identity.contractLineage)
         || !SYMBOL.test(identity.role) || identity.contractVersion < 1n
         || identity.contractVersion > 18446744073709551615n) {
         throw new Error("invalid RiffDB driver identity");

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { DriverApplicationTransport, type DriverApplicationError, type DriverCompactQueryResult, type DriverPackedQueryResult, type DriverOperation } from "./driver.js";
+import { DriverApplicationTransport, type DriverApplicationError, type DriverApplicationTransportOptions, type DriverConnectFromEnvOptions, type DriverCompactQueryResult, type DriverPackedQueryResult, type DriverOperation } from "./driver.js";
 export type ApplicationValueSchema = {
     readonly kind: "bool" | "i64" | "u64" | "string" | "uuid" | "bytes" | "date" | "timestamp" | "cursor" | "limit";
     readonly maximumBytes?: number;
@@ -51,12 +51,52 @@ export interface ExactDecimalValue {
     readonly coefficientTwosComplement: Uint8Array;
     readonly scale: number;
     readonly precision: number;
+    toString?(): string;
+    toJSON?(): string;
 }
 /** One exact currency value accepted by generated `money<CURRENCY>` fields. */
 export interface ExactMoneyValue<Currency extends string = string> {
     readonly currency: Currency;
     readonly amount: ExactDecimalValue;
+    toString?(): string;
+    toJSON?(): {
+        readonly currency: Currency;
+        readonly amount: string;
+    };
 }
+/** One exact UTC timestamp returned by generated query and command fields. */
+export interface TimestampValue {
+    readonly seconds: bigint;
+    readonly nanos: number;
+    toISOString(): string;
+    toDate(): Date;
+    toJSON(): string;
+    toString(): string;
+}
+export type TimestampInput = TimestampValue | {
+    readonly seconds: bigint | number | string;
+    readonly nanos?: number;
+} | Date | string;
+export type IntegerInput = bigint | number | string;
+export declare class RiffTimestamp implements TimestampValue {
+    readonly seconds: bigint;
+    readonly nanos: number;
+    constructor(seconds: bigint, nanos?: number);
+    static from(value: TimestampInput): TimestampValue;
+    static now(): TimestampValue;
+    toISOString(): string;
+    toDate(): Date;
+    toJSON(): string;
+    toString(): string;
+}
+export declare function createTimestampValue(seconds: bigint, nanos: number): TimestampValue;
+export declare function formatTimestampIso(seconds: bigint, nanos: number): string;
+export declare function formatExactDecimal(value: {
+    readonly coefficientTwosComplement: Uint8Array;
+    readonly scale: number;
+}): string;
+export declare function toJsonValue(value: unknown, key?: string): unknown;
+export declare function attachRecordToJson<T extends Record<string, unknown>>(record: T): T;
 /**
  * Constructs an exact fixed-point value from decimal text without using a
  * JavaScript floating-point number.
@@ -198,8 +238,10 @@ export interface ContextualBatch<E> {
     readonly status: ReactiveConsumerStatus;
 }
 export interface ReactiveConsumerStatus {
+    readonly kind?: "exact" | "protected";
     readonly revision: bigint;
     readonly checkpoint: string;
+    readonly progressCursor?: string;
     readonly historyIncarnation: bigint;
     readonly liveLeases: number;
     readonly retries: number;
@@ -294,8 +336,11 @@ export declare class CliApplicationTransport {
 export declare class DriverGeneratedApplicationTransport {
     private readonly driver;
     constructor(driver: DriverApplicationTransport);
+    static connect(options: DriverApplicationTransportOptions): Promise<DriverGeneratedApplicationTransport>;
+    static connectFromEnv(options?: DriverConnectFromEnvOptions): Promise<DriverGeneratedApplicationTransport>;
     /** Returns the bound tenant identifier when this session is tenant-scoped. */
     get tenant(): string | undefined;
+    shutdown(): Promise<void>;
     executeNamedQuery<P, R>(request: NamedQueryRequest<P, R>, options?: QueryOptions): Promise<TypedQueryResult<R>>;
     executeCommand<I, R>(request: CommandRequest<I, R>, attemptBudget: number): Promise<TypedCommandResult<R>>;
     executeVectorInspection<P, R>(request: VectorInspectionRequest<P, R>, options?: VectorInspectionOptions): Promise<TypedVectorInspectionResult<R>>;
@@ -328,5 +373,5 @@ export declare class DriverGeneratedApplicationTransport {
     }): AsyncIterable<LiveQueryUpdate<T>>;
     private mutateDriverLease;
 }
-export { DRIVER_ERROR_REGISTRY_HASH, DRIVER_PROTOCOL_VERSION, DRIVER_VALUE_REGISTRY_HASH, DriverApplicationError, DriverApplicationTransport, } from "./driver.js";
-export type { DriverApplicationIdentity, DriverApplicationTransportOptions, DriverBatchItem, DriverBatchResult, DriverBatchSuccess, DriverDecimal, DriverErrorDetails, DriverInvokeOptions, DriverMoney, DriverOperation, DriverPackedColumn, DriverPackedQueryResult, DriverResult, DriverTimestamp, DriverValue, } from "./driver.js";
+export { DRIVER_ERROR_REGISTRY_HASH, DRIVER_PROTOCOL_VERSION, DRIVER_VALUE_REGISTRY_HASH, DriverApplicationError, DriverApplicationTransport, resolveTransportOptionsFromEnv, } from "./driver.js";
+export type { DriverApplicationIdentity, DriverApplicationTransportOptions, DriverConnectFromEnvOptions, DriverBatchItem, DriverBatchResult, DriverBatchSuccess, DriverDecimal, DriverErrorDetails, DriverInvokeOptions, DriverMoney, DriverOperation, DriverPackedColumn, DriverPackedQueryResult, DriverResult, DriverTimestamp, DriverValue, ResolvedDriverApplicationIdentity, } from "./driver.js";

package/dist/index.js

@@ -3,6 +3,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
+import { DriverApplicationTransport, } from "./driver.js";
 const executeFile = promisify(execFile);
 const MAX_OUTPUT_BYTES = 4_194_304;
 const HASH = /^[0-9a-f]{64}$/;
@@ -18,6 +19,253 @@ export class InputBudgetError extends Error {
         this.name = "InputBudgetError";
     }
 }
+export class RiffTimestamp {
+    seconds;
+    nanos;
+    constructor(seconds, nanos = 0) {
+        if (typeof seconds !== "bigint" || seconds < -(1n << 63n) || seconds > (1n << 63n) - 1n) {
+            throw new Error("invalid RiffDB timestamp seconds");
+        }
+        if (!Number.isInteger(nanos) || nanos < 0 || nanos > 999_999_999) {
+            throw new Error("invalid RiffDB timestamp nanos");
+        }
+        this.seconds = seconds;
+        this.nanos = nanos;
+    }
+    static from(value) {
+        const parsed = coerceTimestampInput(value, "invalid RiffDB timestamp input");
+        return createTimestampValue(parsed.seconds, parsed.nanos);
+    }
+    static now() {
+        return RiffTimestamp.from(new Date());
+    }
+    toISOString() {
+        return formatTimestampIso(this.seconds, this.nanos);
+    }
+    toDate() {
+        return new Date(Number(this.seconds) * 1000 + Math.floor(this.nanos / 1_000_000));
+    }
+    toJSON() {
+        return this.toISOString();
+    }
+    toString() {
+        return this.toISOString();
+    }
+}
+export function createTimestampValue(seconds, nanos) {
+    const target = { seconds, nanos };
+    Object.defineProperties(target, {
+        toISOString: {
+            value() {
+                return formatTimestampIso(this.seconds, this.nanos);
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        toDate: {
+            value() {
+                return new Date(Number(this.seconds) * 1000 + Math.floor(this.nanos / 1_000_000));
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        toJSON: {
+            value() {
+                return formatTimestampIso(this.seconds, this.nanos);
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        toString: {
+            value() {
+                return formatTimestampIso(this.seconds, this.nanos);
+            },
+            enumerable: false,
+            configurable: true,
+        },
+    });
+    return target;
+}
+function isGregorianLeapYear(year) {
+    return year % 4n === 0n && (year % 100n !== 0n || year % 400n === 0n);
+}
+function daysInGregorianMonth(year, month) {
+    switch (month) {
+        case 1:
+        case 3:
+        case 5:
+        case 7:
+        case 8:
+        case 10:
+        case 12:
+            return 31;
+        case 4:
+        case 6:
+        case 9:
+        case 11:
+            return 30;
+        case 2:
+            return isGregorianLeapYear(year) ? 29 : 28;
+        default:
+            return 0;
+    }
+}
+function daysFromCivil(year, month, day) {
+    const adjustedYear = month <= 2 ? year - 1n : year;
+    const era = (adjustedYear >= 0n ? adjustedYear : adjustedYear - 399n) / 400n;
+    const yoe = adjustedYear - era * 400n;
+    const m = BigInt(month);
+    const d = BigInt(day);
+    const doy = (153n * (m > 2n ? m - 3n : m + 9n) + 2n) / 5n + d - 1n;
+    const doe = yoe * 365n + yoe / 4n - yoe / 100n + doy;
+    return era * 146097n + doe - 719468n;
+}
+function civilFromDays(days) {
+    const z = days + 719468n;
+    const era = (z >= 0n ? z : z - 146096n) / 146097n;
+    const doe = z - era * 146097n;
+    const yoe = (doe - doe / 1460n + doe / 36524n - doe / 146096n) / 365n;
+    const y = yoe + era * 400n;
+    const doy = doe - (365n * yoe + yoe / 4n - yoe / 100n);
+    const mp = (5n * doy + 2n) / 153n;
+    const d = doy - (153n * mp + 2n) / 5n + 1n;
+    const m = mp < 10n ? mp + 3n : mp - 9n;
+    return {
+        year: m <= 2n ? y + 1n : y,
+        month: Number(m),
+        day: Number(d),
+    };
+}
+export function formatTimestampIso(seconds, nanos) {
+    const daySeconds = ((seconds % 86400n) + 86400n) % 86400n;
+    const days = (seconds - daySeconds) / 86400n;
+    const { year, month, day } = civilFromDays(days);
+    const hour = Number(daySeconds / 3600n);
+    const minute = Number((daySeconds % 3600n) / 60n);
+    const second = Number(daySeconds % 60n);
+    const yearPart = year < 0n
+        ? `-${(-year).toString().padStart(6, "0")}`
+        : year > 9999n
+            ? `+${year.toString().padStart(6, "0")}`
+            : year.toString().padStart(4, "0");
+    const datePart = `${yearPart}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}T${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}:${String(second).padStart(2, "0")}`;
+    const fractionPart = nanos % 1_000_000 === 0
+        ? String(Math.floor(nanos / 1_000_000)).padStart(3, "0")
+        : String(nanos).padStart(9, "0").replace(/0+$/, "");
+    return `${datePart}.${fractionPart}Z`;
+}
+export function formatExactDecimal(value) {
+    let coefficient = decodeSignedTwosComplement(value.coefficientTwosComplement);
+    const negative = coefficient < 0n;
+    if (negative)
+        coefficient = -coefficient;
+    const scale = value.scale;
+    if (scale === 0) {
+        return `${negative ? "-" : ""}${coefficient.toString()}`;
+    }
+    const digits = coefficient.toString().padStart(scale + 1, "0");
+    const split = digits.length - scale;
+    return `${negative ? "-" : ""}${digits.slice(0, split)}.${digits.slice(split)}`;
+}
+function attachDecimalToJson(decimal) {
+    Object.defineProperties(decimal, {
+        toString: {
+            value() {
+                return formatExactDecimal(this);
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        toJSON: {
+            value() {
+                return formatExactDecimal(this);
+            },
+            enumerable: false,
+            configurable: true,
+        },
+    });
+    return decimal;
+}
+function attachMoneyToJson(money) {
+    Object.defineProperties(money, {
+        toString: {
+            value() {
+                return `${this.currency} ${formatExactDecimal(this.amount)}`;
+            },
+            enumerable: false,
+            configurable: true,
+        },
+        toJSON: {
+            value() {
+                return { currency: this.currency, amount: formatExactDecimal(this.amount) };
+            },
+            enumerable: false,
+            configurable: true,
+        },
+    });
+    return money;
+}
+export function toJsonValue(value, key) {
+    if (value === null || value === undefined || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "bigint") {
+        if (key !== undefined && (key === "revision" || key.endsWith("_revision") || key.endsWith("Revision"))) {
+            return value.toString();
+        }
+        if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+            return Number(value);
+        }
+        return value.toString();
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (value instanceof Uint8Array) {
+        return Buffer.from(value).toString("base64");
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => toJsonValue(item));
+    }
+    if (typeof value === "object") {
+        const record = value;
+        if (typeof record.seconds === "bigint" && typeof record.nanos === "number") {
+            return formatTimestampIso(record.seconds, record.nanos);
+        }
+        if (record.coefficientTwosComplement instanceof Uint8Array && typeof record.scale === "number") {
+            return formatExactDecimal(record);
+        }
+        if (typeof record.currency === "string" && typeof record.amount === "object" && record.amount !== null) {
+            const amount = record.amount;
+            if (amount.coefficientTwosComplement instanceof Uint8Array && typeof amount.scale === "number") {
+                return {
+                    currency: record.currency,
+                    amount: formatExactDecimal(amount),
+                };
+            }
+        }
+        const output = {};
+        for (const [entryKey, entryValue] of Object.entries(record)) {
+            output[entryKey] = toJsonValue(entryValue, entryKey);
+        }
+        return output;
+    }
+    return value;
+}
+export function attachRecordToJson(record) {
+    Object.defineProperty(record, "toJSON", {
+        value() {
+            const output = {};
+            for (const [entryKey, entryValue] of Object.entries(this)) {
+                output[entryKey] = toJsonValue(entryValue, entryKey);
+            }
+            return output;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+    return record;
+}
 /**
  * Constructs an exact fixed-point value from decimal text without using a
  * JavaScript floating-point number.
@@ -43,17 +291,17 @@ export function exactDecimal(value, precision, scale) {
     const limit = 10n ** BigInt(precision);
     if (coefficient <= -limit || coefficient >= limit)
         throw new Error("exact decimal exceeds precision");
-    return {
+    return attachDecimalToJson({
         coefficientTwosComplement: signedTwosComplement(coefficient),
         scale,
         precision,
-    };
+    });
 }
 /** Constructs the exact precision-38, scale-2 value used by `money<CURRENCY>`. */
 export function exactMoney(currency, value) {
     if (!/^[A-Z]{3}$/.test(currency))
         throw new Error("invalid exact money currency");
-    return { currency, amount: exactDecimal(value, 38, 2) };
+    return attachMoneyToJson({ currency, amount: exactDecimal(value, 38, 2) });
 }
 export class CliApplicationTransport {
     options;
@@ -389,10 +637,19 @@ export class DriverGeneratedApplicationTransport {
     constructor(driver) {
         this.driver = driver;
     }
+    static async connect(options) {
+        return new DriverGeneratedApplicationTransport(await DriverApplicationTransport.connect(options));
+    }
+    static async connectFromEnv(options = {}) {
+        return new DriverGeneratedApplicationTransport(await DriverApplicationTransport.connectFromEnv(options));
+    }
     /** Returns the bound tenant identifier when this session is tenant-scoped. */
     get tenant() {
         return this.driver.tenant;
     }
+    async shutdown() {
+        await this.driver.shutdown();
+    }
     async executeNamedQuery(request, options = {}) {
         validateIdentity(request);
         const operation = requireDriverOperation(request.driverOperation);
@@ -613,6 +870,42 @@ function decodeDriverMutationResult(value) {
 }
 function decodeDriverConsumerStatus(value) {
     const status = driverRecord(value);
+    if (status.kind !== undefined) {
+        const kind = driverEnum(status.kind);
+        if (kind === "protected") {
+            const historyIncarnation = driverPositiveU64(requiredDriverField(status, "history_incarnation"));
+            const rawCursor = requiredDriverField(status, "progress_cursor");
+            let progressCursor;
+            if (rawCursor.type === "bytes") {
+                if (rawCursor.value.length < 1 || rawCursor.value.length > 512) {
+                    throw new Error("invalid RiffDB driver consumer status");
+                }
+                progressCursor = rawCursor.value;
+            }
+            else if (rawCursor.type === "string") {
+                progressCursor = expectBoundedString(rawCursor.value, 512);
+                if (progressCursor.length < 1) {
+                    throw new Error("invalid RiffDB driver consumer status");
+                }
+            }
+            else {
+                throw new Error("invalid RiffDB driver consumer status");
+            }
+            return {
+                kind: "protected",
+                revision: 0n,
+                checkpoint: progressCursor,
+                progressCursor,
+                historyIncarnation,
+                liveLeases: 0,
+                retries: 0,
+                deadLetters: 0,
+            };
+        }
+        if (kind !== "exact") {
+            throw new Error("invalid RiffDB driver consumer status");
+        }
+    }
     return {
         revision: driverPositiveU64(requiredDriverField(status, "revision")),
         checkpoint: driverString(requiredDriverField(status, "checkpoint"), 256),
@@ -701,13 +994,13 @@ function decodeDriverLiveUpdate(value, applicationHead, responseCursor) {
         return {
             type: "terminal",
             reason,
-            lastApplicationHead: driverPositiveU64(requiredDriverField(record, "application_head")),
+            lastApplicationHead: driverNonnegativeU64(requiredDriverField(record, "application_head")),
             historyIncarnation: driverPositiveU64(requiredDriverField(record, "history_incarnation")),
         };
     }
     const checkpoint = driverRecord(requiredDriverField(update, "checkpoint"));
     const cursor = driverString(requiredDriverField(checkpoint, "cursor"), 16_384);
-    const head = driverPositiveU64(requiredDriverField(checkpoint, "application_head"));
+    const head = driverNonnegativeU64(requiredDriverField(checkpoint, "application_head"));
     const history = driverPositiveU64(requiredDriverField(checkpoint, "history_incarnation"));
     if (applicationHead !== head || responseCursor !== cursor) {
         throw new Error("RiffDB driver live frontier is inconsistent");
@@ -774,6 +1067,7 @@ function decodeDriverDynamic(value) {
                 throw new Error("invalid RiffDB driver money");
             return { currency: value.value.currency, amount: { coefficientTwosComplement: Uint8Array.from(Buffer.from(value.value.amount.coefficient, "base64")), scale: value.value.amount.scale, precision: value.value.amount.precision } };
         }
+        case "vector": return decodeVectorBits(value.value.component_bits, value.value.component_bits.length);
         case "list": return value.value.map(decodeDriverDynamic);
         case "record": return decodeDriverDynamicRecord(value.value);
     }
@@ -805,6 +1099,14 @@ function driverPositiveU64(value) {
         throw new Error("invalid RiffDB driver u64");
     return parsed;
 }
+function driverNonnegativeU64(value) {
+    if (value.type !== "u64")
+        throw new Error("invalid RiffDB driver u64");
+    const parsed = BigInt(value.value);
+    if (parsed < 0n || parsed > (1n << 64n) - 1n)
+        throw new Error("invalid RiffDB driver u64");
+    return parsed;
+}
 function driverBoundedU32(value) {
     if (value.type !== "u64")
         throw new Error("invalid RiffDB driver u32");
@@ -899,14 +1201,14 @@ function encodeDriverValue(value, schema, budgetPath) {
             if (typeof value !== "boolean")
                 throw new Error("invalid generated RiffDB bool input");
             return { type: "bool", value };
-        case "i64":
-            if (typeof value !== "bigint" || value < -(1n << 63n) || value > (1n << 63n) - 1n)
-                throw new Error("invalid generated RiffDB i64 input");
-            return { type: "i64", value: value.toString() };
-        case "u64":
-            if (typeof value !== "bigint" || value < 0n || value > (1n << 64n) - 1n)
-                throw new Error("invalid generated RiffDB u64 input");
-            return { type: "u64", value: value.toString() };
+        case "i64": {
+            const parsed = coerceI64Input(value, "invalid generated RiffDB i64 input");
+            return { type: "i64", value: parsed.toString() };
+        }
+        case "u64": {
+            const parsed = coerceU64Input(value, "invalid generated RiffDB u64 input");
+            return { type: "u64", value: parsed.toString() };
+        }
         case "string": {
             const string = expectBoundedString(value, 262_144);
             if (schema.maximumBytes !== undefined && new TextEncoder().encode(string).length > schema.maximumBytes && budgetPath !== undefined) {
@@ -932,10 +1234,8 @@ function encodeDriverValue(value, schema, budgetPath) {
                 throw new Error("invalid generated RiffDB date input");
             return { type: "date", value: String(value) };
         case "timestamp": {
-            const timestamp = exactObject(value);
-            if (typeof timestamp.seconds !== "bigint" || timestamp.seconds < -(1n << 63n) || timestamp.seconds > (1n << 63n) - 1n)
-                throw new Error("invalid generated RiffDB timestamp input");
-            return { type: "timestamp", value: { seconds: timestamp.seconds.toString(), nanos: boundedInteger(timestamp.nanos, 0, 999_999_999) } };
+            const timestamp = coerceTimestampInput(value, "invalid generated RiffDB timestamp input");
+            return { type: "timestamp", value: { seconds: timestamp.seconds.toString(), nanos: timestamp.nanos } };
         }
         case "decimal": return { type: "decimal", value: encodeDriverDecimal(value, schema) };
         case "money": {
@@ -1120,7 +1420,7 @@ function decodeDriverValue(value, schema) {
                 throw new Error("invalid RiffDB driver record result");
             output[field.name] = decodeDriverValue(fieldValue, field.schema);
         }
-        return output;
+        return attachRecordToJson(output);
     }
     switch (schema.kind) {
         case "bool":
@@ -1167,7 +1467,7 @@ function decodeDriverValue(value, schema) {
             break;
         case "timestamp":
             if (value.type === "timestamp")
-                return { seconds: BigInt(value.value.seconds), nanos: boundedInteger(value.value.nanos, 0, 999_999_999) };
+                return createTimestampValue(BigInt(value.value.seconds), boundedInteger(value.value.nanos, 0, 999_999_999));
             break;
         case "decimal":
             if (value.type === "decimal")
@@ -1175,7 +1475,7 @@ function decodeDriverValue(value, schema) {
             break;
         case "money":
             if (value.type === "money" && value.value.currency === schema.currency)
-                return { currency: value.value.currency, amount: decodeDriverDecimal(value.value.amount, schema) };
+                return attachMoneyToJson({ currency: value.value.currency, amount: decodeDriverDecimal(value.value.amount, schema) });
             break;
         case "vector":
             if (value.type === "vector")
@@ -1196,7 +1496,7 @@ function decodeDriverDecimal(value, schema) {
     const coefficient = Uint8Array.from(Buffer.from(value.coefficient, "base64"));
     if (coefficient.byteLength < 1 || coefficient.byteLength > 16)
         throw new Error("RiffDB driver decimal coefficient is invalid");
-    return { coefficientTwosComplement: coefficient, precision: schema.precision, scale: schema.scale };
+    return attachDecimalToJson({ coefficientTwosComplement: coefficient, precision: schema.precision, scale: schema.scale });
 }
 function decodeTypedCommandResult(result, request) {
     if (expectHash(result.plan_hash) !== request.planHash) {
@@ -1207,7 +1507,7 @@ function decodeTypedCommandResult(result, request) {
     if (schema === undefined)
         throw new Error("RiffDB application response has an unknown outcome");
     const payload = decodeWire(result.outcome, schema);
-    const outcome = { outcome: outcomeName, ...exactObject(payload) };
+    const outcome = attachRecordToJson({ outcome: outcomeName, ...exactObject(payload) });
     const typed = {
         outcome,
         contractVersion: positiveNumber(result.contract_version),
@@ -1367,16 +1667,14 @@ function encodeValue(value, schema, budgetPath) {
             if (typeof value !== "boolean")
                 throw new Error("invalid boolean input");
             return value;
-        case "i64":
-            if (typeof value !== "bigint" || value < -(1n << 63n) || value > (1n << 63n) - 1n) {
-                throw new Error("invalid i64 input");
-            }
-            return { $i64: value.toString() };
-        case "u64":
-            if (typeof value !== "bigint" || value < 0n || value > (1n << 64n) - 1n) {
-                throw new Error("invalid u64 input");
-            }
-            return { $u64: value.toString() };
+        case "i64": {
+            const parsed = coerceI64Input(value, "invalid i64 input");
+            return { $i64: parsed.toString() };
+        }
+        case "u64": {
+            const parsed = coerceU64Input(value, "invalid u64 input");
+            return { $u64: parsed.toString() };
+        }
         case "decimal": {
             const decimal = encodeDecimal(value);
             if (schema.precision === undefined || schema.scale === undefined
@@ -1416,14 +1714,8 @@ function encodeValue(value, schema, budgetPath) {
             }
             return { $date: value };
         case "timestamp": {
-            const input = exactObject(value);
-            const seconds = input.seconds;
-            const nanos = input.nanos;
-            if (typeof seconds !== "bigint" || seconds < -(1n << 63n) || seconds > (1n << 63n) - 1n
-                || !Number.isInteger(nanos) || nanos < 0 || nanos > 999_999_999) {
-                throw new Error("invalid timestamp input");
-            }
-            return { $timestamp: { seconds: seconds.toString(), nanos } };
+            const timestamp = coerceTimestampInput(value, "invalid timestamp input");
+            return { $timestamp: { seconds: timestamp.seconds.toString(), nanos: timestamp.nanos } };
         }
         case "vector": return { $vector: encodeVector(value, schema.dimension) };
         case "limit":
@@ -1500,7 +1792,7 @@ function normalizeQueryFields(value) {
                     throw new Error("duplicate RiffDB query field");
                 result[fieldName] = decodeTagged(entry.value);
             }
-            return result;
+            return attachRecordToJson(result);
         });
         switch (field.cardinality) {
             case "one":
@@ -1533,13 +1825,13 @@ function decodeTagged(value) {
         case "uuid": return expectBoundedString(input.value, 262_144);
         case "enum": return expectSymbol(input.name);
         case "date": return Number(expectDecimal(input.days_since_unix_epoch));
-        case "timestamp": return { seconds: BigInt(expectDecimal(input.seconds)), nanos: nonnegativeNumber(input.nanos) };
+        case "timestamp": return createTimestampValue(BigInt(expectDecimal(input.seconds)), nonnegativeNumber(input.nanos));
         case "bytes": return Uint8Array.from(Buffer.from(expectBoundedString(input.value, MAX_OUTPUT_BYTES), "base64"));
         case "decimal": return decodeDecimal(input);
-        case "money": return {
+        case "money": return attachMoneyToJson({
             currency: expectCurrency(input.currency),
             amount: decodeDecimal(exactObject(input.amount)),
-        };
+        });
         case "vector": return decodeVector(input.components, undefined);
         case "list":
             if (!Array.isArray(input.values))
@@ -1575,9 +1867,9 @@ function decodeDecimal(input) {
     if (coefficient.byteLength < 1 || coefficient.byteLength > 16)
         return fail();
     if (input.precision === undefined)
-        return { coefficientTwosComplement: coefficient, scale };
+        return attachDecimalToJson({ coefficientTwosComplement: coefficient, scale });
     const precision = positiveNumber(input.precision);
-    return { coefficientTwosComplement: coefficient, scale, precision };
+    return attachDecimalToJson({ coefficientTwosComplement: coefficient, scale, precision });
 }
 function decodePlain(value, schema) {
     if (schema.kind === "optional")
@@ -1596,7 +1888,7 @@ function decodePlain(value, schema) {
             return fail();
         for (const field of schema.fields)
             output[field.name] = decodePlain(input[field.name], field.schema);
-        return output;
+        return attachRecordToJson(output);
     }
     switch (schema.kind) {
         case "bool":
@@ -1625,8 +1917,9 @@ function decodePlain(value, schema) {
             break;
         case "timestamp": {
             const input = exactObject(value);
-            if (typeof input.seconds === "bigint" && Number.isInteger(input.nanos))
-                return value;
+            if (typeof input.seconds === "bigint" && Number.isInteger(input.nanos)) {
+                return createTimestampValue(input.seconds, input.nanos);
+            }
             break;
         }
         case "bytes":
@@ -1641,10 +1934,10 @@ function decodePlain(value, schema) {
             const currency = expectCurrency(input.currency);
             if (schema.currency !== undefined && currency !== schema.currency)
                 return fail();
-            return {
+            return attachMoneyToJson({
                 currency,
                 amount: normalizeDecodedDecimal(input.amount, schema.precision, schema.scale),
-            };
+            });
         }
         case "vector": return decodeVector(value, schema.dimension);
         default: break;
@@ -1659,11 +1952,11 @@ function normalizeDecodedDecimal(value, expectedPrecision, expectedScale) {
         || (expectedScale !== undefined && encoded.scale !== expectedScale))
         return fail();
     const precision = expectedPrecision ?? encoded.precision;
-    return {
+    return attachDecimalToJson({
         coefficientTwosComplement: input.coefficientTwosComplement,
         scale: encoded.scale,
         ...(precision === undefined ? {} : { precision }),
-    };
+    });
 }
 function decodeWire(value, schema) {
     if (schema.kind !== "record")
@@ -1876,7 +2169,7 @@ function encodeVectorBits(value, dimension) {
     });
 }
 function decodeVectorBits(value, dimension) {
-    if (!Array.isArray(value) || value.length !== dimension)
+    if (!Array.isArray(value) || dimension < 1 || dimension > 4_096 || value.length !== dimension)
         return fail();
     const float = new Float32Array(1);
     const bits = new Uint32Array(float.buffer);
@@ -1903,6 +2196,26 @@ function decodeVector(value, dimension) {
 }
 function decodeReactiveConsumerStatus(value) {
     const status = exactObject(value);
+    if (status.kind !== undefined) {
+        const kind = expectSymbol(status.kind);
+        if (kind === "protected") {
+            const progressCursor = expectBoundedString(status.progress_cursor, 512);
+            if (progressCursor.length < 1)
+                return fail();
+            return {
+                kind: "protected",
+                revision: 0n,
+                checkpoint: progressCursor,
+                progressCursor,
+                historyIncarnation: positiveBigInt(status.history_incarnation),
+                liveLeases: 0,
+                retries: 0,
+                deadLetters: 0,
+            };
+        }
+        if (kind !== "exact")
+            return fail();
+    }
     return {
         revision: positiveBigInt(status.revision),
         checkpoint: expectBoundedString(status.checkpoint, 64),
@@ -2031,6 +2344,122 @@ function signedTwosComplement(value) {
     }
     return fail();
 }
+function decodeSignedTwosComplement(bytes) {
+    if (bytes.byteLength < 1 || bytes.byteLength > 16)
+        return fail();
+    let value = 0n;
+    for (const byte of bytes) {
+        value = (value << 8n) | BigInt(byte);
+    }
+    if ((bytes[0] & 0x80) !== 0) {
+        value -= 1n << BigInt(bytes.byteLength * 8);
+    }
+    return value;
+}
+function coerceI64Input(value, errorMessage) {
+    let parsed;
+    if (typeof value === "bigint") {
+        parsed = value;
+    }
+    else if (typeof value === "number") {
+        if (!Number.isSafeInteger(value))
+            throw new Error(errorMessage);
+        parsed = BigInt(value);
+    }
+    else if (typeof value === "string" && /^-?(?:0|[1-9][0-9]*)$/.test(value)) {
+        parsed = BigInt(value);
+    }
+    else {
+        throw new Error(errorMessage);
+    }
+    if (parsed < -(1n << 63n) || parsed > (1n << 63n) - 1n) {
+        throw new Error(errorMessage);
+    }
+    return parsed;
+}
+function coerceU64Input(value, errorMessage) {
+    let parsed;
+    if (typeof value === "bigint") {
+        parsed = value;
+    }
+    else if (typeof value === "number") {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new Error(errorMessage);
+        parsed = BigInt(value);
+    }
+    else if (typeof value === "string" && /^(?:0|[1-9][0-9]*)$/.test(value)) {
+        parsed = BigInt(value);
+    }
+    else {
+        throw new Error(errorMessage);
+    }
+    if (parsed < 0n || parsed > (1n << 64n) - 1n) {
+        throw new Error(errorMessage);
+    }
+    return parsed;
+}
+function coerceTimestampInput(value, errorMessage) {
+    if (value instanceof Date) {
+        const ms = value.getTime();
+        if (!Number.isFinite(ms))
+            throw new Error(errorMessage);
+        const seconds = BigInt(Math.floor(ms / 1000));
+        const nanos = (((ms % 1000) + 1000) % 1000) * 1_000_000;
+        return { seconds, nanos };
+    }
+    if (typeof value === "string") {
+        const match = /^([+-]?\d{4,19})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|([+-])(\d{2}):(\d{2}))$/.exec(value);
+        if (match === null)
+            throw new Error(errorMessage);
+        const rawYear = match[1];
+        if (/^-0+$/.test(rawYear))
+            throw new Error(errorMessage);
+        const year = BigInt(rawYear);
+        const month = Number(match[2]);
+        const day = Number(match[3]);
+        const hour = Number(match[4]);
+        const minute = Number(match[5]);
+        const second = Number(match[6]);
+        if (month < 1
+            || month > 12
+            || day < 1
+            || day > daysInGregorianMonth(year, month)
+            || hour > 23
+            || minute > 59
+            || second > 59) {
+            throw new Error(errorMessage);
+        }
+        let offsetSeconds = 0n;
+        if (match[8] !== "Z") {
+            const offsetSign = match[9] === "-" ? -1n : 1n;
+            const offsetHours = Number(match[10]);
+            const offsetMinutes = Number(match[11]);
+            if (offsetHours > 23 || offsetMinutes > 59) {
+                throw new Error(errorMessage);
+            }
+            offsetSeconds = offsetSign * BigInt((offsetHours * 60 + offsetMinutes) * 60);
+        }
+        const seconds = daysFromCivil(year, month, day) * 86400n + BigInt(hour * 3600 + minute * 60 + second) - offsetSeconds;
+        if (seconds < -(1n << 63n) || seconds > (1n << 63n) - 1n) {
+            throw new Error(errorMessage);
+        }
+        const nanos = match[7] === undefined ? 0 : Number(match[7].padEnd(9, "0"));
+        if (!Number.isInteger(nanos) || nanos < 0 || nanos > 999_999_999) {
+            throw new Error(errorMessage);
+        }
+        return { seconds, nanos };
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const input = value;
+        const seconds = coerceI64Input(input.seconds, errorMessage);
+        const rawNanos = input.nanos === undefined ? 0 : input.nanos;
+        if (typeof rawNanos !== "number" || !Number.isInteger(rawNanos) || rawNanos < 0 || rawNanos > 999_999_999) {
+            throw new Error(errorMessage);
+        }
+        return { seconds, nanos: rawNanos };
+    }
+    throw new Error(errorMessage);
+}
 function positiveNumber(value) {
     const number = typeof value === "string" ? Number(expectDecimal(value)) : value;
     if (!Number.isSafeInteger(number) || number < 1)
@@ -2051,4 +2480,4 @@ function positiveBigInt(value) {
 function fail() {
     throw new Error("invalid RiffDB application response");
 }
-export { DRIVER_ERROR_REGISTRY_HASH, DRIVER_PROTOCOL_VERSION, DRIVER_VALUE_REGISTRY_HASH, DriverApplicationError, DriverApplicationTransport, } from "./driver.js";
+export { DRIVER_ERROR_REGISTRY_HASH, DRIVER_PROTOCOL_VERSION, DRIVER_VALUE_REGISTRY_HASH, DriverApplicationError, DriverApplicationTransport, resolveTransportOptionsFromEnv, } from "./driver.js";

package/package.json

@@ -1 +1 @@
-{"description":"First-party application runtime for the Rust-owned RiffDB driver host","engines":{"node":">=22"},"exports":{".":"./dist/index.js","./operator":"./dist/operator.js"},"files":["dist","README.md","conformance-manifest-v1.json"],"license":"MIT OR Apache-2.0","name":"@riffdb/client","repository":{"type":"git","url":"git+https://github.com/riffdb/riffdb.git"},"type":"module","types":"./dist/index.d.ts","version":"0.2.0"}
+{"description":"First-party application runtime for the Rust-owned RiffDB driver host","engines":{"node":">=22"},"exports":{".":"./dist/index.js","./operator":"./dist/operator.js"},"files":["dist","README.md","conformance-manifest-v1.json"],"license":"MIT OR Apache-2.0","name":"@riffdb/client","repository":{"type":"git","url":"git+https://github.com/riffdb/riffdb.git"},"type":"module","types":"./dist/index.d.ts","version":"0.2.1"}