@tinycloud/sdk-services 2.6.3 → 2.7.0-beta.4

package/dist/index.d.cts

@@ -1,11 +1,13 @@
-import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, T as TelemetryConfig, c as IService, E as EventHandler, d as ServiceError, e as Result, B as BaseService, f as StorageQuotaInfo } from './BaseService-BdRvNm2s.cjs';
-export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './BaseService-BdRvNm2s.cjs';
+import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-DAY1O1kW.cjs';
+export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-DAY1O1kW.cjs';
 import { z } from 'zod';
+import { B as BaseService } from './BaseService-BwBU5CQ4.cjs';
 import { IKVService } from './kv/index.cjs';
 export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.cjs';
 export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLMigrations, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLMigrations, SQLService, SQLServiceConfig, SqlMigration, SqlMigrationApplyOptions, SqlMigrationApplyResponse, SqlStatement, SqlValue } from './sql/index.cjs';
 import { IEncryptionService, DecryptCapabilityProof } from './encryption/index.cjs';
 export { BuildCanonicalDecryptRequestInput, BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, CanonicalDecryptRequest, CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, DecryptTransport, DiscoverNetworkInput, DiscoveredNetwork, DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, EncryptToNetworkInput, EncryptToNetworkOptions, EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionErrorInput, EncryptionService, EncryptionServiceConfig, InlineEncryptedEnvelope, Json, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, NodeDescriptorFetcher, ParsedNetworkId, RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, SignedReceiverKeyInput, VerifyDecryptResponseInput, WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize as canonicalizeEncryptionJson, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse } from './encryption/index.cjs';
+export { DecryptTransportResponseError } from '@tinycloud/sdk-services/internal/decrypt-transport-response-error';
 
 type TinyCloudDebugLevel = "debug";
 interface TinyCloudDebugEvent {
@@ -491,18 +493,18 @@ declare const ServiceResponseEventSchema: z.ZodObject<{
     durationMs: z.ZodOptional<z.ZodNumber>;
     status: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    service: string;
+    duration: number;
     ok: boolean;
+    service: string;
     action: string;
-    duration: number;
     durationMs?: number | undefined;
     status?: number | undefined;
     span?: string | undefined;
 }, {
-    service: string;
+    duration: number;
     ok: boolean;
+    service: string;
     action: string;
-    duration: number;
     durationMs?: number | undefined;
     status?: number | undefined;
     span?: string | undefined;
@@ -660,8 +662,8 @@ declare const TelemetrySpanEventSchema: z.ZodObject<{
         cause?: unknown;
         meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     } | undefined;
-    service?: string | undefined;
     status?: number | undefined;
+    service?: string | undefined;
     action?: string | undefined;
 }, {
     durationMs: number;
@@ -674,8 +676,8 @@ declare const TelemetrySpanEventSchema: z.ZodObject<{
         cause?: unknown;
         meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     } | undefined;
-    service?: string | undefined;
     status?: number | undefined;
+    service?: string | undefined;
     action?: string | undefined;
 }>;
 type TelemetrySpanEventType = z.infer<typeof TelemetrySpanEventSchema>;
@@ -904,6 +906,7 @@ declare class ServiceContext implements IServiceContext {
     private _services;
     private _eventHandlers;
     private _abortController;
+    private _retired;
     private readonly _invoke;
     private readonly _invokeAny?;
     private readonly _fetch;
@@ -987,6 +990,12 @@ declare class ServiceContext implements IServiceContext {
      * Get the abort signal for cancelling operations.
      */
     get abortSignal(): AbortSignal;
+    /**
+     * Permanently retire this graph after its owner installs a replacement.
+     * Unlike `abort()`, retirement never creates a fresh controller, so captured
+     * services cannot resume calls under a superseded session.
+     */
+    retire(): void;
     /**
      * Abort all pending operations and notify services.
      * Creates a new AbortController for future operations.
@@ -1001,10 +1010,16 @@ declare class ServiceContext implements IServiceContext {
      */
     get retryPolicy(): RetryPolicy;
     private wrapInvoke;
+    private assertActive;
     private wrapInvokeAny;
     private wrapFetch;
+    private combineSignals;
 }
 
+/** Validate one structured node permission hint without accepting raw errors. */
+declare function parsePermissionHint(value: unknown): PermissionHint | undefined;
+/** Extract only a validated structured hint from an SDK-owned error body. */
+declare function parsePermissionHintFromErrorText(text: string): PermissionHint | undefined;
 /**
  * Create a service error for authentication required.
  */
@@ -1601,6 +1616,32 @@ interface VaultEntry<T> {
     /** Key ID used for encryption */
     keyId: string;
 }
+/**
+ * Safe classification for a network-encrypted vault read.
+ *
+ * Failure variants intentionally contain no node response, encrypted envelope,
+ * plaintext, or key material. Consumers that need to distinguish an authorized
+ * absence from a failed read should use this instead of {@link IDataVaultService.get}.
+ */
+type VaultNetworkReadResult<T> = {
+    status: "ok";
+    entry: VaultEntry<T>;
+} | {
+    status: "not_found";
+} | {
+    status: "node_unreachable";
+} | {
+    status: "permission_required";
+    hint: PermissionHint;
+} | {
+    status: "read_failed";
+} | {
+    status: "corrupt_envelope";
+} | {
+    status: "decrypt_failed";
+} | {
+    status: "invalid_payload";
+};
 /**
  * Structured error codes for vault operations.
  */
@@ -1969,6 +2010,14 @@ declare class DataVaultService extends BaseService implements IDataVaultService
     onSignOut(): void;
     private putNetworkEncrypted;
     private getNetworkEncrypted;
+    /**
+     * Read a network-encrypted entry while preserving safe failure phases.
+     *
+     * Unlike {@link getNetworkEncrypted}, this is intentionally message-free so
+     * an operation layer can distinguish an authorized absence from a failed
+     * read without receiving node, envelope, plaintext, or key material.
+     */
+    readNetworkEncrypted<T = unknown>(key: string, options?: VaultGetOptions<T>): Promise<VaultNetworkReadResult<T>>;
     private headNetworkEncrypted;
     /**
      * Encrypt and store a value at the given key.
@@ -2151,4 +2200,4 @@ declare class SecretsService implements ISecretsService {
     list(options?: SecretScopeOptions): Promise<Result<string[], SecretsError>>;
 }
 
-export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, networkError, notFoundError, parseAuthError, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };
+export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, networkError, notFoundError, parseAuthError, parsePermissionHint, parsePermissionHintFromErrorText, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };

package/dist/index.d.ts

@@ -1,11 +1,13 @@
-import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, T as TelemetryConfig, c as IService, E as EventHandler, d as ServiceError, e as Result, B as BaseService, f as StorageQuotaInfo } from './BaseService-BdRvNm2s.js';
-export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './BaseService-BdRvNm2s.js';
+import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-DAY1O1kW.js';
+export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-DAY1O1kW.js';
 import { z } from 'zod';
+import { B as BaseService } from './BaseService-CnPTKR5G.js';
 import { IKVService } from './kv/index.js';
 export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.js';
 export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLMigrations, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLMigrations, SQLService, SQLServiceConfig, SqlMigration, SqlMigrationApplyOptions, SqlMigrationApplyResponse, SqlStatement, SqlValue } from './sql/index.js';
 import { IEncryptionService, DecryptCapabilityProof } from './encryption/index.js';
 export { BuildCanonicalDecryptRequestInput, BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, CanonicalDecryptRequest, CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, DecryptTransport, DiscoverNetworkInput, DiscoveredNetwork, DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, EncryptToNetworkInput, EncryptToNetworkOptions, EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionErrorInput, EncryptionService, EncryptionServiceConfig, InlineEncryptedEnvelope, Json, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, NodeDescriptorFetcher, ParsedNetworkId, RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, SignedReceiverKeyInput, VerifyDecryptResponseInput, WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize as canonicalizeEncryptionJson, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse } from './encryption/index.js';
+export { DecryptTransportResponseError } from '@tinycloud/sdk-services/internal/decrypt-transport-response-error';
 
 type TinyCloudDebugLevel = "debug";
 interface TinyCloudDebugEvent {
@@ -491,18 +493,18 @@ declare const ServiceResponseEventSchema: z.ZodObject<{
     durationMs: z.ZodOptional<z.ZodNumber>;
     status: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    service: string;
+    duration: number;
     ok: boolean;
+    service: string;
     action: string;
-    duration: number;
     durationMs?: number | undefined;
     status?: number | undefined;
     span?: string | undefined;
 }, {
-    service: string;
+    duration: number;
     ok: boolean;
+    service: string;
     action: string;
-    duration: number;
     durationMs?: number | undefined;
     status?: number | undefined;
     span?: string | undefined;
@@ -660,8 +662,8 @@ declare const TelemetrySpanEventSchema: z.ZodObject<{
         cause?: unknown;
         meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     } | undefined;
-    service?: string | undefined;
     status?: number | undefined;
+    service?: string | undefined;
     action?: string | undefined;
 }, {
     durationMs: number;
@@ -674,8 +676,8 @@ declare const TelemetrySpanEventSchema: z.ZodObject<{
         cause?: unknown;
         meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     } | undefined;
-    service?: string | undefined;
     status?: number | undefined;
+    service?: string | undefined;
     action?: string | undefined;
 }>;
 type TelemetrySpanEventType = z.infer<typeof TelemetrySpanEventSchema>;
@@ -904,6 +906,7 @@ declare class ServiceContext implements IServiceContext {
     private _services;
     private _eventHandlers;
     private _abortController;
+    private _retired;
     private readonly _invoke;
     private readonly _invokeAny?;
     private readonly _fetch;
@@ -987,6 +990,12 @@ declare class ServiceContext implements IServiceContext {
      * Get the abort signal for cancelling operations.
      */
     get abortSignal(): AbortSignal;
+    /**
+     * Permanently retire this graph after its owner installs a replacement.
+     * Unlike `abort()`, retirement never creates a fresh controller, so captured
+     * services cannot resume calls under a superseded session.
+     */
+    retire(): void;
     /**
      * Abort all pending operations and notify services.
      * Creates a new AbortController for future operations.
@@ -1001,10 +1010,16 @@ declare class ServiceContext implements IServiceContext {
      */
     get retryPolicy(): RetryPolicy;
     private wrapInvoke;
+    private assertActive;
     private wrapInvokeAny;
     private wrapFetch;
+    private combineSignals;
 }
 
+/** Validate one structured node permission hint without accepting raw errors. */
+declare function parsePermissionHint(value: unknown): PermissionHint | undefined;
+/** Extract only a validated structured hint from an SDK-owned error body. */
+declare function parsePermissionHintFromErrorText(text: string): PermissionHint | undefined;
 /**
  * Create a service error for authentication required.
  */
@@ -1601,6 +1616,32 @@ interface VaultEntry<T> {
     /** Key ID used for encryption */
     keyId: string;
 }
+/**
+ * Safe classification for a network-encrypted vault read.
+ *
+ * Failure variants intentionally contain no node response, encrypted envelope,
+ * plaintext, or key material. Consumers that need to distinguish an authorized
+ * absence from a failed read should use this instead of {@link IDataVaultService.get}.
+ */
+type VaultNetworkReadResult<T> = {
+    status: "ok";
+    entry: VaultEntry<T>;
+} | {
+    status: "not_found";
+} | {
+    status: "node_unreachable";
+} | {
+    status: "permission_required";
+    hint: PermissionHint;
+} | {
+    status: "read_failed";
+} | {
+    status: "corrupt_envelope";
+} | {
+    status: "decrypt_failed";
+} | {
+    status: "invalid_payload";
+};
 /**
  * Structured error codes for vault operations.
  */
@@ -1969,6 +2010,14 @@ declare class DataVaultService extends BaseService implements IDataVaultService
     onSignOut(): void;
     private putNetworkEncrypted;
     private getNetworkEncrypted;
+    /**
+     * Read a network-encrypted entry while preserving safe failure phases.
+     *
+     * Unlike {@link getNetworkEncrypted}, this is intentionally message-free so
+     * an operation layer can distinguish an authorized absence from a failed
+     * read without receiving node, envelope, plaintext, or key material.
+     */
+    readNetworkEncrypted<T = unknown>(key: string, options?: VaultGetOptions<T>): Promise<VaultNetworkReadResult<T>>;
     private headNetworkEncrypted;
     /**
      * Encrypt and store a value at the given key.
@@ -2151,4 +2200,4 @@ declare class SecretsService implements ISecretsService {
     list(options?: SecretScopeOptions): Promise<Result<string[], SecretsError>>;
 }
 
-export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, networkError, notFoundError, parseAuthError, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };
+export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, networkError, notFoundError, parseAuthError, parsePermissionHint, parsePermissionHintFromErrorText, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };