@riffdb/client 0.2.0 → 0.2.2

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.2
+npm install @riffdb/client@0.2.2
 ```
 
 ## 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;
@@ -72,8 +84,18 @@ export interface DriverApplicationIdentity {
 }
 export interface DriverApplicationTransportOptions {
     readonly socketPath: string;
-    readonly identity: DriverApplicationIdentity;
+    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;
+    readonly env?: Readonly<Record<string, string | undefined>>;
 }
 export interface DriverOperation {
     readonly name: string;
@@ -163,9 +185,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

@@ -61,28 +61,62 @@ export class DriverApplicationError extends Error {
  * surface. Those semantics remain owned by the Rust host.
  */
 export class DriverApplicationTransport {
+    #socketPath;
     #socket;
     #identity;
+    #resolvedIdentity;
     #tenant;
     #requestPrefix;
     #pending = new Map();
-    #input = Buffer.alloc(0);
+    #inputChunks = [];
+    #inputLength = 0;
     #nextRequest = 1;
     #closed = false;
-    constructor(socket, identity, tenant) {
+    #disconnected = false;
+    #reconnecting;
+    constructor(socketPath, socket, identity, tenant) {
+        this.#socketPath = socketPath;
         this.#socket = socket;
         this.#identity = identity;
         this.#tenant = tenant;
         nextSession = nextSession === Number.MAX_SAFE_INTEGER ? 1 : nextSession + 1;
         this.#requestPrefix = `ts.${process.pid}.${nextSession}`;
-        socket.on("data", (chunk) => this.#receive(chunk));
-        socket.on("error", () => this.#fail(new Error("RiffDB driver session failed")));
-        socket.on("close", () => this.#fail(new Error("RiffDB driver session closed")));
+        this.#attachSocket(socket);
+    }
+    #attachSocket(socket) {
+        socket.on("data", (chunk) => {
+            if (this.#socket !== socket)
+                return;
+            this.#receive(chunk);
+        });
+        socket.on("error", () => {
+            if (this.#socket !== socket)
+                return;
+            this.#disconnected = true;
+            this.#inputChunks.length = 0;
+            this.#inputLength = 0;
+            this.#fail(new Error("RiffDB driver session failed"));
+        });
+        socket.on("close", () => {
+            if (this.#socket !== socket)
+                return;
+            this.#disconnected = true;
+            this.#inputChunks.length = 0;
+            this.#inputLength = 0;
+            this.#fail(new Error("RiffDB driver session closed"));
+        });
     }
     /** Returns the bound tenant identifier when this session is tenant-scoped. */
     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);
@@ -92,7 +126,7 @@ export class DriverApplicationTransport {
             socket.once("connect", () => { socket.off("error", onError); resolve(); });
             socket.once("error", onError);
         });
-        const transport = new DriverApplicationTransport(socket, options.identity, tenant);
+        const transport = new DriverApplicationTransport(options.socketPath, socket, options.identity ?? {}, tenant);
         try {
             await transport.#handshake();
             return transport;
@@ -102,9 +136,18 @@ export class DriverApplicationTransport {
             throw error;
         }
     }
+    static async connectFromEnv(options = {}) {
+        return DriverApplicationTransport.connect(resolveTransportOptionsFromEnv(options));
+    }
     async invoke(operation, input, options = {}) {
         validateOperation(operation);
         validateDriverRecord(input);
+        const lowered = lowerOptions(options);
+        if (options.signal?.aborted)
+            throw new Error("RiffDB driver request aborted");
+        if (this.#disconnected || this.#socket.destroyed) {
+            await this.#ensureConnected();
+        }
         const requestId = this.#requestId("invoke");
         const response = await this.#request({
             type: "invoke",
@@ -112,7 +155,7 @@ export class DriverApplicationTransport {
             operation: operation.name,
             input_schema_hash: operation.inputSchemaHash,
             input,
-            options: lowerOptions(options),
+            options: lowered,
         }, requestId, options.signal);
         return decodeResult(response);
     }
@@ -127,6 +170,12 @@ export class DriverApplicationTransport {
         }
         for (const input of items)
             validateDriverRecord(input);
+        const lowered = lowerOptions(options);
+        if (options.signal?.aborted)
+            throw new Error("RiffDB driver request aborted");
+        if (this.#disconnected || this.#socket.destroyed) {
+            await this.#ensureConnected();
+        }
         const requestId = this.#requestId("batch");
         const response = await this.#request({
             type: "batch",
@@ -136,15 +185,16 @@ export class DriverApplicationTransport {
             items,
             concurrency,
             checkpoint,
-            options: lowerOptions(options),
+            options: lowered,
         }, 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() {
         if (this.#closed)
             return;
         this.#closed = true;
+        this.#disconnected = true;
         this.#fail(new Error("RiffDB driver session closed"));
         await new Promise((resolve) => {
             if (this.#socket.destroyed) {
@@ -154,38 +204,121 @@ export class DriverApplicationTransport {
             this.#socket.end(resolve);
         });
     }
+    async #ensureConnected() {
+        if (this.#closed)
+            throw new Error("RiffDB driver session closed");
+        if (!this.#disconnected && !this.#socket.destroyed)
+            return;
+        if (this.#reconnecting !== undefined) {
+            await this.#reconnecting;
+            return;
+        }
+        const task = (async () => {
+            const socket = createConnection({ path: this.#socketPath });
+            await new Promise((resolve, reject) => {
+                const onError = () => reject(new Error("RiffDB driver session failed"));
+                socket.once("connect", () => { socket.off("error", onError); resolve(); });
+                socket.once("error", onError);
+            });
+            if (this.#closed) {
+                socket.destroy();
+                throw new Error("RiffDB driver session closed");
+            }
+            this.#socket = socket;
+            this.#inputChunks.length = 0;
+            this.#inputLength = 0;
+            this.#disconnected = false;
+            this.#attachSocket(socket);
+            try {
+                await this.#handshake();
+            }
+            catch (error) {
+                this.#disconnected = true;
+                socket.destroy();
+                throw error;
+            }
+        })();
+        this.#reconnecting = task;
+        try {
+            await task;
+        }
+        finally {
+            if (this.#reconnecting === task) {
+                this.#reconnecting = undefined;
+            }
+        }
+    }
     async #handshake() {
         const requestId = this.#requestId("handshake");
         const identity = this.#identity;
+        const manifestHash = identity.applicationManifestHash ?? "";
+        const catalogHash = identity.operationCatalogHash ?? "";
+        const contractLineage = identity.contractLineage ?? "";
+        const contractVersion = identity.contractVersion ?? 0n;
+        const contractBundleHash = identity.contractBundleHash ?? "";
+        const database = identity.database ?? "";
+        const role = identity.role ?? "";
+        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,
-            contract_lineage: identity.contractLineage,
-            contract_version: identity.contractVersion,
-            contract_bundle_hash: identity.contractBundleHash,
+            application_manifest_hash: manifestHash,
+            operation_catalog_hash: catalogHash,
+            contract_lineage: contractLineage,
+            contract_version: contractVersion,
+            contract_bundle_hash: contractBundleHash,
             value_registry_hash: DRIVER_VALUE_REGISTRY_HASH,
             error_registry_hash: DRIVER_ERROR_REGISTRY_HASH,
-            database: identity.database,
-            role: identity.role,
-            role_definition_hash: identity.roleDefinitionHash,
-            remote_identity_hash: identity.remoteIdentityHash,
+            database,
+            role,
+            role_definition_hash: roleDefinitionHash,
+            remote_identity_hash: remoteIdentityHash,
         }, requestId);
+        const resolvedContractVersion = requiredPositiveBigInt(response.contract_version);
         if (response.type !== "handshake"
             || response.protocol_version !== DRIVER_PROTOCOL_VERSION
-            || response.application_manifest_hash !== identity.applicationManifestHash
-            || response.operation_catalog_hash !== identity.operationCatalogHash
-            || response.contract_lineage !== identity.contractLineage
-            || requiredPositiveBigInt(response.contract_version) !== identity.contractVersion
-            || response.contract_bundle_hash !== identity.contractBundleHash
-            || response.database !== identity.database
-            || response.role !== identity.role
-            || response.role_definition_hash !== identity.roleDefinitionHash
-            || response.remote_identity_hash !== identity.remoteIdentityHash) {
+            || 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)
+            || typeof response.contract_lineage !== "string"
+            || !SYMBOL.test(response.contract_lineage)
+            || (contractLineage !== "" && response.contract_lineage !== contractLineage)
+            || (contractVersion !== 0n && resolvedContractVersion !== contractVersion)
+            || typeof response.contract_bundle_hash !== "string"
+            || !HASH.test(response.contract_bundle_hash)
+            || (contractBundleHash !== "" && response.contract_bundle_hash !== contractBundleHash)
+            || typeof response.database !== "string"
+            || !SYMBOL.test(response.database)
+            || (database !== "" && response.database !== database)
+            || typeof response.role !== "string"
+            || !SYMBOL.test(response.role)
+            || (role !== "" && response.role !== role)
+            || 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: response.contract_lineage,
+            contractVersion: resolvedContractVersion,
+            contractBundleHash: response.contract_bundle_hash,
+            database: response.database,
+            role: response.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 +363,40 @@ 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.#closed = true;
+                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.#closed = true;
+                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.#closed = true;
+                this.#inputChunks.length = 0;
+                this.#inputLength = 0;
                 this.#fail(new Error("RiffDB driver returned an invalid request identity"));
                 this.#socket.destroy();
                 return;
@@ -266,6 +408,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 +891,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 +930,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,9 +970,11 @@ function decodeError(response) {
         ...(incidentId === undefined ? {} : { incidentId }),
     });
 }
+const ENV_RESOLVED = Symbol("riffdb.envResolved");
 function resolveTransportTenant(options) {
-    const envTenant = process.env.RIFFDB_TENANT;
-    const candidate = options.tenant ?? options.identity.tenant ?? (envTenant && envTenant.length > 0 ? envTenant : undefined);
+    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;
     if (typeof candidate !== "string" || candidate.length < 1 || candidate.length > 128 || !/^[\x21-\x7e]+$/.test(candidate)) {
@@ -750,21 +982,103 @@ 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 envSource = options.env ?? process.env;
+    const readEnv = (suffix) => {
+        for (const candidatePrefix of candidatePrefixes) {
+            const raw = envSource[`${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") {
+        if (!/^[1-9][0-9]*$/.test(rawVersion)) {
+            throw new Error("invalid RiffDB driver identity");
+        }
+        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 (identity === undefined)
+        return;
     for (const value of [
+        identity.contractBundleHash,
         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");
+        }
+    }
+    for (const value of [identity.database, identity.contractLineage, identity.role]) {
+        if (value !== undefined && value !== "" && !SYMBOL.test(value)) {
+            throw new Error("invalid RiffDB driver identity");
+        }
     }
-    if (!SYMBOL.test(identity.contractLineage) || !SYMBOL.test(identity.database)
-        || !SYMBOL.test(identity.role) || identity.contractVersion < 1n
-        || identity.contractVersion > 18446744073709551615n) {
+    if (identity.contractVersion !== undefined
+        && identity.contractVersion !== 0n
+        && (identity.contractVersion < 1n || identity.contractVersion > 18446744073709551615n)) {
         throw new Error("invalid RiffDB driver identity");
     }
 }