@tinycloud/sdk-core 2.11.0-beta.3 → 2.11.0-beta.5

package/dist/index.d.cts

@@ -2487,6 +2487,13 @@ interface AccountSpace {
     updatedAt?: string;
     expiresAt?: Date;
 }
+interface RegisterBatchSuccess {
+    spaces: AccountSpace[];
+    /** Present iff the batch write failed ambiguously and per-space
+     *  reconciliation recovered it. The original batch error verbatim, so
+     *  callers can record the degradation structurally (TC-361). */
+    recoveredFromBatchError?: ServiceError;
+}
 interface AccountDelegation {
     cid: string;
     direction: "granted" | "received";
@@ -2591,6 +2598,17 @@ declare class AccountService {
         list: (options?: AccountSpaceListOptions) => Promise<Result<AccountSpace[]>>;
         get: (spaceId: string) => Promise<Result<AccountSpace>>;
         register: (space: SpaceInfo | AccountSpace) => Promise<Result<AccountSpace>>;
+        /**
+         * Register multiple spaces in one KV batch write + one multi-row index
+         * write, instead of one `register()` round trip per space (TC-373).
+         *
+         * The stored records are computed exactly once and reused for both the
+         * batch attempt and any reconciliation below, so a fallback never mints a
+         * fresh timestamp for a space that already has a written record — a
+         * second `spaceRecordFromInput` call would produce a new content hash and
+         * leave the first attempt's blocks orphaned.
+         */
+        registerBatch: (spaces: readonly (SpaceInfo | AccountSpace)[]) => Promise<Result<RegisterBatchSuccess>>;
         syncAccessible: () => Promise<Result<AccountSpace[]>>;
         remove: (spaceId: string) => Promise<Result<void>>;
     };
@@ -2623,6 +2641,16 @@ declare class AccountService {
     private deleteApplicationIndex;
     private upsertSpaceIndexQuietly;
     private upsertSpaceIndex;
+    private upsertSpacesIndexQuietly;
+    /**
+     * Upsert multiple space index rows in ONE multi-row `INSERT OR REPLACE`
+     * statement (TC-373), rather than one statement per space. This matters
+     * because `IDatabaseHandle.batch()` executes its statement list as a plain
+     * loop, not a single database transaction — an N-statement batch is not
+     * atomic. A single multi-row INSERT is one SQLite statement, so it applies
+     * atomically: all rows or none.
+     */
+    private upsertSpacesIndex;
     private deleteSpaceIndexQuietly;
     private deleteSpaceIndex;
     private resolveSpace;
@@ -2776,7 +2804,7 @@ interface LocationRecord extends LocationRecordPayload {
 type LocationSource = "explicit" | "local-loopback" | "local-link" | "blockchain" | "centralized" | "fallback";
 declare const DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
 declare const DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
-/** Default local loopback node URL probed before registry/fallback resolution. */
+/** Conventional local loopback node URL. Probed only when explicitly configured. */
 declare const DEFAULT_LOCAL_NODE_URL = "http://127.0.0.1:8000";
 /** Probe timeout for the local loopback candidate. No retries. */
 declare const LOCAL_LOOPBACK_PROBE_TIMEOUT_MS = 250;
@@ -2863,7 +2891,7 @@ interface DiscoverLocalTinyCloudNodeOptions {
     subject?: string;
     /** Enable local-node auto-discovery. Default true. */
     autoDiscoverLocalNode?: boolean;
-    /** Local loopback node URL to probe. Default http://127.0.0.1:8000. */
+    /** Local loopback node URL to probe. Omit to avoid probing loopback. */
     localNodeUrl?: string;
     /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
     localLinkName?: string;
@@ -2897,12 +2925,12 @@ interface ResolveTinyCloudHostsOptions {
     /** Verify centralized/blockchain record signatures. Default true. */
     verifyRecords?: boolean;
     /**
-     * Probe for a locally-running TinyCloud node before falling back to
-     * registry/hosted resolution. Default true. Setting false restores the
-     * exact pre-TC-106 resolution order (registry → fallback).
+     * Probe configured and registered local TinyCloud node endpoints before
+     * falling back to registry/hosted resolution. Default true. The loopback
+     * URL is probed only when `localNodeUrl` is explicitly configured.
      */
     autoDiscoverLocalNode?: boolean;
-    /** Local loopback node URL to probe. Default http://127.0.0.1:8000. */
+    /** Local loopback node URL to probe. Omit to avoid probing loopback. */
     localNodeUrl?: string;
     /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
     localLinkName?: string;
@@ -2988,4 +3016,4 @@ declare const EXPIRY: {
 declare const DEFAULT_SIGNED_READ_URL_EXPIRY_MS: number;
 type ExpiryTier = keyof typeof EXPIRY;
 
-export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, type AccountApplication, type AccountApplicationListOptions, type AccountApplicationRegisterOptions, type AccountDelegation, type AccountDelegationListOptions, AccountDelegationPage, AccountDelegationQueryOptions, type AccountDelegationRevokeOptions, type AccountIndexEnsureResult, type AccountIndexRebuildResult, type AccountIndexStatus, type AccountIndexedReadOptions, AccountService, type AccountServiceConfig, type AccountSpace, type AccountSpaceListOptions, type AccountStatus, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CanonicalAddress, type CanonicalParsedNetworkId, CaveatedDelegationUnsupportedError, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, CreateDelegationParams, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_KNOWLEDGE_ROOT, DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY, DEFAULT_LOCAL_NODE_URL, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, Delegation, DelegationManager, DelegationRevocationReceipt, type DidCacheKeyOptions, type DidEqualsOptions, type DiscoverLocalTinyCloudNodeOptions, type DiscoveredLocalTinyCloudNode, ENCRYPTION_MANIFEST_SPACE, ENCRYPTION_PERMISSION_SERVICE, EXPIRY, type EnsData, EnsDataSchema, type EventEmitterStrategy, type ExpiryTier, type Extension, GenerateShareParams, ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, IdentityParseError, LOCAL_LINK_HOST_SUFFIX, LOCAL_LINK_PROBE_TIMEOUT_MS, LOCAL_LOOPBACK_PROBE_TIMEOUT_MS, type LocalNodeIdentityStore, type LocationCandidate, type LocationCandidateInput, type LocationRecord, type LocationRecordPayload, type LocationRecordSigner, LocationRecordValidationError, type LocationResolutionAttempt, type LocationSource, type Manifest, type ManifestDefaults, type ManifestKnowledge, type ManifestRegistryRecord, type ManifestSecretActions, ManifestValidationError, type NodeInfo, type OpenKeyCallbackStrategy, type OpenKeySigningRequestBody, type OpenKeySigningResponseBody, type OpenKeySigningStrategyOptions, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedSessionProof, type PersistedTinyCloudSession, type PkhDidParts, ProtocolMismatchError, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SECRETS_SPACE, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, ShareLink, type SignCallback, type SignInOptions, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceAbilitiesMap, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, SpaceInfo, SpaceService, type SpaceServiceConfig, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, VAULT_PERMISSION_SERVICE, type ValidatedPersistedSessionProof, type ValidationError, VersionCheckError, type WasmRecapEntry, type WebStorageLike, actionContains, activateSessionWithHost, addressStorageKey, applyPrefix, buildSpaceUri, canonicalLocationPayload, canonicalizeAddress, canonicalizeDid, canonicalizeDidUrl, canonicalizeNetworkId, canonicalizeRecapCaveats, checkNodeInfo, composeManifestRequest, createInMemoryLocalNodeIdentityStore, createLocalStorageLocalNodeIdentityStore, createOpenKeyCallbackSigningStrategy, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, didCacheKey, didEquals, discoverLocalTinyCloudNode, expandActionShortNames, expandPermissionEntries, expandPermissionEntry, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, isEvmAddress, loadManifest, locationPayloadForRecord, makePkhSpaceId, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseCanonicalNetworkId, parseExpiry, parsePkhDid, parseRecapCapabilities, parseSpaceUri, pkhDid, principalDid, principalDidEquals, recapCaveatsEqual, resolveCloudLocation, resolveManifest, resolveManifestKnowledgeRoot, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyDidKeyEd25519Signature, verifyLocationRecord };
+export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, type AccountApplication, type AccountApplicationListOptions, type AccountApplicationRegisterOptions, type AccountDelegation, type AccountDelegationListOptions, AccountDelegationPage, AccountDelegationQueryOptions, type AccountDelegationRevokeOptions, type AccountIndexEnsureResult, type AccountIndexRebuildResult, type AccountIndexStatus, type AccountIndexedReadOptions, AccountService, type AccountServiceConfig, type AccountSpace, type AccountSpaceListOptions, type AccountStatus, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CanonicalAddress, type CanonicalParsedNetworkId, CaveatedDelegationUnsupportedError, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, CreateDelegationParams, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_KNOWLEDGE_ROOT, DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY, DEFAULT_LOCAL_NODE_URL, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, Delegation, DelegationManager, DelegationRevocationReceipt, type DidCacheKeyOptions, type DidEqualsOptions, type DiscoverLocalTinyCloudNodeOptions, type DiscoveredLocalTinyCloudNode, ENCRYPTION_MANIFEST_SPACE, ENCRYPTION_PERMISSION_SERVICE, EXPIRY, type EnsData, EnsDataSchema, type EventEmitterStrategy, type ExpiryTier, type Extension, GenerateShareParams, ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, IdentityParseError, LOCAL_LINK_HOST_SUFFIX, LOCAL_LINK_PROBE_TIMEOUT_MS, LOCAL_LOOPBACK_PROBE_TIMEOUT_MS, type LocalNodeIdentityStore, type LocationCandidate, type LocationCandidateInput, type LocationRecord, type LocationRecordPayload, type LocationRecordSigner, LocationRecordValidationError, type LocationResolutionAttempt, type LocationSource, type Manifest, type ManifestDefaults, type ManifestKnowledge, type ManifestRegistryRecord, type ManifestSecretActions, ManifestValidationError, type NodeInfo, type OpenKeyCallbackStrategy, type OpenKeySigningRequestBody, type OpenKeySigningResponseBody, type OpenKeySigningStrategyOptions, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedSessionProof, type PersistedTinyCloudSession, type PkhDidParts, ProtocolMismatchError, type RegisterBatchSuccess, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SECRETS_SPACE, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, ShareLink, type SignCallback, type SignInOptions, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceAbilitiesMap, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, SpaceInfo, SpaceService, type SpaceServiceConfig, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, VAULT_PERMISSION_SERVICE, type ValidatedPersistedSessionProof, type ValidationError, VersionCheckError, type WasmRecapEntry, type WebStorageLike, actionContains, activateSessionWithHost, addressStorageKey, applyPrefix, buildSpaceUri, canonicalLocationPayload, canonicalizeAddress, canonicalizeDid, canonicalizeDidUrl, canonicalizeNetworkId, canonicalizeRecapCaveats, checkNodeInfo, composeManifestRequest, createInMemoryLocalNodeIdentityStore, createLocalStorageLocalNodeIdentityStore, createOpenKeyCallbackSigningStrategy, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, didCacheKey, didEquals, discoverLocalTinyCloudNode, expandActionShortNames, expandPermissionEntries, expandPermissionEntry, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, isEvmAddress, loadManifest, locationPayloadForRecord, makePkhSpaceId, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseCanonicalNetworkId, parseExpiry, parsePkhDid, parseRecapCapabilities, parseSpaceUri, pkhDid, principalDid, principalDidEquals, recapCaveatsEqual, resolveCloudLocation, resolveManifest, resolveManifestKnowledgeRoot, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyDidKeyEd25519Signature, verifyLocationRecord };

package/dist/index.d.ts

@@ -2487,6 +2487,13 @@ interface AccountSpace {
     updatedAt?: string;
     expiresAt?: Date;
 }
+interface RegisterBatchSuccess {
+    spaces: AccountSpace[];
+    /** Present iff the batch write failed ambiguously and per-space
+     *  reconciliation recovered it. The original batch error verbatim, so
+     *  callers can record the degradation structurally (TC-361). */
+    recoveredFromBatchError?: ServiceError;
+}
 interface AccountDelegation {
     cid: string;
     direction: "granted" | "received";
@@ -2591,6 +2598,17 @@ declare class AccountService {
         list: (options?: AccountSpaceListOptions) => Promise<Result<AccountSpace[]>>;
         get: (spaceId: string) => Promise<Result<AccountSpace>>;
         register: (space: SpaceInfo | AccountSpace) => Promise<Result<AccountSpace>>;
+        /**
+         * Register multiple spaces in one KV batch write + one multi-row index
+         * write, instead of one `register()` round trip per space (TC-373).
+         *
+         * The stored records are computed exactly once and reused for both the
+         * batch attempt and any reconciliation below, so a fallback never mints a
+         * fresh timestamp for a space that already has a written record — a
+         * second `spaceRecordFromInput` call would produce a new content hash and
+         * leave the first attempt's blocks orphaned.
+         */
+        registerBatch: (spaces: readonly (SpaceInfo | AccountSpace)[]) => Promise<Result<RegisterBatchSuccess>>;
         syncAccessible: () => Promise<Result<AccountSpace[]>>;
         remove: (spaceId: string) => Promise<Result<void>>;
     };
@@ -2623,6 +2641,16 @@ declare class AccountService {
     private deleteApplicationIndex;
     private upsertSpaceIndexQuietly;
     private upsertSpaceIndex;
+    private upsertSpacesIndexQuietly;
+    /**
+     * Upsert multiple space index rows in ONE multi-row `INSERT OR REPLACE`
+     * statement (TC-373), rather than one statement per space. This matters
+     * because `IDatabaseHandle.batch()` executes its statement list as a plain
+     * loop, not a single database transaction — an N-statement batch is not
+     * atomic. A single multi-row INSERT is one SQLite statement, so it applies
+     * atomically: all rows or none.
+     */
+    private upsertSpacesIndex;
     private deleteSpaceIndexQuietly;
     private deleteSpaceIndex;
     private resolveSpace;
@@ -2776,7 +2804,7 @@ interface LocationRecord extends LocationRecordPayload {
 type LocationSource = "explicit" | "local-loopback" | "local-link" | "blockchain" | "centralized" | "fallback";
 declare const DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
 declare const DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
-/** Default local loopback node URL probed before registry/fallback resolution. */
+/** Conventional local loopback node URL. Probed only when explicitly configured. */
 declare const DEFAULT_LOCAL_NODE_URL = "http://127.0.0.1:8000";
 /** Probe timeout for the local loopback candidate. No retries. */
 declare const LOCAL_LOOPBACK_PROBE_TIMEOUT_MS = 250;
@@ -2863,7 +2891,7 @@ interface DiscoverLocalTinyCloudNodeOptions {
     subject?: string;
     /** Enable local-node auto-discovery. Default true. */
     autoDiscoverLocalNode?: boolean;
-    /** Local loopback node URL to probe. Default http://127.0.0.1:8000. */
+    /** Local loopback node URL to probe. Omit to avoid probing loopback. */
     localNodeUrl?: string;
     /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
     localLinkName?: string;
@@ -2897,12 +2925,12 @@ interface ResolveTinyCloudHostsOptions {
     /** Verify centralized/blockchain record signatures. Default true. */
     verifyRecords?: boolean;
     /**
-     * Probe for a locally-running TinyCloud node before falling back to
-     * registry/hosted resolution. Default true. Setting false restores the
-     * exact pre-TC-106 resolution order (registry → fallback).
+     * Probe configured and registered local TinyCloud node endpoints before
+     * falling back to registry/hosted resolution. Default true. The loopback
+     * URL is probed only when `localNodeUrl` is explicitly configured.
      */
     autoDiscoverLocalNode?: boolean;
-    /** Local loopback node URL to probe. Default http://127.0.0.1:8000. */
+    /** Local loopback node URL to probe. Omit to avoid probing loopback. */
     localNodeUrl?: string;
     /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
     localLinkName?: string;
@@ -2988,4 +3016,4 @@ declare const EXPIRY: {
 declare const DEFAULT_SIGNED_READ_URL_EXPIRY_MS: number;
 type ExpiryTier = keyof typeof EXPIRY;
 
-export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, type AccountApplication, type AccountApplicationListOptions, type AccountApplicationRegisterOptions, type AccountDelegation, type AccountDelegationListOptions, AccountDelegationPage, AccountDelegationQueryOptions, type AccountDelegationRevokeOptions, type AccountIndexEnsureResult, type AccountIndexRebuildResult, type AccountIndexStatus, type AccountIndexedReadOptions, AccountService, type AccountServiceConfig, type AccountSpace, type AccountSpaceListOptions, type AccountStatus, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CanonicalAddress, type CanonicalParsedNetworkId, CaveatedDelegationUnsupportedError, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, CreateDelegationParams, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_KNOWLEDGE_ROOT, DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY, DEFAULT_LOCAL_NODE_URL, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, Delegation, DelegationManager, DelegationRevocationReceipt, type DidCacheKeyOptions, type DidEqualsOptions, type DiscoverLocalTinyCloudNodeOptions, type DiscoveredLocalTinyCloudNode, ENCRYPTION_MANIFEST_SPACE, ENCRYPTION_PERMISSION_SERVICE, EXPIRY, type EnsData, EnsDataSchema, type EventEmitterStrategy, type ExpiryTier, type Extension, GenerateShareParams, ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, IdentityParseError, LOCAL_LINK_HOST_SUFFIX, LOCAL_LINK_PROBE_TIMEOUT_MS, LOCAL_LOOPBACK_PROBE_TIMEOUT_MS, type LocalNodeIdentityStore, type LocationCandidate, type LocationCandidateInput, type LocationRecord, type LocationRecordPayload, type LocationRecordSigner, LocationRecordValidationError, type LocationResolutionAttempt, type LocationSource, type Manifest, type ManifestDefaults, type ManifestKnowledge, type ManifestRegistryRecord, type ManifestSecretActions, ManifestValidationError, type NodeInfo, type OpenKeyCallbackStrategy, type OpenKeySigningRequestBody, type OpenKeySigningResponseBody, type OpenKeySigningStrategyOptions, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedSessionProof, type PersistedTinyCloudSession, type PkhDidParts, ProtocolMismatchError, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SECRETS_SPACE, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, ShareLink, type SignCallback, type SignInOptions, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceAbilitiesMap, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, SpaceInfo, SpaceService, type SpaceServiceConfig, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, VAULT_PERMISSION_SERVICE, type ValidatedPersistedSessionProof, type ValidationError, VersionCheckError, type WasmRecapEntry, type WebStorageLike, actionContains, activateSessionWithHost, addressStorageKey, applyPrefix, buildSpaceUri, canonicalLocationPayload, canonicalizeAddress, canonicalizeDid, canonicalizeDidUrl, canonicalizeNetworkId, canonicalizeRecapCaveats, checkNodeInfo, composeManifestRequest, createInMemoryLocalNodeIdentityStore, createLocalStorageLocalNodeIdentityStore, createOpenKeyCallbackSigningStrategy, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, didCacheKey, didEquals, discoverLocalTinyCloudNode, expandActionShortNames, expandPermissionEntries, expandPermissionEntry, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, isEvmAddress, loadManifest, locationPayloadForRecord, makePkhSpaceId, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseCanonicalNetworkId, parseExpiry, parsePkhDid, parseRecapCapabilities, parseSpaceUri, pkhDid, principalDid, principalDidEquals, recapCaveatsEqual, resolveCloudLocation, resolveManifest, resolveManifestKnowledgeRoot, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyDidKeyEd25519Signature, verifyLocationRecord };
+export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, type AccountApplication, type AccountApplicationListOptions, type AccountApplicationRegisterOptions, type AccountDelegation, type AccountDelegationListOptions, AccountDelegationPage, AccountDelegationQueryOptions, type AccountDelegationRevokeOptions, type AccountIndexEnsureResult, type AccountIndexRebuildResult, type AccountIndexStatus, type AccountIndexedReadOptions, AccountService, type AccountServiceConfig, type AccountSpace, type AccountSpaceListOptions, type AccountStatus, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CanonicalAddress, type CanonicalParsedNetworkId, CaveatedDelegationUnsupportedError, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, CreateDelegationParams, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_KNOWLEDGE_ROOT, DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY, DEFAULT_LOCAL_NODE_URL, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, Delegation, DelegationManager, DelegationRevocationReceipt, type DidCacheKeyOptions, type DidEqualsOptions, type DiscoverLocalTinyCloudNodeOptions, type DiscoveredLocalTinyCloudNode, ENCRYPTION_MANIFEST_SPACE, ENCRYPTION_PERMISSION_SERVICE, EXPIRY, type EnsData, EnsDataSchema, type EventEmitterStrategy, type ExpiryTier, type Extension, GenerateShareParams, ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, IdentityParseError, LOCAL_LINK_HOST_SUFFIX, LOCAL_LINK_PROBE_TIMEOUT_MS, LOCAL_LOOPBACK_PROBE_TIMEOUT_MS, type LocalNodeIdentityStore, type LocationCandidate, type LocationCandidateInput, type LocationRecord, type LocationRecordPayload, type LocationRecordSigner, LocationRecordValidationError, type LocationResolutionAttempt, type LocationSource, type Manifest, type ManifestDefaults, type ManifestKnowledge, type ManifestRegistryRecord, type ManifestSecretActions, ManifestValidationError, type NodeInfo, type OpenKeyCallbackStrategy, type OpenKeySigningRequestBody, type OpenKeySigningResponseBody, type OpenKeySigningStrategyOptions, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedSessionProof, type PersistedTinyCloudSession, type PkhDidParts, ProtocolMismatchError, type RegisterBatchSuccess, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SECRETS_SPACE, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, ShareLink, type SignCallback, type SignInOptions, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceAbilitiesMap, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, SpaceInfo, SpaceService, type SpaceServiceConfig, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, VAULT_PERMISSION_SERVICE, type ValidatedPersistedSessionProof, type ValidationError, VersionCheckError, type WasmRecapEntry, type WebStorageLike, actionContains, activateSessionWithHost, addressStorageKey, applyPrefix, buildSpaceUri, canonicalLocationPayload, canonicalizeAddress, canonicalizeDid, canonicalizeDidUrl, canonicalizeNetworkId, canonicalizeRecapCaveats, checkNodeInfo, composeManifestRequest, createInMemoryLocalNodeIdentityStore, createLocalStorageLocalNodeIdentityStore, createOpenKeyCallbackSigningStrategy, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, didCacheKey, didEquals, discoverLocalTinyCloudNode, expandActionShortNames, expandPermissionEntries, expandPermissionEntry, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, isEvmAddress, loadManifest, locationPayloadForRecord, makePkhSpaceId, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseCanonicalNetworkId, parseExpiry, parsePkhDid, parseRecapCapabilities, parseSpaceUri, pkhDid, principalDid, principalDidEquals, recapCaveatsEqual, resolveCloudLocation, resolveManifest, resolveManifestKnowledgeRoot, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyDidKeyEd25519Signature, verifyLocationRecord };

package/dist/index.js

@@ -11793,7 +11793,8 @@ var TinyCloud = class _TinyCloud {
 import {
   err as err3,
   ok as ok3,
-  serviceError as serviceError3
+  serviceError as serviceError3,
+  ErrorCodes as ErrorCodes3
 } from "@tinycloud/sdk-services";
 import { ACCOUNT_INDEX_SCHEMA } from "@tinycloud/bootstrap";
 var SERVICE_NAME2 = "account";
@@ -11945,6 +11946,60 @@ var AccountService = class {
         await this.upsertSpaceIndexQuietly(registered);
         return ok3(registered);
       },
+      /**
+       * Register multiple spaces in one KV batch write + one multi-row index
+       * write, instead of one `register()` round trip per space (TC-373).
+       *
+       * The stored records are computed exactly once and reused for both the
+       * batch attempt and any reconciliation below, so a fallback never mints a
+       * fresh timestamp for a space that already has a written record — a
+       * second `spaceRecordFromInput` call would produce a new content hash and
+       * leave the first attempt's blocks orphaned.
+       */
+      registerBatch: async (spaces) => {
+        if (spaces.length === 0) return ok3({ spaces: [] });
+        await this.config.ensureAccountSpaceHosted?.();
+        const kvResult = this.accountKV();
+        if (!kvResult.ok) return kvResult;
+        const stored = spaces.map((space) => spaceRecordFromInput(space));
+        const registered = stored.map(
+          (record) => spaceFromRecord(spaceKey(record.space_id), record)
+        );
+        const items = stored.map((record) => ({
+          key: spaceKey(record.space_id),
+          value: record
+        }));
+        const batchResult = await kvResult.data.batchPut(items);
+        if (batchResult.ok) {
+          await this.upsertSpacesIndexQuietly(registered);
+          return ok3({ spaces: registered });
+        }
+        if (!isAmbiguousBatchFailure(batchResult.error)) {
+          return accountErr(batchResult.error);
+        }
+        const reconcileFailures = [];
+        for (const record of stored) {
+          const written = await kvResult.data.put(spaceKey(record.space_id), record);
+          if (!written.ok) {
+            reconcileFailures.push(`${record.space_id}: ${written.error.message}`);
+          }
+        }
+        if (reconcileFailures.length > 0) {
+          return err3(
+            serviceError3(
+              "KV_BATCH_RECONCILE_FAILED",
+              `KV batch write for ${items.length} space(s) failed ambiguously (${batchResult.error.message}) and per-space reconciliation also failed for: ${reconcileFailures.join("; ")}`,
+              SERVICE_NAME2,
+              { cause: batchResult.error.cause, meta: { originalError: batchResult.error } }
+            )
+          );
+        }
+        console.warn(
+          `[AccountService] KV batch write for ${items.length} space(s) returned an ambiguous error and was reconciled via per-space fallback. Original error: ${batchResult.error.message}`
+        );
+        await this.upsertSpacesIndexQuietly(registered);
+        return ok3({ spaces: registered, recoveredFromBatchError: batchResult.error });
+      },
       syncAccessible: async () => {
         const listed = await this.config.getSpaces().list();
         if (!listed.ok) return accountErr(listed.error);
@@ -12331,6 +12386,47 @@ var AccountService = class {
     if (!written.ok) return accountErr(written.error);
     return ok3(void 0);
   }
+  async upsertSpacesIndexQuietly(spaces) {
+    await ignoreIndexFailure(() => this.upsertSpacesIndex(spaces));
+  }
+  /**
+   * Upsert multiple space index rows in ONE multi-row `INSERT OR REPLACE`
+   * statement (TC-373), rather than one statement per space. This matters
+   * because `IDatabaseHandle.batch()` executes its statement list as a plain
+   * loop, not a single database transaction — an N-statement batch is not
+   * atomic. A single multi-row INSERT is one SQLite statement, so it applies
+   * atomically: all rows or none.
+   */
+  async upsertSpacesIndex(spaces) {
+    if (spaces.length === 0) return ok3(void 0);
+    const dbResult = this.accountDb();
+    if (!dbResult.ok) return ok3(void 0);
+    const schema = await this.ensureAccountIndex(dbResult.data);
+    if (!schema.ok) return schema;
+    const placeholders = spaces.map(() => "(?, ?, ?, ?, ?, ?, ?, ?, ?)").join(", ");
+    const params = spaces.flatMap((space) => {
+      const updatedAt = space.updatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+      return [
+        space.spaceId,
+        space.name,
+        space.ownerDid,
+        space.type,
+        JSON.stringify(space.permissions),
+        space.status,
+        space.registeredAt ?? updatedAt,
+        updatedAt,
+        space.expiresAt?.toISOString() ?? null
+      ];
+    });
+    const written = await dbResult.data.batch([
+      {
+        sql: `INSERT OR REPLACE INTO spaces (space_id, name, owner_did, type, permissions_json, status, registered_at, updated_at, expires_at) VALUES ${placeholders}`,
+        params
+      }
+    ]);
+    if (!written.ok) return accountErr(written.error);
+    return ok3(void 0);
+  }
   async deleteSpaceIndexQuietly(spaceId) {
     await ignoreIndexFailure(() => this.deleteSpaceIndex(spaceId));
   }
@@ -12657,6 +12753,17 @@ function accountErr(error) {
 function isMissingIndexError(error) {
   return /no such table:/i.test(error.message);
 }
+var AMBIGUOUS_WRITE_STATUSES = /* @__PURE__ */ new Set([500, 502, 503, 504, 520, 522, 524]);
+function isAmbiguousBatchFailure(error) {
+  if (error.code === ErrorCodes3.NETWORK_ERROR || error.code === ErrorCodes3.TIMEOUT) {
+    return error.meta?.requestMayHaveDispatched === true;
+  }
+  if (error.code === ErrorCodes3.KV_WRITE_FAILED) {
+    const status = error.meta?.status;
+    return typeof status === "number" && AMBIGUOUS_WRITE_STATUSES.has(status);
+  }
+  return false;
+}
 async function ignoreIndexFailure(task) {
   try {
     await task();
@@ -12672,7 +12779,7 @@ import {
   ok as ok5,
   err as err5,
   serviceError as serviceError5,
-  ErrorCodes as ErrorCodes3,
+  ErrorCodes as ErrorCodes4,
   TinyCloudDebugLogger,
   tinyCloudDebugLogger,
   enableTinyCloudDebug,
@@ -15132,13 +15239,14 @@ async function discoverLocalTinyCloudNode(options2 = {}) {
   }
   const fetchFn = options2.fetch ?? globalThis.fetch;
   const identityStore = options2.identityStore ?? defaultLocalNodeIdentityStore;
-  const staticCandidates = [
-    {
+  const staticCandidates = [];
+  if (options2.localNodeUrl) {
+    staticCandidates.push({
       source: "local-loopback",
-      url: options2.localNodeUrl ?? DEFAULT_LOCAL_NODE_URL,
+      url: options2.localNodeUrl,
       timeoutMs: LOCAL_LOOPBACK_PROBE_TIMEOUT_MS
-    }
-  ];
+    });
+  }
   if (options2.localLinkName) {
     if (isValidDnsLabel(options2.localLinkName)) {
       staticCandidates.push({
@@ -15591,7 +15699,7 @@ export {
   EXPIRY,
   EncryptionService,
   EnsDataSchema,
-  ErrorCodes3 as ErrorCodes,
+  ErrorCodes4 as ErrorCodes,
   HOLDER_KEY_BINDING_PRESENTATION_SCHEMA,
   HOOKS,
   HooksService2 as HooksService,