@tinycloud/sdk-services 3.1.0-beta.7 → 3.1.0

package/dist/index.cjs

@@ -155,6 +155,10 @@ var ErrorCodes = {
   AUTH_EXPIRED: "AUTH_EXPIRED",
   AUTH_REQUIRED: "AUTH_REQUIRED",
   AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  /** HTTP 401: the delegation the invocation cites was revoked. */
+  AUTH_DELEGATION_REVOKED: "AUTH_DELEGATION_REVOKED",
+  /** HTTP 401: a delegation the cited one rests on was revoked. */
+  AUTH_DELEGATION_ANCESTOR_REVOKED: "AUTH_DELEGATION_ANCESTOR_REVOKED",
   NETWORK_ERROR: "NETWORK_ERROR",
   TIMEOUT: "TIMEOUT",
   ABORTED: "ABORTED",
@@ -166,6 +170,10 @@ var ErrorCodes = {
   KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
   KV_CONFLICT: "KV_CONFLICT",
   KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
+  /** HTTP 410 from the change feed: discard sync state and restart without a cursor; `meta.reason` says why. */
+  KV_SYNC_RESET_REQUIRED: "KV_SYNC_RESET_REQUIRED",
+  /** HTTP 403 from the change feed: the retention grant was refused; `meta.reason` says why. */
+  KV_RETENTION_GRANT_REFUSED: "KV_RETENTION_GRANT_REFUSED",
   // SQL-specific errors
   SQL_ERROR: "SQL_ERROR",
   SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
@@ -1767,6 +1775,30 @@ var PrefixedKVService = class _PrefixedKVService {
       removePrefix
     });
   }
+  /**
+   * Read the change feed for everything under this prefix. A view with an
+   * empty prefix (`""` or `"/"`) is refused: the node does not serve a
+   * whole-space feed.
+   */
+  async changes(options) {
+    if (this._prefix.replace(/\/+$/, "") === "") {
+      return err(serviceError(
+        ErrorCodes.INVALID_INPUT,
+        "KV changes needs a non-empty prefix; this view has none",
+        "kv"
+      ));
+    }
+    const syncPrefix = `${this._prefix}/`;
+    const response = await this._kv.changes({ ...options, prefix: syncPrefix });
+    if (!response.ok) return response;
+    return ok({
+      ...response.data,
+      changes: response.data.changes.map((change) => ({
+        ...change,
+        key: change.key.startsWith(syncPrefix) ? change.key.slice(syncPrefix.length) : change.key
+      }))
+    });
+  }
   /**
    * Delete a key.
    */
@@ -1819,11 +1851,36 @@ var KVAction = {
   PUT: "tinycloud.kv/put",
   LIST: "tinycloud.kv/list",
   DELETE: "tinycloud.kv/del",
-  HEAD: "tinycloud.kv/metadata"
+  HEAD: "tinycloud.kv/metadata",
+  /** The change feed; never implied by `*` or `tinycloud.kv/*`. */
+  SYNC: "tinycloud.kv/sync",
+  /** Retention attestation; presented through `retentionGrant`, never invoked or implied. */
+  RETAIN: "tinycloud.kv/retain"
 };
 
 // src/kv/KVService.ts
 var MAX_KV_BATCH_READ_ITEMS = 100;
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var pathByteEncoder = new TextEncoder();
+function comparePathsByBytes(a, b) {
+  const left = pathByteEncoder.encode(a);
+  const right = pathByteEncoder.encode(b);
+  const length = Math.min(left.length, right.length);
+  for (let index = 0; index < length; index++) {
+    if (left[index] !== right[index]) {
+      return left[index] - right[index];
+    }
+  }
+  return left.length - right.length;
+}
+var REVOKED_BODY = /^(?:Invalid invocation: )?delegation-(?:(revoked): [A-Za-z0-9]+|(ancestor-revoked): ancestor=[A-Za-z0-9]+ invoked=[A-Za-z0-9]+)$/;
+function revocationCodeOf(body) {
+  const match = REVOKED_BODY.exec(body.trim());
+  if (match === null) return void 0;
+  return match[1] !== void 0 ? ErrorCodes.AUTH_DELEGATION_REVOKED : ErrorCodes.AUTH_DELEGATION_ANCESTOR_REVOKED;
+}
 function encodeKvBatchPartName(path) {
   return encodeURIComponent(path).replace(
     /[!'()*]/g,
@@ -2051,15 +2108,25 @@ var KVService = class extends BaseService {
     )?.[1];
     return contentType?.includes("application/json") ? JSON.parse(text) : text;
   }
+  /**
+   * Validate a batch read response and return its items in the caller's
+   * request order. The node flattens invocation abilities from a `BTreeMap`,
+   * so results arrive sorted by UTF-8 byte order of the path, not in request
+   * order. Items that carry their path in `key` are matched by path; if no
+   * item carries a key, items are assumed to be in the node's byte-sorted
+   * order and the request is aligned the same way. Any mix of keyed and
+   * keyless items, a missing requested path, an unrequested path, or a
+   * malformed item fails closed (returns undefined).
+   */
   normalizeBatchReadResponse(data, paths, requireData) {
     if (!data || typeof data !== "object") return void 0;
     const response = data;
-    if (!Array.isArray(response.results) || response.results.length !== paths.length) {
+    const items = response.results;
+    if (!Array.isArray(items) || items.length !== paths.length) {
       return void 0;
     }
-    for (let index = 0; index < response.results.length; index++) {
-      const item = response.results[index];
-      if (!item || typeof item !== "object" || item.key !== paths[index] || typeof item.ok !== "boolean") {
+    for (const item of items) {
+      if (!item || typeof item !== "object" || typeof item.ok !== "boolean") {
         return void 0;
       }
       if (item.ok && (!item.headers || typeof item.headers !== "object" || Object.values(item.headers).some((value) => typeof value !== "string") || requireData && typeof item.dataBase64 !== "string")) {
@@ -2069,7 +2136,24 @@ var KVService = class extends BaseService {
         return void 0;
       }
     }
-    return response;
+    if (items.every((item) => typeof item.key === "string")) {
+      const byPath = new Map(items.map((item) => [item.key, item]));
+      if (byPath.size !== items.length) return void 0;
+      const aligned2 = [];
+      for (const path of paths) {
+        const item = byPath.get(path);
+        if (!item) return void 0;
+        aligned2.push(item);
+      }
+      return aligned2;
+    }
+    if (items.some((item) => item.key !== void 0)) return void 0;
+    const requestOrder = paths.map((_, index) => index).sort((a, b) => comparePathsByBytes(paths[a], paths[b]));
+    const aligned = new Array(items.length);
+    for (let position = 0; position < requestOrder.length; position++) {
+      aligned[requestOrder[position]] = items[position];
+    }
+    return aligned;
   }
   async batchRead(keys, action, options) {
     if (!this.requireAuth()) return err(authRequiredError("kv"));
@@ -2162,19 +2246,19 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
-      const payload = this.normalizeBatchReadResponse(
+      const items = this.normalizeBatchReadResponse(
         await response.json(),
         paths,
         action === KVAction.GET
       );
-      if (!payload) {
+      if (!items) {
         return err(serviceError(
           ErrorCodes.NETWORK_ERROR,
           "KV batch read response did not match the requested keys",
           "kv"
         ));
       }
-      const results = payload.results.map((item, index) => {
+      const results = items.map((item, index) => {
         if (!item.ok) {
           return {
             key: keys[index],
@@ -2742,6 +2826,169 @@ var KVService = class extends BaseService {
       }
     });
   }
+  /**
+   * Read one page of the `tinycloud.kv/sync` change feed for a prefix.
+   */
+  async changes(options) {
+    return this.withTelemetry("changes", options?.prefix, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      if (typeof options?.prefix !== "string" || options.prefix.length === 0) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV changes prefix must be a non-empty string",
+          "kv"
+        ));
+      }
+      if (options.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1e3)) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV changes limit must be an integer from 1 through 1000",
+          "kv"
+        ));
+      }
+      const headers = {};
+      if (options.limit !== void 0) headers["x-tinycloud-limit"] = String(options.limit);
+      if (options.cursor !== void 0) headers["x-tinycloud-cursor"] = options.cursor;
+      if (options.retentionGrant !== void 0) {
+        headers["x-tinycloud-retention-grant"] = options.retentionGrant;
+      }
+      const request = this.createRequestSignal(options.signal, options.timeout);
+      try {
+        const response = await this.invokeOperation(
+          options.prefix,
+          KVAction.SYNC,
+          void 0,
+          request.signal,
+          headers
+        );
+        if (!response.ok) {
+          return await this.changesFailure(response, options.prefix, request.signal);
+        }
+        const text = await response.text();
+        let body;
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = void 0;
+        }
+        const page = this.normalizeChangesResponse(body);
+        if (!page) {
+          return err(serviceError(
+            ErrorCodes.NETWORK_ERROR,
+            "KV changes response was not a tinycloud.kv/sync page",
+            "kv",
+            { meta: { status: response.status, statusText: response.statusText } }
+          ));
+        }
+        return ok(page);
+      } catch (error) {
+        return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
+      }
+    });
+  }
+  /**
+   * Map a failed `kv/sync` response. 410 and the retention 403 carry
+   * `{"error":{"code","reason"}}`; a revoked grant is a 401 whose whole body
+   * is the node's revocation error (see REVOKED_BODY). A body read that
+   * fails because the request was cancelled or timed out rethrows, so the
+   * caller sees `ABORTED`/`TIMEOUT` rather than a mapped status.
+   */
+  async changesFailure(response, prefix, signal) {
+    if (response.status === 404) {
+      return this.classifyNotFound(response, prefix);
+    }
+    let errorText;
+    try {
+      errorText = await response.text();
+    } catch (error) {
+      if (signal.aborted) throw error;
+      errorText = "";
+    }
+    const meta = { status: response.status, statusText: response.statusText };
+    let reason;
+    let bodyCode;
+    try {
+      const body = JSON.parse(errorText);
+      const error = isJsonObject(body) ? body.error : void 0;
+      if (isJsonObject(error)) {
+        if (typeof error.code === "string") bodyCode = error.code;
+        if (typeof error.reason === "string") reason = error.reason;
+      }
+    } catch {
+    }
+    const context = `Failed to read KV changes for ${JSON.stringify(prefix)}`;
+    if (response.status === 410) {
+      return err(serviceError(
+        ErrorCodes.KV_SYNC_RESET_REQUIRED,
+        `${context}: the node requires a reset (${reason ?? "reason not given"}); discard sync state and restart without a cursor`,
+        "kv",
+        { meta: { ...meta, reason } }
+      ));
+    }
+    if (response.status === 403 && bodyCode === "RETENTION_GRANT_REFUSED") {
+      return err(serviceError(
+        ErrorCodes.KV_RETENTION_GRANT_REFUSED,
+        `${context}: the retention grant was refused (${reason ?? "reason not given"})`,
+        "kv",
+        { meta: { ...meta, reason } }
+      ));
+    }
+    if (response.status === 401) {
+      const revoked = revocationCodeOf(errorText);
+      if (revoked !== void 0) {
+        return err(serviceError(revoked, `${context}: 401 - ${errorText}`, "kv", { meta }));
+      }
+    }
+    if (response.status === 401 || response.status === 403) {
+      return this.authorizationFailure(context, response, errorText, [prefix], KVAction.SYNC);
+    }
+    return err(serviceError(
+      response.status === 400 ? ErrorCodes.INVALID_INPUT : ErrorCodes.NETWORK_ERROR,
+      `${context}: ${response.status} - ${errorText}`,
+      "kv",
+      { meta }
+    ));
+  }
+  normalizeChangesResponse(data) {
+    if (!isJsonObject(data)) return void 0;
+    const { changes, more, cursor, source, authority } = data;
+    if (!Array.isArray(changes) || typeof more !== "boolean" || typeof cursor !== "string" || !isJsonObject(source) || typeof source.nodeDid !== "string" || typeof source.space !== "string" || typeof source.prefix !== "string" || !isJsonObject(authority)) {
+      return void 0;
+    }
+    const { notBefore, expiresAt, retainUntil } = authority;
+    if (notBefore !== null && typeof notBefore !== "string" || expiresAt !== null && typeof expiresAt !== "string" || retainUntil !== null && typeof retainUntil !== "string") {
+      return void 0;
+    }
+    const parsed = [];
+    for (const change of changes) {
+      if (!isJsonObject(change) || typeof change.key !== "string") return void 0;
+      if (change.deleted === true) {
+        parsed.push({ key: change.key, deleted: true });
+        continue;
+      }
+      const { metadata } = change;
+      if (change.deleted !== false || typeof change.etag !== "string" || !isJsonObject(metadata) || !Object.values(metadata).every((value) => typeof value === "string")) {
+        return void 0;
+      }
+      parsed.push({
+        key: change.key,
+        deleted: false,
+        etag: change.etag,
+        metadata
+      });
+    }
+    return {
+      changes: parsed,
+      more,
+      cursor,
+      source: { nodeDid: source.nodeDid, space: source.space, prefix: source.prefix },
+      authority: { notBefore, expiresAt, retainUntil }
+    };
+  }
   /**
    * Delete a key.
    */
@@ -3938,7 +4185,7 @@ var AsyncQueue = class {
     }
     const waiter = this.waiters.shift();
     if (waiter) {
-      waiter({ value, done: false });
+      waiter.resolve({ value, done: false });
       return;
     }
     this.values.push(value);
@@ -3950,7 +4197,22 @@ var AsyncQueue = class {
     this.closed = true;
     while (this.waiters.length > 0) {
       const waiter = this.waiters.shift();
-      waiter?.({ value: void 0, done: true });
+      waiter?.resolve({ value: void 0, done: true });
+    }
+  }
+  /**
+   * Fail the queue: pending and future `next()` calls reject with `error`,
+   * so a `for await` consumer sees the iterator throw.
+   */
+  fail(error) {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.failure = error;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      waiter?.reject(error);
     }
   }
   next() {
@@ -3958,20 +4220,28 @@ var AsyncQueue = class {
       const value = this.values.shift();
       return Promise.resolve({ value, done: false });
     }
+    if (this.failure !== void 0) {
+      return Promise.reject(this.failure);
+    }
     if (this.closed) {
       return Promise.resolve({ value: void 0, done: true });
     }
-    return new Promise((resolve) => {
-      this.waiters.push(resolve);
+    return new Promise((resolve, reject) => {
+      this.waiters.push({ resolve, reject });
     });
   }
 };
+var HOOK_STREAM_RETRY_BASE_DELAY_MS = 250;
+var HOOK_STREAM_RETRY_MAX_DELAY_MS = 3e4;
+var HOOK_STREAM_HEALTHY_MS = 5e3;
 var HooksService = class extends BaseService {
   constructor(config = {}) {
     super();
     this._subscribers = /* @__PURE__ */ new Set();
-    this._refreshChain = Promise.resolve();
-    this._activeSignature = "";
+    /** True while the one supervisor loop runs. Set only by wake(), cleared only at loop exit. */
+    this._supervising = false;
+    /** Bumped on every session change; part of the plan key. */
+    this._sessionGeneration = 0;
     this._config = config;
   }
   get config() {
@@ -3987,35 +4257,32 @@ var HooksService = class extends BaseService {
     if (subscriptions.length === 0) {
       throw new Error("At least one hook subscription is required");
     }
-    const normalized = subscriptions.map(normalizeSubscription);
+    const requested = subscriptions.map(normalizeSubscription);
     const subscriber = {
-      requested: normalized,
+      requested,
+      signatures: requested.map(subscriptionSignature),
       ttlSeconds: options.ttlSeconds,
       queue: new AsyncQueue()
     };
-    this._subscribers.add(subscriber);
-    const abortHandler = () => {
+    const leave = () => {
       this._subscribers.delete(subscriber);
       subscriber.queue.close();
-      void this.scheduleSharedStreamRefresh();
+      this.wake();
     };
-    if (options.signal) {
-      if (options.signal.aborted) {
-        abortHandler();
-      } else {
-        options.signal.addEventListener("abort", abortHandler, { once: true });
-      }
+    const { signal } = options;
+    if (signal?.aborted) {
+      return;
     }
-    void this.scheduleSharedStreamRefresh();
+    signal?.addEventListener("abort", leave, { once: true });
+    this._subscribers.add(subscriber);
+    this.wake();
     try {
       for await (const event of subscriber.queue) {
         yield event;
       }
     } finally {
-      if (options.signal) {
-        options.signal.removeEventListener("abort", abortHandler);
-      }
-      abortHandler();
+      signal?.removeEventListener("abort", leave);
+      leave();
     }
   }
   async register(webhook) {
@@ -4156,146 +4423,292 @@ var HooksService = class extends BaseService {
       return err(wrapError("hooks", error));
     }
   }
-  async scheduleSharedStreamRefresh() {
-    this._refreshChain = this._refreshChain.then(() => this.refreshSharedStream()).catch(() => void 0);
-    await this._refreshChain;
-  }
-  async refreshSharedStream() {
-    if (!this.requireAuth() || this._subscribers.size === 0) {
-      this.abortSharedStream();
-      this._activeSignature = "";
-      return;
-    }
-    const state = this.collectSharedStreamState();
-    if (state.signature !== this._activeSignature) {
-      this._activeSignature = state.signature;
-      this.abortSharedStream();
+  /**
+   * Called after anything that may change what the supervisor should do:
+   * subscribe, unsubscribe, session change, sign-out. Interrupts the running
+   * step if the plan moved away from it, and starts the supervisor if none
+   * runs. Touches only SDK-owned state, so it never throws into callers such
+   * as `ServiceContext.setSession`.
+   */
+  wake() {
+    const phase = this._phase;
+    if (phase && phase.key !== this.plan()?.key) {
+      phase.interrupt.abort();
     }
-    if (!this._sharedStreamTask) {
-      this._sharedStreamTask = this.runSharedStream(state).catch((error) => {
-        if (!isAbortError(error)) {
-          throw error;
-        }
-      }).finally(() => {
-        this._sharedStreamTask = void 0;
-        this._sharedStreamAbort = void 0;
-        if (this._subscribers.size > 0) {
-          void this.scheduleSharedStreamRefresh();
-        }
-      });
+    if (this._supervising || this._subscribers.size === 0) {
+      return;
     }
+    this._supervising = true;
+    this.supervise().catch(() => this.collapse());
   }
-  collectSharedStreamState() {
-    const merged = /* @__PURE__ */ new Map();
-    const ttlCandidates = [];
-    for (const subscriber of this._subscribers) {
-      if (typeof subscriber.ttlSeconds === "number") {
-        ttlCandidates.push(subscriber.ttlSeconds);
+  /**
+   * The only owner of the shared stream. Each iteration is one attempt
+   * (mint → open → drain), then a classification and, unless the attempt was
+   * superseded or released its subscribers, a backoff. Every await is a
+   * `phase` that wake() can interrupt; an interrupted phase yields
+   * `undefined`, so a superseded mint can never act. Outside `attempt` and
+   * `pause`, which each own one catch, the loop touches only SDK state.
+   */
+  async supervise() {
+    let streak = 0;
+    for (; ; ) {
+      const plan = this.plan();
+      if (!plan) {
+        this._supervising = false;
+        return;
+      }
+      const health = { openedAt: 0, delivered: false };
+      const outcome = await this.phase(
+        plan.key,
+        (signal) => this.attempt(plan, signal, health)
+      );
+      if (health.delivered || health.openedAt > 0 && performance.now() - health.openedAt >= HOOK_STREAM_HEALTHY_MS) {
+        streak = 0;
+      }
+      if (!outcome) {
+        continue;
       }
-      for (const subscription of subscriber.requested) {
-        merged.set(subscriptionSignature(subscription), subscription);
+      if (this.plan()?.key !== plan.key) {
+        continue;
+      }
+      if (outcome.kind === "stopped") {
+        this.release();
+        continue;
+      }
+      if (outcome.kind === "refused" && outcome.terminal) {
+        this.release(outcome.error);
+        this.report(outcome.error);
+        continue;
       }
+      if (outcome.kind !== "ended") {
+        this.report(outcome.error);
+      }
+      streak += 1;
+      await this.phase(
+        plan.key,
+        (signal) => this.pause(streak, signal)
+      );
+    }
+  }
+  /**
+   * Run one step under an interrupt that wake() fires when the plan key moves
+   * on. An interrupted step's result is discarded. The interrupt is also
+   * fired when the step returns, which releases whatever it left open: the
+   * request signal and its listeners, an unread response body, a timer.
+   */
+  async phase(key, step) {
+    const interrupt = new AbortController();
+    this._phase = { key, interrupt };
+    try {
+      if (this.plan()?.key !== key) {
+        interrupt.abort();
+      }
+      const result = await step(interrupt.signal);
+      return interrupt.signal.aborted ? void 0 : result;
+    } finally {
+      this._phase = void 0;
+      interrupt.abort();
     }
-    const subscriptions = [...merged.values()].sort(
-      (left, right) => subscriptionSignature(left).localeCompare(subscriptionSignature(right))
-    );
-    const ttlSeconds = ttlCandidates.length > 0 ? Math.min(...ttlCandidates) : void 0;
-    const signature = JSON.stringify({
-      subscriptions: subscriptions.map(subscriptionSignature),
-      ttlSeconds
-    });
-    return {
-      subscriptions,
-      ttlSeconds,
-      signature
-    };
   }
-  async runSharedStream(state) {
-    const abortController = new AbortController();
-    this._sharedStreamAbort = abortController;
+  /**
+   * One mint → open → drain. The single catch site for everything the
+   * attempt touches that the SDK does not own: context accessors, invoke,
+   * fetch, response bodies, the SSE parser. Never rejects.
+   */
+  async attempt(plan, signal, health) {
+    let phase = "mint";
+    let request;
+    const owns = () => !signal.aborted && !request?.signal.aborted && this.plan()?.key === plan.key;
     try {
-      const host = this._config.host ?? this.context.hosts[0];
-      const ticketResponse = await this.mintHookTicket(
-        state.subscriptions,
-        state.ttlSeconds,
-        abortController.signal
+      const context = this.context;
+      const contextSignal = context.abortSignal;
+      this._lastContextSignal = contextSignal;
+      if (!context.isAuthenticated || contextSignal?.aborted) {
+        return { kind: "stopped" };
+      }
+      request = this.createRequestSignal(signal, 0);
+      const host = this.host;
+      const minted = await awaitOwned(
+        request.signal,
+        () => context.fetch(`${host}/hooks/tickets`, {
+          method: "POST",
+          headers: {
+            ...serviceHeadersToRecord(this.createInvokeHeaders(plan.subscriptions)),
+            "content-type": "application/json"
+          },
+          body: JSON.stringify({
+            subscriptions: plan.subscriptions,
+            ttlSeconds: plan.ttlSeconds
+          }),
+          signal: request.signal
+        })
       );
-      const streamResponse = await this.openHookStream(
-        host,
-        ticketResponse.ticket,
-        abortController.signal
+      if (!owns()) return { kind: "stopped" };
+      if (!minted.ok) {
+        const status = minted.status;
+        const error = await awaitOwned(
+          request.signal,
+          () => responseError("hooks", "failed to mint hook ticket", minted)
+        );
+        if (!owns()) return { kind: "stopped" };
+        return { kind: "refused", terminal: isTerminalMintRefusal(status), error };
+      }
+      const body = await awaitOwned(request.signal, () => minted.json());
+      if (!owns()) return { kind: "stopped" };
+      const ticket = body !== null && typeof body === "object" && "ticket" in body ? body.ticket : void 0;
+      if (typeof ticket !== "string" || ticket.length === 0) {
+        throw new Error("Hook ticket response did not include a ticket");
+      }
+      phase = "open";
+      if (!owns()) return { kind: "stopped" };
+      const stream = await awaitOwned(
+        request.signal,
+        () => context.fetch(`${host}/hooks/events?ticket=${encodeURIComponent(ticket)}`, {
+          method: "GET",
+          headers: { accept: "text/event-stream" },
+          signal: request.signal
+        })
       );
-      for await (const message of parseSseStream(
-        streamResponse.body,
-        abortController.signal
-      )) {
-        if (!message.data) {
-          continue;
-        }
-        const event = parseHookEvent(message);
-        for (const subscriber of this._subscribers) {
-          if (matchesAnySubscription(event, subscriber.requested)) {
-            subscriber.queue.push(event);
-          }
+      if (!owns()) return { kind: "stopped" };
+      if (!stream.ok) {
+        return { kind: "refused", terminal: false, error: hookStreamRefusal(stream.status) };
+      }
+      health.openedAt = performance.now();
+      const iterator = parseSseStream(stream.body, request.signal)[Symbol.asyncIterator]();
+      try {
+        for (; ; ) {
+          const next = await awaitOwned(request.signal, () => iterator.next());
+          if (!owns()) return { kind: "stopped" };
+          if (next.done) break;
+          const message = next.value;
+          if (!message.data) continue;
+          const event = parseHookEvent(message);
+          if (!owns()) return { kind: "stopped" };
+          this.dispatch(event);
+          health.delivered = true;
         }
+      } finally {
+        const closing = iterator.return?.();
+        if (closing) void Promise.resolve(closing).then(() => void 0, () => void 0);
       }
+      return owns() ? { kind: "ended" } : { kind: "stopped" };
+    } catch (thrown) {
+      return request?.signal.aborted || thrown === SUPERSEDED ? { kind: "stopped" } : { kind: "failed", error: hookStreamFailure(phase, thrown) };
+    }
+  }
+  /**
+   * Back off before the next attempt. `config.streamRetry` overrides the
+   * delay and the clock; whatever they do, the pause ends by the delay or the
+   * interrupt, then yields one timer turn so an instant clock cannot starve
+   * due timers or the process.
+   */
+  async pause(attempt, signal) {
+    try {
+      this._lastContextSignal = this.context.abortSignal;
+    } catch {
+    }
+    const contextSignal = this._lastContextSignal;
+    const waits = [];
+    const aborts = [];
+    try {
+      const retry = this._config.streamRetry;
+      const delayMs = retry?.delay?.(attempt) ?? hookStreamRetryDelay(attempt);
+      waits.push((retry?.wait ?? sleep)(delayMs, attempt, signal));
+    } catch {
+      waits.push(Promise.resolve());
+    }
+    aborts.push(abortPromise(signal));
+    if (contextSignal) aborts.push(abortPromise(contextSignal));
+    try {
+      await Promise.race([...waits, ...aborts.map(({ promise }) => promise)]);
+    } catch {
     } finally {
-      if (this._sharedStreamAbort === abortController) {
-        this._sharedStreamAbort = void 0;
+      for (const abort of aborts) abort.dispose();
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  /** The stream the current subscribers need, or undefined when none remain. */
+  plan() {
+    if (this._subscribers.size === 0) {
+      return void 0;
+    }
+    const merged = /* @__PURE__ */ new Map();
+    let ttlSeconds;
+    for (const subscriber of this._subscribers) {
+      subscriber.requested.forEach(
+        (subscription, index) => merged.set(subscriber.signatures[index], subscription)
+      );
+      if (typeof subscriber.ttlSeconds === "number") {
+        ttlSeconds = Math.min(subscriber.ttlSeconds, ttlSeconds ?? Infinity);
       }
     }
+    const signatures = [...merged.keys()].sort();
+    return {
+      key: JSON.stringify([this._sessionGeneration, signatures, ttlSeconds ?? null]),
+      subscriptions: signatures.map((signature) => merged.get(signature)),
+      ttlSeconds
+    };
   }
-  abortSharedStream() {
-    this._sharedStreamAbort?.abort();
+  dispatch(event) {
+    for (const subscriber of this._subscribers) {
+      if (matchesAnySubscription(event, subscriber.requested)) {
+        subscriber.queue.push(event);
+      }
+    }
   }
-  createHookHeaders(action, path) {
-    return this.context.invoke(this.session, "hooks", path, action);
+  /**
+   * Detach every subscriber. With `error`, their iterators throw it after
+   * draining buffered events; without, they complete.
+   */
+  release(error) {
+    const subscribers = [...this._subscribers];
+    this._subscribers.clear();
+    for (const { queue } of subscribers) {
+      if (error) {
+        queue.fail(error);
+      } else {
+        queue.close();
+      }
+    }
   }
-  async mintHookTicket(subscriptions, ttlSeconds, signal) {
-    const host = this._config.host ?? this.context.hosts[0];
-    const headers = this.createInvokeHeaders(subscriptions);
-    const ticketResponse = await this.context.fetch(`${host}/hooks/tickets`, {
-      method: "POST",
-      headers: {
-        ...serviceHeadersToRecord(headers),
-        "content-type": "application/json"
-      },
-      body: JSON.stringify({
-        subscriptions,
-        ttlSeconds
-      }),
-      signal
-    });
-    if (!ticketResponse.ok) {
-      throw await responseError(
-        "hooks",
-        "failed to mint hook ticket",
-        ticketResponse
-      );
+  report(error) {
+    if (error.meta && typeof error.meta === "object") {
+      Object.freeze(error.meta);
     }
-    const ticketJson = await ticketResponse.json();
-    if (!ticketJson?.ticket) {
-      throw new Error("Hook ticket response did not include a ticket");
+    Object.freeze(error);
+    try {
+      this.emitError(error, "stream");
+    } catch {
     }
-    return ticketJson;
   }
-  async openHookStream(host, ticket, signal) {
-    const streamResponse = await this.context.fetch(
-      `${host}/hooks/events?ticket=${encodeURIComponent(ticket)}`,
-      {
-        method: "GET",
-        headers: { accept: "text/event-stream" },
-        signal
-      }
+  /**
+   * Unreachable by construction. If the loop ever rejects anyway, fail its
+   * subscribers visibly instead of stranding them or crashing the process.
+   */
+  collapse() {
+    this._supervising = false;
+    this._phase?.interrupt.abort();
+    this._phase = void 0;
+    const error = serviceError(
+      ErrorCodes.NETWORK_ERROR,
+      "hook stream supervisor stopped unexpectedly",
+      "hooks"
     );
-    if (!streamResponse.ok) {
-      throw await responseError(
-        "hooks",
-        "failed to open hook stream",
-        streamResponse
-      );
-    }
-    return streamResponse;
+    this.report(error);
+    this.release(error);
+  }
+  onSessionChange(session) {
+    super.onSessionChange(session);
+    this._sessionGeneration += 1;
+    this.wake();
+  }
+  onSignOut() {
+    super.onSignOut();
+    this.release();
+    this.wake();
+  }
+  createHookHeaders(action, path) {
+    return this.context.invoke(this.session, "hooks", path, action);
   }
   createInvokeHeaders(subscriptions) {
     const entries = subscriptions.map((subscription) => ({
@@ -4326,11 +4739,168 @@ function buildScopePath(service, pathPrefix) {
   const normalized = normalizePathPrefix(pathPrefix);
   return normalized ? `${service}/${normalized}` : service;
 }
+function hookStreamRetryDelay(attempt) {
+  const cap = Math.min(
+    HOOK_STREAM_RETRY_BASE_DELAY_MS * 2 ** Math.max(0, attempt - 1),
+    HOOK_STREAM_RETRY_MAX_DELAY_MS
+  );
+  return cap / 2 + Math.random() * (cap / 2);
+}
+function isTerminalMintRefusal(status) {
+  return typeof status === "number" && status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
+var SUPERSEDED = /* @__PURE__ */ Symbol("hooks attempt superseded");
+async function awaitOwned(signal, operation) {
+  if (signal.aborted) {
+    if (typeof operation !== "function") {
+      void operation.then(cancelLateResponse, () => void 0);
+    }
+    throw SUPERSEDED;
+  }
+  const promise = typeof operation === "function" ? operation() : operation;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(SUPERSEDED);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        if (settled) {
+          cancelLateResponse(value);
+          return;
+        }
+        settled = true;
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      }
+    );
+  });
+}
+function cancelLateResponse(value) {
+  if (!(value instanceof Response) || !value.body) return;
+  try {
+    const cancellation = value.body.cancel();
+    void cancellation.then(() => void 0, () => void 0);
+  } catch {
+  }
+}
+function hookStreamRefusal(status) {
+  const code = typeof status === "number" ? status : void 0;
+  return serviceError(
+    ErrorCodes.NETWORK_ERROR,
+    `hook stream open refused: ${code ?? "unknown status"}`,
+    "hooks",
+    { meta: { phase: "open", status: code } }
+  );
+}
+var STREAM_ERROR_NAMES = /* @__PURE__ */ new Set([
+  "Error",
+  "TypeError",
+  "AbortError",
+  "TimeoutError",
+  "SyntaxError",
+  "RangeError",
+  "NetworkError"
+]);
+function hookStreamFailure(phase, thrown) {
+  const candidateName = readProperty(thrown, "name");
+  const name = typeof candidateName === "string" && STREAM_ERROR_NAMES.has(candidateName) ? candidateName : "Error";
+  const code = identifier(readProperty(thrown, "code")) ?? identifier(readProperty(readProperty(thrown, "cause"), "code"));
+  return serviceError(
+    ErrorCodes.NETWORK_ERROR,
+    `hook stream ${phase} failed: ${name}${code ? ` (${code})` : ""}`,
+    "hooks",
+    { meta: { phase, errorName: name, ...code ? { errorCode: code } : {} } }
+  );
+}
+var STREAM_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ECONNABORTED",
+  "ETIMEDOUT",
+  "EPIPE",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "EADDRNOTAVAIL",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_CLOSED",
+  "UND_ERR_ABORTED",
+  "UND_ERR_RESPONSE_STATUS_CODE",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "CERT_HAS_EXPIRED",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "ERR_SSL_WRONG_VERSION_NUMBER"
+]);
+function identifier(value) {
+  return typeof value === "string" && STREAM_ERROR_CODES.has(value) ? value : void 0;
+}
+function readProperty(value, key) {
+  if (value === null || typeof value !== "object" && typeof value !== "function") {
+    return void 0;
+  }
+  try {
+    return Reflect.get(value, key);
+  } catch {
+    return void 0;
+  }
+}
+function sleep(delayMs, _attempt, signal) {
+  return new Promise((resolve) => {
+    const finish = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", stop);
+      resolve();
+    };
+    const timer = setTimeout(finish, delayMs);
+    timer.unref?.();
+    const stop = () => finish();
+    if (signal.aborted) {
+      finish();
+    } else {
+      signal.addEventListener("abort", stop, { once: true });
+    }
+  });
+}
+function abortPromise(signal) {
+  let resolve;
+  const promise = new Promise((done) => {
+    resolve = done;
+  });
+  const onAbort = () => resolve();
+  if (signal.aborted) {
+    resolve();
+  } else {
+    signal.addEventListener("abort", onAbort, { once: true });
+  }
+  return {
+    promise,
+    dispose: () => signal.removeEventListener("abort", onAbort)
+  };
+}
 function normalizeSubscription(subscription) {
   return {
     ...subscription,
     pathPrefix: normalizePathPrefix(subscription.pathPrefix),
-    abilities: subscription.abilities ?? []
+    abilities: subscription.abilities ? [...subscription.abilities] : []
   };
 }
 function subscriptionSignature(subscription) {
@@ -4396,9 +4966,6 @@ async function responseError(service, message, response) {
     meta: { ...error.meta, status: response.status, statusText: response.statusText }
   };
 }
-function isAbortError(error) {
-  return error instanceof DOMException && error.name === "AbortError";
-}
 async function* parseSseStream(body, signal) {
   if (!body) {
     throw new Error("Hook stream response does not expose a readable body");
@@ -4427,11 +4994,24 @@ async function* parseSseStream(body, signal) {
 async function* readBodyChunks(body, signal) {
   const asyncIterable = body;
   if (typeof asyncIterable?.[Symbol.asyncIterator] === "function") {
-    for await (const chunk of asyncIterable) {
-      if (signal?.aborted) {
-        break;
+    const iterator = asyncIterable[Symbol.asyncIterator]();
+    const cancel = () => {
+      try {
+        const closing = iterator.return?.();
+        if (closing) void Promise.resolve(closing).then(() => void 0, () => void 0);
+      } catch {
       }
-      yield chunk;
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
+    try {
+      while (!signal?.aborted) {
+        const next = await iterator.next();
+        if (next.done) break;
+        yield next.value;
+      }
+    } finally {
+      signal?.removeEventListener("abort", cancel);
+      cancel();
     }
     return;
   }
@@ -4440,21 +5020,23 @@ async function* readBodyChunks(body, signal) {
     throw new Error("Unsupported hook stream body type");
   }
   const reader = stream.getReader();
+  const cancelReader = () => {
+    try {
+      const cancellation = reader.cancel?.();
+      if (cancellation) void cancellation.then(() => void 0, () => void 0);
+    } catch {
+    }
+  };
+  signal?.addEventListener("abort", cancelReader, { once: true });
   try {
     while (!signal?.aborted) {
       const { done, value } = await reader.read();
-      if (done) {
-        break;
-      }
-      if (value) {
-        yield value;
-      }
+      if (done) break;
+      if (value) yield value;
     }
   } finally {
-    try {
-      await reader.cancel?.();
-    } catch {
-    }
+    signal?.removeEventListener("abort", cancelReader);
+    cancelReader();
     reader.releaseLock?.();
   }
 }
@@ -6289,6 +6871,7 @@ var SecretsService = class {
   }
   async listAll() {
     const entries = /* @__PURE__ */ new Map();
+    const seenCursors = /* @__PURE__ */ new Set();
     let cursor;
     do {
       const result = await this.vault.listPage({
@@ -6311,6 +6894,14 @@ var SecretsService = class {
           "Secret catalog listing was truncated without a continuation cursor."
         );
       }
+      if (cursor !== void 0) {
+        if (seenCursors.has(cursor)) {
+          return invalidSecretInput(
+            "Secret catalog listing repeated a continuation cursor; the node does not support paged KV lists."
+          );
+        }
+        seenCursors.add(cursor);
+      }
     } while (cursor !== void 0);
     return {
       ok: true,
@@ -7089,10 +7680,10 @@ var EncryptionService = class extends BaseService {
   get crypto() {
     return this._config.crypto;
   }
-  async discoverNetwork(identifier, ownerDid) {
+  async discoverNetwork(identifier2, ownerDid) {
     this.assertActive();
     const result = await discoverNetwork({
-      identifier,
+      identifier: identifier2,
       ...ownerDid !== void 0 ? { ownerDid } : {},
       ...this._config.node !== void 0 ? { node: this._config.node } : {},
       ...this._config.wellKnown !== void 0 ? { wellKnown: this._config.wellKnown } : {}