@tinycloud/node-sdk 3.2.0-beta.1 → 3.2.0-beta.3

package/dist/core.js

@@ -1,5 +1,19 @@
 // src/core.ts
 import { TinyCloud as TinyCloud2 } from "@tinycloud/sdk-core";
+
+// src/replication/module-registry.ts
+var nodeLoaders;
+function registerReplicationLoaders(loaders) {
+  nodeLoaders = loaders;
+}
+function getNodeReplicationLoaders() {
+  if (nodeLoaders === void 0) {
+    throw new Error("Replication requires registering replication controller loaders.");
+  }
+  return nodeLoaders;
+}
+
+// src/core.ts
 import {
   SilentNotificationHandler as SilentNotificationHandler2,
   AutoApproveSpaceCreationHandler as AutoApproveSpaceCreationHandler2,
@@ -16,7 +30,7 @@ import {
   makePkhSpaceId as makePkhSpaceId2,
   parsePkhDid,
   pkhDid as pkhDid3,
-  principalDid,
+  principalDid as principalDid2,
   principalDidEquals as principalDidEquals4,
   parseCanonicalNetworkId,
   TinyCloudDebugLogger,
@@ -247,7 +261,7 @@ import {
   parseCanonicalRecapResource,
   ACCOUNT_REGISTRY_SPACE,
   ACCOUNT_MANIFEST_PERMISSIONS,
-  KV,
+  KV as KV2,
   SQL,
   DUCKDB,
   CAPABILITIES,
@@ -255,6 +269,46 @@ import {
   ENCRYPTION
 } from "@tinycloud/sdk-core";
 
+// src/replication/authority-sign-in.ts
+import {
+  grantPathsForSelector,
+  KV,
+  isCapabilitySubset
+} from "@tinycloud/sdk-core";
+import { requiresSecretsOptIn } from "@tinycloud/sdk-services";
+var KV_GET = KV.GET;
+var KV_SYNC = KV.SYNC;
+var KV_SERVICE = "tinycloud.kv";
+function hasUnrestrictedGetCoverage(entries, spaceId, prefix) {
+  const requiredPaths = grantPathsForSelector(prefix);
+  return isCapabilitySubset(
+    requiredPaths.map((path) => ({ service: KV_SERVICE, space: spaceId, path, actions: [KV_GET] })),
+    [...entries]
+  ).subset;
+}
+function augmentSignInEntriesWithReplication(input) {
+  const out = [];
+  const replication = input.replication;
+  if (replication === void 0) return out;
+  for (const prefix of replication.prefixes) {
+    if (requiresSecretsOptIn(input.primarySpaceId, prefix) && replication.allowSecrets !== true) {
+      continue;
+    }
+    if (!hasUnrestrictedGetCoverage(input.entries, input.primarySpaceId, prefix)) {
+      continue;
+    }
+    for (const path of grantPathsForSelector(prefix)) {
+      out.push({
+        service: KV_SERVICE,
+        space: input.primarySpaceId,
+        path,
+        actions: [KV_GET, KV_SYNC]
+      });
+    }
+  }
+  return out;
+}
+
 // src/authorization/strategies.ts
 import { createOpenKeyCallbackSigningStrategy } from "@tinycloud/sdk-core";
 var defaultSignStrategy = { type: "auto-sign" };
@@ -330,7 +384,7 @@ var NodeUserAuthorization = class {
     this.spacePrefix = config.spacePrefix ?? "default";
     this.defaultActions = config.defaultActions ?? {
       kv: {
-        "": [KV.PUT, KV.GET, KV.DEL, KV.LIST, KV.METADATA]
+        "": [KV2.PUT, KV2.GET, KV2.DEL, KV2.LIST, KV2.METADATA]
       },
       sql: {
         "": [SQL.READ, SQL.WRITE, SQL.SCHEMA, SQL.ADMIN, SQL.EXPORT]
@@ -368,6 +422,7 @@ var NodeUserAuthorization = class {
     this.nonce = config.nonce;
     this.siweConfig = config.siweConfig;
     this.includeAccountRegistryPermissions = config.includeAccountRegistryPermissions ?? true;
+    this.replication = config.replication?.enabled === true ? config.replication : void 0;
     this._manifest = config.manifest;
     this._capabilityRequest = config.capabilityRequest;
     this.sessionManager = config.sessionManager ?? this.wasm.createSessionManager();
@@ -576,6 +631,143 @@ var NodeUserAuthorization = class {
     }
     return makePkhSpaceId(address, chainId, space);
   }
+  /**
+   * The plain-session primary abilities: `defaultActions` (the shared table)
+   * unless the primary space IS the account space, where account-registry
+   * permissions merge into a private clone so the shared table is never
+   * mutated. Shared between `resolveSignInCapabilities` and
+   * `signInPermissionInputs` so sign-in and `replicationSignInEntries`
+   * can't disagree (§4.6).
+   */
+  primaryActionsForSignIn() {
+    const primaryActions = this.includeAccountRegistryPermissions && this.spacePrefix === ACCOUNT_REGISTRY_SPACE ? cloneAbilitiesMap(this.defaultActions) : this.defaultActions;
+    if (this.includeAccountRegistryPermissions && this.spacePrefix === ACCOUNT_REGISTRY_SPACE) {
+      const accountAbilities = resourceCapabilitiesToAbilitiesMap(
+        ACCOUNT_MANIFEST_PERMISSIONS
+      );
+      for (const [service, paths] of Object.entries(accountAbilities)) {
+        const existingPaths = primaryActions[service] ?? (primaryActions[service] = {});
+        for (const [path, actions] of Object.entries(paths)) {
+          const existingActions = existingPaths[path] ?? (existingPaths[path] = []);
+          for (const action of actions) {
+            if (!existingActions.includes(action)) existingActions.push(action);
+          }
+        }
+      }
+    }
+    return primaryActions;
+  }
+  /**
+   * The abilities a `spacePrefix: "secrets"` plain session actually requests
+   * for its primary space: the vault-secrets subtree only — the
+   * `defaultActions` root `get` is REPLACED, not merged (sign-in installs
+   * this map under the primary space id). Shared between
+   * `resolveSignInCapabilities` and `signInPermissionInputs` so the
+   * replication augmentation measures coverage against the effective
+   * pre-replication request, never the uninstalled `primaryActions` (§4.1).
+   */
+  secretsPrimaryAbilities() {
+    return {
+      kv: {
+        "vault/secrets/": [
+          KV2.GET,
+          KV2.PUT,
+          KV2.DEL,
+          KV2.LIST,
+          KV2.METADATA
+        ]
+      }
+    };
+  }
+  /**
+   * The effective sign-in request as `PermissionEntry`s plus the resolved
+   * primary space id — the inputs to the replication augmentation (§4.1).
+   * `resolveSignInCapabilities` merges the augmented entries into its
+   * abilities; `replicationSignInEntries()` returns them verbatim, so the
+   * entries the SIWE recap carries and the restore check sees are the same.
+   */
+  signInPermissionInputs(address, chainId) {
+    const request = this.getCapabilityRequest();
+    if (request === void 0) {
+      const primarySpaceId2 = makePkhSpaceId(address, chainId, this.spacePrefix);
+      const effectivePrimary = this.spacePrefix === "secrets" ? this.secretsPrimaryAbilities() : this.primaryActionsForSignIn();
+      const kvPaths = effectivePrimary["kv"] ?? {};
+      return {
+        primarySpaceId: primarySpaceId2,
+        entries: Object.entries(kvPaths).map(([path, actions]) => ({
+          service: "tinycloud.kv",
+          space: primarySpaceId2,
+          path,
+          actions: [...actions]
+        }))
+      };
+    }
+    const spaceResources = request.resources.filter(
+      (entry) => entry.service !== ENCRYPTION_PERMISSION_SERVICE
+    );
+    const primarySpaceName = spaceResources.find((entry) => entry.space !== "account")?.space ?? DEFAULT_MANIFEST_SPACE;
+    const primarySpaceId = this.resolveSpaceName(
+      primarySpaceName,
+      address,
+      chainId
+    );
+    return {
+      primarySpaceId,
+      entries: spaceResources.map((entry) => ({
+        service: entry.service,
+        space: this.resolveSpaceName(entry.space, address, chainId),
+        path: entry.path,
+        actions: [...entry.actions]
+      }))
+    };
+  }
+  /**
+   * Merge replication augmentation entries into a space's abilities map
+   * without mutating shared tables (`defaultActions` may back the base map):
+   * the primary entry in `spaceAbilities` is replaced with a copy whose `kv`
+   * paths gain `get`/`sync`. Returns the merged map for `abilities`.
+   */
+  mergeReplicationEntries(spaceAbilities, primarySpaceId, abilities, entries) {
+    var _a;
+    if (entries.length === 0) {
+      return abilities;
+    }
+    const base = spaceAbilities[primarySpaceId] ?? abilities;
+    const kv = {};
+    for (const [path, actions] of Object.entries(base["kv"] ?? {})) {
+      kv[path] = [...actions];
+    }
+    for (const entry of entries) {
+      const list = kv[_a = entry.path] ?? (kv[_a] = []);
+      for (const action of entry.actions) {
+        if (!list.includes(action)) list.push(action);
+      }
+    }
+    const merged = { ...base, kv };
+    spaceAbilities[primarySpaceId] = merged;
+    return merged;
+  }
+  /**
+   * The replication entries this authorization's sign-in request carries
+   * for the signed-in or restored address (TC-858 §4.1/§4.6): the output of
+   * the same augmentation `resolveSignInCapabilities` runs — one
+   * `{tinycloud.kv, primarySpace, prefix, [get, sync]}` per configured
+   * prefix that already has an unrestricted covering `get` and passes the
+   * secrets opt-in gate. Empty when replication is off or no address is
+   * known. Pure.
+   */
+  replicationSignInEntries() {
+    if (this.replication === void 0) return [];
+    const address = this._address ?? this._tinyCloudSession?.address;
+    const chainId = this._chainId ?? this._tinyCloudSession?.chainId;
+    if (address === void 0 || chainId === void 0) return [];
+    const { entries, primarySpaceId } = this.signInPermissionInputs(address, chainId);
+    return augmentSignInEntriesWithReplication({
+      entries,
+      primarySpaceId,
+      replication: this.replication
+    });
+  }
   defaultEncryptionNetworkId(address, chainId) {
     return `urn:tinycloud:encryption:${pkhDid(address, chainId)}:default`;
   }
@@ -585,39 +777,25 @@ var NodeUserAuthorization = class {
       const defaultNetworkId = this.defaultEncryptionNetworkId(address, chainId);
       const primarySpaceId2 = makePkhSpaceId(address, chainId, this.spacePrefix);
       const secretsSpaceId = makePkhSpaceId(address, chainId, "secrets");
-      const primaryActions = this.includeAccountRegistryPermissions && this.spacePrefix === ACCOUNT_REGISTRY_SPACE ? cloneAbilitiesMap(this.defaultActions) : this.defaultActions;
+      const primaryActions = this.primaryActionsForSignIn();
       const spaceAbilities2 = {
         [primarySpaceId2]: primaryActions,
-        [secretsSpaceId]: {
-          kv: {
-            "vault/secrets/": [
-              KV.GET,
-              KV.PUT,
-              KV.DEL,
-              KV.LIST,
-              KV.METADATA
-            ]
-          }
-        }
+        [secretsSpaceId]: this.secretsPrimaryAbilities()
       };
       if (this.includeAccountRegistryPermissions && this.spacePrefix !== ACCOUNT_REGISTRY_SPACE) {
         spaceAbilities2[makePkhSpaceId(address, chainId, ACCOUNT_REGISTRY_SPACE)] = resourceCapabilitiesToAbilitiesMap(ACCOUNT_MANIFEST_PERMISSIONS);
-      } else if (this.includeAccountRegistryPermissions) {
-        const accountAbilities = resourceCapabilitiesToAbilitiesMap(
-          ACCOUNT_MANIFEST_PERMISSIONS
-        );
-        for (const [service, paths] of Object.entries(accountAbilities)) {
-          const existingPaths = primaryActions[service] ?? (primaryActions[service] = {});
-          for (const [path, actions] of Object.entries(paths)) {
-            const existingActions = existingPaths[path] ?? (existingPaths[path] = []);
-            for (const action of actions) {
-              if (!existingActions.includes(action)) existingActions.push(action);
-            }
-          }
-        }
       }
+      const mergedPrimary = this.mergeReplicationEntries(
+        spaceAbilities2,
+        primarySpaceId2,
+        primaryActions,
+        augmentSignInEntriesWithReplication({
+          ...this.signInPermissionInputs(address, chainId),
+          replication: this.replication
+        })
+      );
       return {
-        abilities: primaryActions,
+        abilities: mergedPrimary,
         spaceId: primarySpaceId2,
         spaceAbilities: spaceAbilities2,
         rawAbilities: {
@@ -653,8 +831,17 @@ var NodeUserAuthorization = class {
     for (const [space, abilities] of Object.entries(bySpace)) {
       spaceAbilities[this.resolveSpaceName(space, address, chainId)] = abilities;
     }
+    const mergedPrimaryAbilities = this.mergeReplicationEntries(
+      spaceAbilities,
+      primarySpaceId,
+      spaceAbilities[primarySpaceId] ?? resourceCapabilitiesToAbilitiesMap([]),
+      augmentSignInEntriesWithReplication({
+        ...this.signInPermissionInputs(address, chainId),
+        replication: this.replication
+      })
+    );
     return {
-      abilities: spaceAbilities[primarySpaceId] ?? resourceCapabilitiesToAbilitiesMap([]),
+      abilities: mergedPrimaryAbilities,
       spaceId: primarySpaceId,
       spaceAbilities,
       rawAbilities: Object.keys(rawAbilities).length > 0 ? rawAbilities : void 0
@@ -712,14 +899,14 @@ var NodeUserAuthorization = class {
    * Create the space on the TinyCloud server (host delegation).
    * This registers the user as the owner of the space.
    */
-  async hostSpace(targetSpaceId, purpose) {
+  async hostSpace(targetSpaceId, purpose, signal) {
     if (!this._tinyCloudSession || !this._address || !this._chainId) {
       throw new Error("Must be signed in to host space");
     }
     await this.ensureTinyCloudHosts();
     const host = this.primaryTinyCloudHost;
     const spaceId = targetSpaceId ?? this._tinyCloudSession.spaceId;
-    const peerId = await fetchPeerId(host, spaceId);
+    const peerId = await fetchPeerId(host, spaceId, signal);
     const siwe = this.wasm.generateHostSIWEMessage({
       address: this._address,
       chainId: this._chainId,
@@ -728,9 +915,28 @@ var NodeUserAuthorization = class {
       spaceId,
       peerId
     });
-    const signature = await this.signMessage(siwe, purpose);
+    if (signal?.aborted) throw signal.reason;
+    const signing = this.signMessage(siwe, purpose);
+    let signature;
+    if (!signal) {
+      signature = await signing;
+    } else {
+      let rejectOnAbort;
+      const aborted = new Promise((_resolve, reject2) => {
+        rejectOnAbort = reject2;
+      });
+      const onAbort = () => rejectOnAbort(signal.reason);
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (signal.aborted) onAbort();
+      try {
+        signature = await Promise.race([signing, aborted]);
+      } finally {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+    if (signal?.aborted) throw signal.reason;
     const headers = this.wasm.siweToDelegationHeaders({ siwe, signature });
-    return submitHostDelegation(host, headers);
+    return submitHostDelegation(host, headers, signal);
   }
   /**
    * Create a specific space on the server via host delegation.
@@ -751,8 +957,8 @@ var NodeUserAuthorization = class {
    * keeps its HTTP status (e.g. a typed 401/403) instead of collapsing to
    * `false`.
    */
-  async hostOwnedSpaceResult(spaceId, purpose) {
-    return this.hostSpace(spaceId, purpose);
+  async hostOwnedSpaceResult(spaceId, purpose, signal) {
+    return this.hostSpace(spaceId, purpose, signal);
   }
   /**
    * Ensure the user's space exists on the TinyCloud server.
@@ -1691,6 +1897,18 @@ var RuntimeDelegationRejectedError = class extends Error {
     this.reason = reason;
   }
 };
+function activationRejectionReason(error) {
+  if (typeof error !== "object" || error === null) return "activation_rejected";
+  if ("code" in error && error.code === "ACTIVATION_TRANSPORT_FAILED") {
+    return "activation_unavailable";
+  }
+  const cause = "cause" in error ? error.cause : void 0;
+  const status = typeof cause === "object" && cause !== null && "status" in cause ? cause.status : void 0;
+  if (typeof status !== "number") return "activation_rejected";
+  if (status === 408 || status === 429 || status >= 500) return "activation_unavailable";
+  if (status === 401) return "activation_unauthenticated";
+  return "activation_rejected";
+}
 function reject(reason, message) {
   throw new RuntimeDelegationRejectedError(reason, message);
 }
@@ -2075,7 +2293,10 @@ async function activateValidatedRuntimeDelegation(node, delegation, options) {
       await node.useRuntimeDelegation(installedCandidate);
     }
   } catch (error) {
-    reject("activation_rejected", error instanceof Error ? error.message : String(error));
+    reject(
+      activationRejectionReason(error),
+      error instanceof Error ? error.message : String(error)
+    );
   }
   const installed = node.getRuntimePermissionDelegations().find((candidate) => candidate.cid === cid);
   if (!installed) {
@@ -2148,6 +2369,37 @@ function deserializeDelegation(data) {
   };
 }
 
+// src/replication/config.ts
+import { kvPrefixCovers } from "@tinycloud/sdk-services";
+function assertValidReplicationConfig(replication) {
+  if (replication === void 0 || replication.enabled !== true) return;
+  if (replication.storage === void 0 || replication.storage === null) {
+    throw new TypeError("replication.enabled requires replication.storage");
+  }
+  if (!Array.isArray(replication.prefixes) || replication.prefixes.length === 0) {
+    throw new TypeError("replication.prefixes must be a non-empty array");
+  }
+  for (const prefix of replication.prefixes) {
+    if (typeof prefix !== "string" || prefix === "") {
+      throw new TypeError("replication.prefixes must not contain an empty prefix");
+    }
+  }
+  for (const [index, prefix] of replication.prefixes.entries()) {
+    for (const other of replication.prefixes.slice(index + 1)) {
+      if (kvPrefixCovers(prefix, other) || kvPrefixCovers(other, prefix)) {
+        throw new TypeError(
+          `replication.prefixes must not overlap: ${JSON.stringify(prefix)} and ${JSON.stringify(other)}`
+        );
+      }
+    }
+    if (prefix.split("/", 1)[0] === "vault" && replication.allowSecrets !== true) {
+      throw new TypeError(
+        `replication prefix ${JSON.stringify(prefix)} overlaps the vault namespace; pass allowSecrets to opt in`
+      );
+    }
+  }
+}
+
 // src/TinyCloudNode.ts
 import {
   TinyCloud,
@@ -2186,12 +2438,12 @@ import {
   canonicalizeRecapCaveats as canonicalizeRecapCaveats2,
   recapCaveatsEqual,
   expandPermissionEntries as expandPermissionEntriesCore,
-  isCapabilitySubset,
+  isCapabilitySubset as isCapabilitySubset2,
   isExplicitOnlyAction,
   parseRecapCapabilities,
   SERVICE_LONG_TO_SHORT,
   SERVICE_SHORT_TO_LONG,
-  KV as KV2,
+  KV as KV3,
   SQL as SQL2,
   DUCKDB as DUCKDB2,
   ENCRYPTION as ENCRYPTION2,
@@ -2201,6 +2453,7 @@ import {
   verifyDidKeyEd25519Signature,
   canonicalizeAddress as canonicalizeAddress2,
   pkhDid as pkhDid2,
+  principalDid,
   resolveTinyCloudHosts as resolveTinyCloudHosts2,
   publishLocationRecord,
   principalDidEquals as principalDidEquals3,
@@ -2672,11 +2925,11 @@ function isSecretPayload(value) {
   return typeof value === "object" && value !== null && "value" in value && typeof value.value === "string" && "createdAt" in value && typeof value.createdAt === "string" && "updatedAt" in value && typeof value.updatedAt === "string";
 }
 var ROOT_DELEGATION_ACTIONS = [
-  KV2.PUT,
-  KV2.GET,
-  KV2.DEL,
-  KV2.LIST,
-  KV2.METADATA,
+  KV3.PUT,
+  KV3.GET,
+  KV3.DEL,
+  KV3.LIST,
+  KV3.METADATA,
   SQL2.READ,
   SQL2.WRITE,
   SQL2.ADMIN,
@@ -3127,6 +3380,8 @@ var _TinyCloudNode = class _TinyCloudNode {
     this.confirmedHostedSpaceIds = /* @__PURE__ */ new Set();
     /** Serializes account-registry writes for the active node instance. */
     this.accountRegistryTail = Promise.resolve();
+    /** Bounds best-effort registry work on the sign-in critical path. */
+    this.accountRegistryDeadlineMs = 4e3;
     /**
      * True when the last signIn() detected an interactive signer and skipped
      * client-side bootstrap. Apps can read this to know whether bootstrap was
@@ -3205,11 +3460,46 @@ var _TinyCloudNode = class _TinyCloudNode {
       });
       return this.wasmBindings.invokeAny(invocationSession, caveatPreservingEntries, facts);
     };
+    assertValidReplicationConfig(config.replication);
     this.explicitHost = config.host;
     this.config = {
       ...config,
       host: config.host ?? DEFAULT_HOST
     };
+    if (this.config.replication?.enabled) {
+      const runtime = getNodeReplicationLoaders().runtime().then(({ ReplicationRuntime }) => {
+        const instance = new ReplicationRuntime(this.config.replication);
+        this.replicationRuntimeInstance = instance;
+        return instance;
+      });
+      this.replicationRuntime = runtime;
+      this.replicationControl = {
+        status: async () => {
+          const status = await runtime.then((ready) => ready.control.status());
+          const scopeError = this.replicationScopeError;
+          if (!scopeError) return status;
+          return this.config.replication.prefixes.map((prefix) => ({
+            prefix,
+            state: "unavailable",
+            lastError: {
+              at: (/* @__PURE__ */ new Date()).toISOString(),
+              code: "SESSION_SCOPE_MISMATCH",
+              message: scopeError
+            },
+            pending: { inFlight: 0, committed: 0, ambiguous: 0 },
+            pinned: [],
+            lagMs: null
+          }));
+        },
+        sync: async (input) => (await runtime).control.sync(input),
+        purge: (input) => {
+          const instance = this.replicationRuntimeInstance;
+          return instance ? instance.control.purge(input) : runtime.then((ready) => ready.control.purge(input));
+        },
+        clearPending: async () => (await runtime).control.clearPending(),
+        close: async () => (await runtime).control.close()
+      };
+    }
     if (config.wasmBindings) {
       this.wasmBindings = config.wasmBindings;
     } else if (_TinyCloudNode.nodeDefaults) {
@@ -3330,7 +3620,14 @@ var _TinyCloudNode = class _TinyCloudNode {
       siweConfig: config.siweConfig,
       manifest: useBootstrapSignInRequest ? void 0 : config.manifest,
       capabilityRequest: useBootstrapSignInRequest ? config.includeAccountRegistryPermissions === false ? BOOTSTRAP_DEFAULT_ONLY_SESSION_REQUEST : BOOTSTRAP_SESSION_REQUESTS.default : config.capabilityRequest,
-      includeAccountRegistryPermissions: useBootstrapSignInRequest ? false : config.includeAccountRegistryPermissions
+      includeAccountRegistryPermissions: useBootstrapSignInRequest ? false : config.includeAccountRegistryPermissions,
+      // Sign-in needs only the entry inputs (prefixes + secrets opt-in);
+      // storage and scheduling never leave TinyCloudNode.
+      replication: config.replication?.enabled === true ? {
+        enabled: true,
+        prefixes: config.replication.prefixes,
+        allowSecrets: config.replication.allowSecrets === true
+      } : void 0
     });
     this.tc = new TinyCloud(this.auth, {
       invokeAny: this.invokeAnyWithRuntimePermissions,
@@ -3581,6 +3878,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     this.confirmedHostedSpaceIds.clear();
     await this.tc.signIn(options);
     this.syncResolvedHostFromAuth();
+    this.replicationDelegateSession = void 0;
+    this.replicationScopeError = void 0;
+    if (this.replicationRuntime) await (await this.replicationRuntime).unbind();
     const oldGraph = this._serviceGraph;
     this._serviceGraph = this.createServiceGraphLifetime();
     oldGraph.retire();
@@ -3590,7 +3890,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       this.sessionKeyId = signedInSession.sessionKey;
       this.sessionKeyJwk = signedInSession.jwk;
     }
-    this.initializeServices();
+    await this.initializeServices();
     const primarySession = this.currentTinyCloudSession();
     if (primarySession) {
       this.registerPrimarySessionGrant(primarySession);
@@ -3602,6 +3902,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     if (!bootstrapped) {
       this.scheduleAccountRegistrySync();
+      await this.accountRegistryTail;
     }
     this.notificationHandler.success("Successfully signed in");
   }
@@ -4054,7 +4355,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       provenance: "primary"
     });
   }
-  async writeManifestRegistryRecords() {
+  async writeManifestRegistryRecords(account, signal) {
     const request = this.capabilityRequest;
     if (!request || request.registryRecords.length === 0) {
       return;
@@ -4063,8 +4364,9 @@ var _TinyCloudNode = class _TinyCloudNode {
       throw new Error("Manifest registry write requires wallet mode");
     }
     const accountSpaceId = this.ownedSpaceId(ACCOUNT_REGISTRY_SPACE2);
-    await this.ensureOwnedSpaceHostedById(accountSpaceId);
-    const result = await this.account.applications.register(request.manifests);
+    await this.ensureOwnedSpaceHostedById(accountSpaceId, signal);
+    if (signal.aborted) throw signal.reason;
+    const result = await account.applications.register(request.manifests);
     if (!result.ok) {
       throw Object.assign(
         new Error(`Failed to write manifest registry records: ${result.error.message}`),
@@ -4072,34 +4374,113 @@ var _TinyCloudNode = class _TinyCloudNode {
       );
     }
   }
+  createAccountRegistryServices(context, signal) {
+    const session = context.session;
+    if (!session) throw new Error("Account registry requires an active service session");
+    const contexts = [context];
+    const accountSpaceId = this.ownedSpaceId(ACCOUNT_REGISTRY_SPACE2);
+    const createScopedContext = (spaceId) => {
+      const scoped = this._serviceGraph.track(new ServiceContext2({
+        invoke: context.invoke,
+        invokeAny: context.invokeAny,
+        fetch: context.fetch,
+        hosts: context.hosts,
+        telemetry: this.config.telemetry
+      }));
+      scoped.setOperationAbortSignal(signal);
+      scoped.setSession({ ...session, spaceId });
+      contexts.push(scoped);
+      return scoped;
+    };
+    const sql = new SQLService2({});
+    const sqlContext = createScopedContext(accountSpaceId);
+    sql.initialize(sqlContext);
+    const spaces = new SpaceService({
+      hosts: context.hosts,
+      session,
+      invoke: context.invoke,
+      fetch: (url, init) => context.fetch(url, {
+        ...init,
+        signal: init?.signal ? AbortSignal.any([init.signal, signal]) : signal
+      }),
+      userDid: this.did,
+      createKVService: (spaceId) => {
+        const kv = new KVService2({});
+        kv.initialize(createScopedContext(spaceId));
+        return kv;
+      }
+    });
+    return {
+      contexts,
+      account: new AccountService({
+        getDid: () => this.did,
+        getHost: () => context.hosts[0] ?? this.config.host,
+        getPrimarySpaceId: () => session.spaceId,
+        getAccountSpaceId: () => accountSpaceId,
+        getSpaces: () => spaces,
+        getAccountDb: () => sql.db("account"),
+        ensureAccountSpaceHosted: () => this.ensureOwnedSpaceHostedById(accountSpaceId, signal)
+      })
+    };
+  }
   scheduleAccountRegistrySync() {
     const session = this.currentTinyCloudSession();
     if (!session || this.pendingAccountRegistrySync?.session === session) {
       return;
     }
+    const controller = new AbortController();
+    const deadline = setTimeout(
+      () => controller.abort(new DOMException("Account registry deadline exceeded", "TimeoutError")),
+      this.accountRegistryDeadlineMs
+    );
     const promise = this.enqueueAccountRegistryOperation(session, async () => {
-      await this.withAccountRegistryRetry(async () => {
-        if (this.currentTinyCloudSession() !== session) {
-          return;
-        }
-        await this.account.index.ensure();
-        if (this.currentTinyCloudSession() !== session) {
-          return;
-        }
-        await this.writeManifestRegistryRecords();
-        if (this.currentTinyCloudSession() !== session) {
-          return;
-        }
-        if (this.currentSessionCanListSpaces()) {
-          const spaces = await this.account.spaces.syncAccessible();
-          if (!spaces.ok) {
-            throw Object.assign(
-              new Error(`Failed to sync account spaces: ${spaces.error.message}`),
-              { cause: spaces.error }
-            );
+      const sharedContext = this._serviceContext;
+      if (!sharedContext) return;
+      const context = this._serviceGraph.track(new ServiceContext2({
+        invoke: sharedContext.invoke,
+        invokeAny: sharedContext.invokeAny,
+        fetch: sharedContext.fetch,
+        hosts: sharedContext.hosts,
+        telemetry: this.config.telemetry
+      }));
+      context.setOperationAbortSignal(controller.signal);
+      const current = this.currentTinyCloudSession();
+      if (!current) return;
+      context.setSession({
+        delegationHeader: current.delegationHeader,
+        delegationCid: current.delegationCid,
+        spaceId: current.spaceId,
+        verificationMethod: current.verificationMethod,
+        jwk: current.jwk
+      });
+      const registry = this.createAccountRegistryServices(context, controller.signal);
+      try {
+        await this.withAccountRegistryRetry(async () => {
+          if (controller.signal.aborted) throw controller.signal.reason;
+          if (this.currentTinyCloudSession() !== session) return;
+          await registry.account.index.ensure();
+          if (controller.signal.aborted) throw controller.signal.reason;
+          if (this.currentTinyCloudSession() !== session) return;
+          await this.writeManifestRegistryRecords(registry.account, controller.signal);
+          if (controller.signal.aborted) throw controller.signal.reason;
+          if (this.currentTinyCloudSession() !== session) return;
+          if (this.currentSessionCanListSpaces()) {
+            const result = await registry.account.spaces.syncAccessible();
+            if (controller.signal.aborted) throw controller.signal.reason;
+            if (!result.ok) {
+              throw Object.assign(
+                new Error(`Failed to sync account spaces: ${result.error.message}`),
+                { cause: result.error }
+              );
+            }
           }
+        }, controller.signal);
+      } finally {
+        for (const operationContext of registry.contexts) {
+          operationContext.retire();
         }
-      });
+        clearTimeout(deadline);
+      }
     });
     this.pendingAccountRegistrySync = { session, promise };
     const clearPendingSync = () => {
@@ -4108,6 +4489,10 @@ var _TinyCloudNode = class _TinyCloudNode {
       }
     };
     void promise.then(clearPendingSync, clearPendingSync);
+    void promise.then(
+      () => clearTimeout(deadline),
+      () => clearTimeout(deadline)
+    );
   }
   enqueueAccountRegistryOperation(session, task) {
     const operation = this.accountRegistryTail.then(async () => {
@@ -4143,14 +4528,22 @@ var _TinyCloudNode = class _TinyCloudNode {
       (operation) => operation.service === "space" && this.actionContains(operation.action, "tinycloud.space/list")
     );
   }
-  async withAccountRegistryRetry(task) {
+  async withAccountRegistryRetry(task, signal) {
     const delays = [250, 1e3, 3e3];
     let lastError;
     for (let attempt = 0; attempt < delays.length; attempt += 1) {
+      if (signal.aborted) {
+        console.warn("TinyCloud account registry sync stopped: deadline exceeded", signal.reason);
+        return;
+      }
       try {
         await task();
         return;
       } catch (error) {
+        if (signal.aborted) {
+          console.warn("TinyCloud account registry sync stopped: deadline exceeded", error);
+          return;
+        }
         const verdict = authorizationVerdictOf(error);
         const message = error instanceof Error ? error.message : String(error);
         const isAuthorizationVerdict = verdict === void 0 ? /Unauthorized Action|\b(?:401|403)\b/.test(message) : verdict !== "other";
@@ -4162,12 +4555,28 @@ var _TinyCloudNode = class _TinyCloudNode {
           return;
         }
         if (isStorageFullError(error) || isStorageFullError(error?.cause) || message.includes(STORAGE_FULL_MESSAGE) || message.includes(STORAGE_WRITE_TOO_LARGE_MESSAGE)) {
-          console.warn("TinyCloud account registry sync stopped: storage is full", error);
+          console.warn(
+            "TinyCloud account registry sync stopped: storage is full",
+            error
+          );
           return;
         }
         lastError = error;
         if (attempt < delays.length - 1) {
-          await new Promise((resolve) => setTimeout(resolve, delays[attempt]));
+          await new Promise((resolve, reject2) => {
+            const timer = setTimeout(() => {
+              signal.removeEventListener("abort", onAbort);
+              resolve();
+            }, delays[attempt]);
+            const onAbort = () => {
+              clearTimeout(timer);
+              signal.removeEventListener("abort", onAbort);
+              reject2(signal.reason);
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+          }).catch((error2) => {
+            if (!signal.aborted) throw error2;
+          });
         }
       }
     }
@@ -4217,7 +4626,7 @@ var _TinyCloudNode = class _TinyCloudNode {
    * self-revealing: the next write to the space fails immediately and loudly
    * with `404 Space not found`.
    */
-  async ensureOwnedSpaceHostedById(spaceId) {
+  async ensureOwnedSpaceHostedById(spaceId, signal) {
     if (!this.auth) {
       throw new Error("Owned space hosting requires wallet mode");
     }
@@ -4232,7 +4641,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (!host) {
       throw new Error("Owned space hosting requires a TinyCloud host");
     }
-    const activation = await activateSessionWithHost2(host, session.delegationHeader);
+    const activation = await activateSessionWithHost2(host, session.delegationHeader, signal);
     if (activation.success && !activation.skipped?.includes(spaceId)) {
       this.confirmedHostedSpaceIds.add(spaceId);
       return;
@@ -4243,15 +4652,16 @@ var _TinyCloudNode = class _TinyCloudNode {
         { cause: activation }
       );
     }
-    const created = await this.auth.hostOwnedSpaceResult(spaceId);
+    const authorization = this.auth;
+    const created = signal ? await authorization.hostOwnedSpaceResult(spaceId, void 0, signal) : await authorization.hostOwnedSpaceResult(spaceId);
     if (!created.success) {
       throw Object.assign(
         new Error(`Failed to create owned space ${spaceId}: ${describeHostFailure2(created)}`),
         { cause: created }
       );
     }
-    await new Promise((resolve) => setTimeout(resolve, 100));
-    const retry = await activateSessionWithHost2(host, session.delegationHeader);
+    if (signal?.aborted) throw signal.reason;
+    const retry = await activateSessionWithHost2(host, session.delegationHeader, signal);
     if (!retry.success || retry.skipped?.includes(spaceId)) {
       throw Object.assign(
         new Error(
@@ -4529,6 +4939,34 @@ var _TinyCloudNode = class _TinyCloudNode {
     const stagedHost = resolvedHost ?? this.config.host;
     const stagedAddress = restoredAddress;
     const stagedChainId = sessionData.chainId ?? 1;
+    let replicationPrincipal;
+    let compactReplicationSession;
+    let replicationScopeError;
+    if (this.config.replication?.enabled) {
+      if (stagedAddress !== void 0) {
+        replicationPrincipal = pkhDid2(stagedAddress, stagedChainId);
+      } else {
+        const { replicationScopeFromSignedSession } = await getNodeReplicationLoaders().authority();
+        const signedScope = replicationScopeFromSignedSession({
+          delegationHeader: sessionData.delegationHeader,
+          delegationCid: sessionData.delegationCid,
+          verificationMethod: restoredVerificationMethod,
+          persistedSpace: sessionData.spaceId
+        });
+        if (!signedScope) {
+          replicationScopeError = "Persisted space does not match the locally verified delegation scope.";
+        } else {
+          replicationPrincipal = signedScope.principal;
+          compactReplicationSession = {
+            delegationHeader: sessionData.delegationHeader,
+            delegationCid: sessionData.delegationCid,
+            spaceId: signedScope.space,
+            verificationMethod: restoredVerificationMethod,
+            jwk: stagedJwk
+          };
+        }
+      }
+    }
     const stagedNodeDid = stagedAddress ? pkhDid2(stagedAddress, stagedChainId) : canonicalVerificationMethod;
     const serviceSession = {
       delegationHeader: sessionData.delegationHeader,
@@ -4607,7 +5045,18 @@ var _TinyCloudNode = class _TinyCloudNode {
     } else {
       this._restoredTcSession = stagedTcSession;
     }
+    this.replicationDelegateSession = compactReplicationSession;
+    this.replicationScopeError = replicationScopeError;
+    if (this.replicationRuntime) await (await this.replicationRuntime).unbind();
     oldGraph.retire();
+    if (replicationScopeError) {
+      stagedGraph.serviceContext.emit("replication.state", {
+        state: "unavailable",
+        code: "SESSION_SCOPE_MISMATCH",
+        detail: replicationScopeError
+      });
+    }
+    await this.bindReplicationRuntime(stagedGraph.serviceContext, serviceSession, stagedGraph.kv, replicationPrincipal);
     oldCore?.retireServices?.();
   }
   stagePrimarySessionState(session, verificationMethod, host, sessionExpiry, recap) {
@@ -4761,6 +5210,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         }));
         context.setSession(config.session);
         service.initialize(context);
+        this.attachReplicationKV(config.session.spaceId, service);
         return service;
       }
     });
@@ -4801,6 +5251,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         }));
         context.setSession({ ...input.serviceSession, spaceId });
         scopedKv.initialize(context);
+        this.attachReplicationKV(spaceId, scopedKv);
         return scopedKv;
       },
       createVaultService: (spaceId) => {
@@ -4815,6 +5266,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         }));
         context.setSession({ ...input.serviceSession, spaceId });
         scopedKv.initialize(context);
+        this.attachReplicationKV(spaceId, scopedKv);
         const scopedVault = this.createVaultService(spaceId, scopedKv, encryption, {
           host: input.host,
           did: input.nodeDid,
@@ -5095,7 +5547,12 @@ var _TinyCloudNode = class _TinyCloudNode {
       siweConfig: this.config.siweConfig,
       manifest: useBootstrapSignInRequest ? void 0 : this.config.manifest,
       capabilityRequest: useBootstrapSignInRequest ? this.config.includeAccountRegistryPermissions === false ? BOOTSTRAP_DEFAULT_ONLY_SESSION_REQUEST : BOOTSTRAP_SESSION_REQUESTS.default : this.config.capabilityRequest,
-      includeAccountRegistryPermissions: useBootstrapSignInRequest ? false : this.config.includeAccountRegistryPermissions
+      includeAccountRegistryPermissions: useBootstrapSignInRequest ? false : this.config.includeAccountRegistryPermissions,
+      replication: this.config.replication?.enabled === true ? {
+        enabled: true,
+        prefixes: this.config.replication.prefixes,
+        allowSecrets: this.config.replication.allowSecrets === true
+      } : void 0
     });
     this.tc = new TinyCloud(this.auth, {
       invokeAny: this.invokeAnyWithRuntimePermissions,
@@ -5148,7 +5605,12 @@ var _TinyCloudNode = class _TinyCloudNode {
       siweConfig: this.config.siweConfig,
       manifest: useBootstrapSignInRequest ? void 0 : this.config.manifest,
       capabilityRequest: useBootstrapSignInRequest ? this.config.includeAccountRegistryPermissions === false ? BOOTSTRAP_DEFAULT_ONLY_SESSION_REQUEST : BOOTSTRAP_SESSION_REQUESTS.default : this.config.capabilityRequest,
-      includeAccountRegistryPermissions: useBootstrapSignInRequest ? false : this.config.includeAccountRegistryPermissions
+      includeAccountRegistryPermissions: useBootstrapSignInRequest ? false : this.config.includeAccountRegistryPermissions,
+      replication: this.config.replication?.enabled === true ? {
+        enabled: true,
+        prefixes: this.config.replication.prefixes,
+        allowSecrets: this.config.replication.allowSecrets === true
+      } : void 0
     });
     this.tc = new TinyCloud(this.auth, {
       invokeAny: this.invokeAnyWithRuntimePermissions,
@@ -5160,7 +5622,7 @@ var _TinyCloudNode = class _TinyCloudNode {
    * Initialize the service context and KV service after sign-in.
    * @internal
    */
-  initializeServices() {
+  async initializeServices() {
     const session = this.currentTinyCloudSession();
     if (!session) {
       return;
@@ -5203,12 +5665,18 @@ var _TinyCloudNode = class _TinyCloudNode {
       jwk: session.jwk
     };
     this._serviceContext.setSession(serviceSession);
+    await this.bindReplicationRuntime(this._serviceContext, serviceSession, this._kv);
     this.tc.serviceContext.setSession(serviceSession);
     this._vault = this.createVaultService(session.spaceId, this._kv);
     this._vault.initialize(this._serviceContext);
     this._serviceContext.registerService("vault", this._vault);
     this.initializeV2Services(serviceSession);
   }
+  attachReplicationKV(spaceId, kvService) {
+    if (!this.replicationRuntime) return;
+    const attached = this.replicationRuntime.then((runtime) => runtime.attach(spaceId, kvService));
+    kvService.setReadThroughReady(attached);
+  }
   createSpaceScopedKVService(spaceId) {
     const kvService = new KVService2({});
     if (this._serviceContext) {
@@ -5224,6 +5692,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         spaceScopedContext.setSession({ ...session, spaceId });
       }
       kvService.initialize(spaceScopedContext);
+      this.attachReplicationKV(spaceId, kvService);
     }
     return kvService;
   }
@@ -5686,6 +6155,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         }));
         context.setSession(config.session);
         service.initialize(context);
+        this.attachReplicationKV(config.session.spaceId, service);
         return service;
       },
       onRootDelegationNeeded: this.signer ? async (params) => {
@@ -6010,6 +6480,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     }));
     spaceScopedContext.setSession({ ...this._serviceContext.session, spaceId });
     kv.initialize(spaceScopedContext);
+    this.attachReplicationKV(spaceId, kv);
     return kv;
   }
   /**
@@ -6432,10 +6903,18 @@ var _TinyCloudNode = class _TinyCloudNode {
       );
     }
     const targetHost = delegation.host ?? this.config.host;
-    const activateResult = await activateSessionWithHost2(
-      targetHost,
-      delegation.delegationHeader
-    );
+    let activateResult;
+    try {
+      activateResult = await activateSessionWithHost2(
+        targetHost,
+        delegation.delegationHeader
+      );
+    } catch (cause) {
+      throw Object.assign(
+        new Error("The TinyCloud host could not be reached to activate the delegation."),
+        { code: "ACTIVATION_TRANSPORT_FAILED", cause }
+      );
+    }
     if (!activateResult.success) {
       if (this.operationsFromDelegation(delegation).some(
         (operation) => operation.resource?.startsWith("urn:cid:") === true && operation.service === "delegation" && operation.action === "tinycloud.delegation/revoke"
@@ -6723,7 +7202,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       throw new Error("Public space not enabled. Set enablePublicSpace: true in config.");
     }
     await this.auth.hostPublicSpace(publicSpaceId);
-    const kvActions = [KV2.PUT, KV2.GET, KV2.DEL, KV2.LIST, KV2.METADATA];
+    const kvActions = [KV3.PUT, KV3.GET, KV3.DEL, KV3.LIST, KV3.METADATA];
     const abilities = { kv: { "": kvActions } };
     const now = /* @__PURE__ */ new Date();
     const expiryMs = EXPIRY3.EPHEMERAL_MS;
@@ -6964,31 +7443,31 @@ var _TinyCloudNode = class _TinyCloudNode {
       );
       return { delegation: delegation2, prompted: true };
     }
-    const granted = this.projectSignedRecapCapabilities(session.siwe);
-    const { subset, missing } = this.signedCapabilitySubset(expandedEntries, granted);
-    if (!subset) {
-      const runtimeOperations = this.permissionEntriesToOperations(expandedEntries, session);
-      const runtimeGrant = this.findGrantForOperations(
-        runtimeOperations,
-        { excludePrimary: true }
-      );
-      if (runtimeGrant) {
-        const marginMs = _TinyCloudNode.SESSION_EXPIRY_SAFETY_MARGIN_MS;
-        if (runtimeGrant.expiresAt.getTime() <= Date.now() + marginMs) {
-          throw new SessionExpiredError(runtimeGrant.expiresAt);
-        }
-        const runtimeExpiration = runtimeGrant.expiresAt < effectiveExpiration ? runtimeGrant.expiresAt : effectiveExpiration;
-        const delegation2 = await this.createDelegationViaRuntimeGrant(
-          did,
-          expandedEntries,
-          runtimeExpiration,
-          runtimeGrant,
-          runtimeOperations,
-          onPrepared
-        );
-        return { delegation: delegation2, prompted: false };
+    const plan = this.planDerivation(
+      expandedEntries,
+      session,
+      effectiveExpiration,
+      Date.now()
+    );
+    if ("refused" in plan) {
+      if (plan.refused === "SESSION_EXPIRING") {
+        throw new SessionExpiredError(plan.expiredAt ?? sessionExpiry ?? /* @__PURE__ */ new Date(0));
+      }
+      if (plan.refused === "CAVEATED_AUTHORITY") {
+        throw new CaveatedDelegationUnsupportedError(plan.caveated ?? []);
       }
-      throw new PermissionNotInManifestError(missing, granted);
+      throw new PermissionNotInManifestError(plan.missing ?? [], plan.granted ?? []);
+    }
+    if (plan.path === "runtime") {
+      const delegation2 = await this.createDelegationViaRuntimeGrant(
+        did,
+        expandedEntries,
+        plan.effectiveExpiration,
+        plan.grant,
+        plan.operations,
+        onPrepared
+      );
+      return { delegation: delegation2, prompted: false };
     }
     const delegation = await this.createDelegationViaWasmPath(
       did,
@@ -6999,6 +7478,149 @@ var _TinyCloudNode = class _TinyCloudNode {
     );
     return { delegation, prompted: false };
   }
+  /**
+   * What `delegateTo` would select for `entries`, without signing or any
+   * network call (TC-858 plan v3 §4.3): the session path when the signed
+   * recap covers every entry, the runtime-grant path otherwise, or a
+   * refusal. A refusal of `CAVEATED_AUTHORITY` means coverage exists only
+   * through caveated branches, which the action-only WASM child-delegation
+   * boundary cannot preserve — replication never derives authority through
+   * them. `expiredAt`/`missing`/`granted`/`caveated` carry the payload
+   * `delegateTo` turns back into its typed errors.
+   * @internal
+   */
+  planDerivation(expandedEntries, session, effectiveExpiration, nowMs) {
+    const caveatedRequest = expandedEntries.filter(
+      (entry) => !recapCaveatsEqual(entry.caveats, void 0)
+    );
+    if (caveatedRequest.length > 0) {
+      return { refused: "CAVEATED_AUTHORITY", caveated: caveatedRequest };
+    }
+    const granted = this.projectSignedRecapCapabilities(session.siwe);
+    const { subset, missing } = this.signedCapabilitySubset(expandedEntries, granted);
+    if (subset) {
+      return {
+        path: "session",
+        parentCid: session.delegationCid,
+        expiresAt: effectiveExpiration.getTime(),
+        effectiveExpiration
+      };
+    }
+    const runtimeOperations = this.permissionEntriesToOperations(expandedEntries, session);
+    const runtimeGrant = this.findGrantForOperations(
+      runtimeOperations,
+      { excludePrimary: true }
+    );
+    if (runtimeGrant) {
+      const marginMs = _TinyCloudNode.SESSION_EXPIRY_SAFETY_MARGIN_MS;
+      if (runtimeGrant.expiresAt.getTime() <= nowMs + marginMs) {
+        return { refused: "SESSION_EXPIRING", expiredAt: runtimeGrant.expiresAt };
+      }
+      const caveated = this.caveatedRuntimeGrantEntries(
+        expandedEntries,
+        runtimeOperations,
+        runtimeGrant
+      );
+      if (caveated.length > 0) {
+        return { refused: "CAVEATED_AUTHORITY", caveated };
+      }
+      const runtimeExpiration = runtimeGrant.expiresAt < effectiveExpiration ? runtimeGrant.expiresAt : effectiveExpiration;
+      return {
+        path: "runtime",
+        parentCid: runtimeGrant.session.delegationCid,
+        expiresAt: runtimeExpiration.getTime(),
+        effectiveExpiration: runtimeExpiration,
+        grant: runtimeGrant,
+        operations: runtimeOperations
+      };
+    }
+    const relaxedGranted = granted.map((entry) => ({ ...entry, caveats: void 0 }));
+    const relaxedRequested = expandedEntries.map((entry) => ({ ...entry, caveats: void 0 }));
+    const relaxed = this.signedCapabilitySubset(relaxedRequested, relaxedGranted);
+    if (relaxed.subset) {
+      return {
+        refused: "CAVEATED_AUTHORITY",
+        caveated: missing.map((entry) => ({ ...entry, caveats: [{ via: "session-recap" }] }))
+      };
+    }
+    return { refused: "NOT_COVERED", missing, granted };
+  }
+  /**
+   * The plan `delegateTo(device, entries)` would follow, as a pure lookup:
+   * no WASM sign and no `POST /delegate`. Backs
+   * `ReplicationAuthority.plan` (and `mint` inside it) so a predicted
+   * parent and expiry can never disagree with what a mint would use (§4.3,
+   * §4.4). Session expiry inside the 60 s margin refuses with
+   * `SESSION_EXPIRING`; the same check delegateTo performs.
+   * @internal
+   */
+  planDelegation(entries, options) {
+    if (!Array.isArray(entries) || entries.length === 0) {
+      throw new Error("planDelegation requires a non-empty permissions array");
+    }
+    const session = this.currentTinyCloudSession();
+    if (!session) {
+      return { refused: "SESSION_EXPIRING", expiredAt: /* @__PURE__ */ new Date(0) };
+    }
+    const nowMs = Date.now();
+    const sessionExpiry = extractSiweExpiration(session.siwe);
+    if (sessionExpiry !== void 0 && sessionExpiry.getTime() <= nowMs + _TinyCloudNode.SESSION_EXPIRY_SAFETY_MARGIN_MS) {
+      return { refused: "SESSION_EXPIRING", expiredAt: sessionExpiry };
+    }
+    const expandedEntries = this.expandPermissionEntries(entries);
+    const expiryMs = resolveExpiryMs(options?.expiry);
+    const expirationTime = new Date(nowMs + expiryMs);
+    const effectiveExpiration = sessionExpiry !== void 0 && sessionExpiry < expirationTime ? sessionExpiry : expirationTime;
+    return this.planDerivation(expandedEntries, session, effectiveExpiration, nowMs);
+  }
+  /**
+   * The replication entries this node's sign-in request carries for the
+   * current replication config and the signed-in or restored address: the
+   * output of the same augmentation step `resolveSignInCapabilities` runs,
+   * with the unrestricted-get and secrets gates applied (§4.1, §4.6).
+   * Empty when replication is off or no address is known. Pure.
+   */
+  replicationSignInEntries() {
+    if (this.config.replication?.enabled !== true) return [];
+    const auth = this.auth;
+    if (auth === void 0 || typeof auth.replicationSignInEntries !== "function") {
+      return [];
+    }
+    return auth.replicationSignInEntries();
+  }
+  async replicationAuthority() {
+    const { createReplicationAuthority } = await getNodeReplicationLoaders().authority();
+    return createReplicationAuthority({
+      replicationSession: () => this.currentTinyCloudSession() ?? this.replicationDelegateSession,
+      siweExpiration: (siwe) => extractSiweExpiration(siwe),
+      planDelegation: (entries, options) => this.planDelegation(entries, options),
+      mintDelegation: async (deviceDid, entries) => {
+        const result = await this.delegateTo(principalDid(deviceDid), entries);
+        return {
+          ucan: result.delegation.delegationHeader.Authorization,
+          expiresAt: result.delegation.expiry.getTime()
+        };
+      }
+    });
+  }
+  async bindReplicationRuntime(context, session, kv, principal) {
+    if (!this.replicationRuntime) return;
+    const identityPrincipal = principal ?? (this._address === void 0 ? void 0 : pkhDid2(this._address, this._chainId));
+    if (identityPrincipal === void 0) return;
+    const runtime = await this.replicationRuntime;
+    const authority = await this.replicationAuthority();
+    await runtime.bind({
+      context,
+      session,
+      principal: identityPrincipal,
+      authority,
+      primaryKV: [{ space: session.spaceId, kv }]
+    });
+  }
+  /** Stable control facade for this node's optional replication runtime. */
+  get replication() {
+    return this.replicationControl;
+  }
   /**
    * Materialize one manifest-declared delegation using the current session key.
    * Delivery is intentionally out of band; callers decide how to transmit the
@@ -7221,6 +7843,18 @@ var _TinyCloudNode = class _TinyCloudNode {
    * it only accepts action maps, so reject the selected constrained branch.
    */
   assertRuntimeGrantCaveatsPreservable(entries, requestedOperations, grant) {
+    const caveated = this.caveatedRuntimeGrantEntries(entries, requestedOperations, grant);
+    if (caveated.length > 0) {
+      throw new CaveatedDelegationUnsupportedError(caveated);
+    }
+  }
+  /**
+   * The entries of `grant` that cover a requested operation while carrying
+   * caveats — the branches {@link assertRuntimeGrantCaveatsPreservable}
+   * rejects and {@link planDerivation} classifies as `CAVEATED_AUTHORITY`.
+   * Shared so the pure plan and the mint path can't disagree.
+   */
+  caveatedRuntimeGrantEntries(entries, requestedOperations, grant) {
     let operationIndex = 0;
     const caveated = [];
     for (const entry of entries) {
@@ -7239,9 +7873,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         }
       }
     }
-    if (caveated.length > 0) {
-      throw new CaveatedDelegationUnsupportedError(caveated);
-    }
+    return caveated;
   }
   /** Reject caveated parent branches before action-only child signing. */
   assertPortableDelegationCaveatsPreservable(delegation) {
@@ -7346,7 +7978,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     const missing = requested.filter((entry) => {
       const raw = this.isEncryptionPermissionEntry(entry) || this.isRawRevocationPermissionEntry(entry);
       const comparable = raw && this.isEncryptionPermissionEntry(entry) ? { ...entry, space: "encryption" } : entry;
-      return !isCapabilitySubset([comparable], raw ? rawGranted : spaceGranted).subset;
+      return !isCapabilitySubset2([comparable], raw ? rawGranted : spaceGranted).subset;
     });
     return { subset: missing.length === 0, missing };
   }
@@ -7818,7 +8450,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         session.chainId
       );
       const publicAbilities = {
-        kv: { "": [KV2.GET, KV2.PUT, KV2.METADATA] }
+        kv: { "": [KV3.GET, KV3.PUT, KV3.METADATA] }
       };
       const publicPrepared = this.wasmBindings.prepareSession({
         abilities: publicAbilities,
@@ -7846,7 +8478,7 @@ var _TinyCloudNode = class _TinyCloudNode {
           delegationHeader: publicSession.delegationHeader,
           spaceId: publicSpaceId,
           path: "",
-          actions: [KV2.GET, KV2.PUT, KV2.METADATA],
+          actions: [KV3.GET, KV3.PUT, KV3.METADATA],
           disableSubDelegation: params.disableSubDelegation ?? false,
           expiry: expirationTime,
           delegateDID: params.delegateDID,
@@ -8120,7 +8752,7 @@ import {
   resolveManifest as resolveManifest2,
   validateManifest,
   loadManifest,
-  isCapabilitySubset as isCapabilitySubset2,
+  isCapabilitySubset as isCapabilitySubset3,
   expandActionShortNames,
   expandPermissionEntries as expandPermissionEntries2,
   expandPermissionEntry,
@@ -8165,7 +8797,7 @@ import {
   SpaceService as SpaceService2,
   SpaceErrorCodes,
   createSpaceService,
-  parseSpaceUri,
+  parseSpaceUri as parseSpaceUri2,
   buildSpaceUri,
   makePublicSpaceId as makePublicSpaceId2,
   Space
@@ -8256,7 +8888,7 @@ export {
   expandPermissionEntry,
   getTinyCloudDebugLogs,
   installTinyCloudDebugGlobals,
-  isCapabilitySubset2 as isCapabilitySubset,
+  isCapabilitySubset3 as isCapabilitySubset,
   isEvmAddress,
   loadManifest,
   makePkhSpaceId2 as makePkhSpaceId,
@@ -8265,10 +8897,11 @@ export {
   parseExpiry2 as parseExpiry,
   parsePkhDid,
   parseSecretCatalogKey,
-  parseSpaceUri,
+  parseSpaceUri2 as parseSpaceUri,
   pkhDid3 as pkhDid,
-  principalDid,
+  principalDid2 as principalDid,
   principalDidEquals4 as principalDidEquals,
+  registerReplicationLoaders,
   resolveManifest2 as resolveManifest,
   resolveSecretListPrefix2 as resolveSecretListPrefix,
   resolveSecretPath3 as resolveSecretPath,