@tinycloud/sdk-services 3.1.0-beta.9 → 3.2.0-beta.2

package/dist/index.js

@@ -1713,6 +1713,24 @@ 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,
@@ -1940,15 +1958,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")) {
@@ -1958,7 +1986,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"));
@@ -2051,19 +2096,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],
@@ -2254,7 +2299,7 @@ var KVService = class extends BaseService {
             );
           }
           if (response.status === 404) {
-            return this.classifyNotFound(response, key);
+            return await this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
           if (response.status === 413) {
@@ -2697,8 +2742,8 @@ var KVService = class extends BaseService {
   }
   /**
    * Map a failed `kv/sync` response. 410 and the retention 403 carry
-   * `{"error":{"code","reason"}}`; a revoked grant is a 401 whose text names
-   * `delegation-revoked` or `delegation-ancestor-revoked`. A body read that
+   * `{"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.
    */
@@ -2743,7 +2788,7 @@ var KVService = class extends BaseService {
       ));
     }
     if (response.status === 401) {
-      const revoked = /\bdelegation-ancestor-revoked\b/.test(errorText) ? ErrorCodes.AUTH_DELEGATION_ANCESTOR_REVOKED : /\bdelegation-revoked\b/.test(errorText) ? ErrorCodes.AUTH_DELEGATION_REVOKED : void 0;
+      const revoked = revocationCodeOf(errorText);
       if (revoked !== void 0) {
         return err(serviceError(revoked, `${context}: 401 - ${errorText}`, "kv", { meta }));
       }
@@ -2823,7 +2868,7 @@ var KVService = class extends BaseService {
             );
           }
           if (response.status === 404) {
-            return this.classifyNotFound(response, key);
+            return await this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
           if (response.status === 412) {
@@ -2890,7 +2935,7 @@ var KVService = class extends BaseService {
             );
           }
           if (response.status === 404) {
-            return this.classifyNotFound(response, key);
+            return await this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
           return err(
@@ -2956,7 +3001,7 @@ var KVService = class extends BaseService {
           signal: request.signal
         });
         if (!response.ok) {
-          return this.createSignedReadUrlError(response, key, path);
+          return await this.createSignedReadUrlError(response, key, path);
         }
         const signedUrl = this.normalizeSignedReadUrlResponse(
           await response.json()
@@ -3990,7 +4035,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);
@@ -4002,7 +4047,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() {
@@ -4010,20 +4070,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() {
@@ -4039,35 +4107,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) {
@@ -4208,146 +4273,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;
+      }
+      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;
       }
-      for (const subscription of subscriber.requested) {
-        merged.set(subscriptionSignature(subscription), subscription);
+      if (outcome.kind !== "ended") {
+        this.report(outcome.error);
       }
+      streak += 1;
+      await this.phase(
+        plan.key,
+        (signal) => this.pause(streak, signal)
+      );
     }
-    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;
+  /**
+   * 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();
+    }
+  }
+  /**
+   * 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) => ({
@@ -4378,11 +4589,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) {
@@ -4448,9 +4816,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");
@@ -4479,11 +4844,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 {
+      }
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
+    try {
+      while (!signal?.aborted) {
+        const next = await iterator.next();
+        if (next.done) break;
+        yield next.value;
       }
-      yield chunk;
+    } finally {
+      signal?.removeEventListener("abort", cancel);
+      cancel();
     }
     return;
   }
@@ -4492,21 +4870,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?.();
   }
 }
@@ -4912,6 +5292,12 @@ function defaultVaultMessage(input) {
       return input.message ?? `Public key not found for ${input.did}`;
     case "STORAGE_ERROR":
       return input.message ?? input.cause.message;
+    case "ALREADY_EXISTS":
+      return input.message ?? `A value already exists at ${input.key}`;
+    case "AUTH_UNAUTHORIZED":
+      return input.message;
+    case "PERMISSION_DENIED":
+      return input.message;
     case "STORAGE_QUOTA_EXCEEDED":
     case "STORAGE_LIMIT_REACHED":
       return input.message;
@@ -4925,13 +5311,33 @@ function vaultError(input) {
   };
   return { ok: false, error };
 }
+function typedKvCause(error) {
+  return Object.assign(new Error(error.message), {
+    name: "ServiceError",
+    code: error.code,
+    service: error.service,
+    ...error.meta !== void 0 ? { meta: error.meta } : {},
+    ...error.cause !== void 0 ? { cause: error.cause } : {}
+  });
+}
 function kvWriteError(context, error) {
   if (error.code === ErrorCodes.STORAGE_QUOTA_EXCEEDED || error.code === ErrorCodes.STORAGE_LIMIT_REACHED) {
     return vaultError({ code: error.code, message: error.message, meta: error.meta });
   }
+  const message = `${context}: ${error.message}`;
+  if (error.code === ErrorCodes.AUTH_UNAUTHORIZED) {
+    const code = authorizationVerdictOf(error) === "unauthenticated" ? "AUTH_UNAUTHORIZED" : "PERMISSION_DENIED";
+    return vaultError({
+      code,
+      message,
+      ...error.meta !== void 0 ? { meta: error.meta } : {},
+      cause: typedKvCause(error)
+    });
+  }
   return vaultError({
     code: "STORAGE_ERROR",
-    cause: new Error(`${context}: ${error.message}`)
+    cause: new Error(message, { cause: typedKvCause(error) }),
+    ...error.meta !== void 0 ? { meta: error.meta } : {}
   });
 }
 var DataVaultService = class extends BaseService {
@@ -5211,11 +5617,18 @@ var DataVaultService = class extends BaseService {
           cause: new Error(envelopeResult.error.message)
         });
       }
-      const valuePutResult = await this.tc.kv.put(
-        `vault/${key}`,
-        JSON.stringify(envelopeResult.data)
-      );
+      const valuePath = `vault/${key}`;
+      const valueBody = JSON.stringify(envelopeResult.data);
+      const valuePutResult = options?.ifNoneMatch !== void 0 ? await this.tc.kv.put(valuePath, valueBody, { ifNoneMatch: options.ifNoneMatch }) : await this.tc.kv.put(valuePath, valueBody);
       if (!valuePutResult.ok) {
+        if (options?.ifNoneMatch !== void 0 && valuePutResult.error.code === ErrorCodes.KV_PRECONDITION_FAILED) {
+          return vaultError({
+            code: "ALREADY_EXISTS",
+            key,
+            ...valuePutResult.error.meta !== void 0 ? { meta: valuePutResult.error.meta } : {},
+            cause: typedKvCause(valuePutResult.error)
+          });
+        }
         return kvWriteError("Failed to store encrypted value", valuePutResult.error);
       }
       return { ok: true, data: void 0 };
@@ -5383,6 +5796,14 @@ var DataVaultService = class extends BaseService {
       if (this.usesNetworkEncryption) {
         return this.putNetworkEncrypted(key, value, options);
       }
+      if (options?.ifNoneMatch !== void 0) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            "ifNoneMatch is only supported by network-encrypted vaults"
+          )
+        });
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -6194,6 +6615,35 @@ var SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
 var SECRET_PREFIX = "secrets/";
 var SCOPED_SECRET_PREFIX = "secrets/scoped/";
 var RESERVED_SECRET_SCOPES = /* @__PURE__ */ new Set(["default", "global"]);
+var SECRET_SCOPE_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var MAX_SECRET_SCOPE_LENGTH = 64;
+var TC832_RESERVED_SCOPES = Object.freeze([
+  "default",
+  "global",
+  "scoped"
+]);
+function appSecretScope(appId) {
+  if (appId.trim() === "") {
+    throw new Error("App id must be non-empty to derive a secret scope.");
+  }
+  const scope = appId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (scope === "") {
+    throw new Error(
+      `App id ${JSON.stringify(appId)} must contain at least one letter or number.`
+    );
+  }
+  if (scope.length > MAX_SECRET_SCOPE_LENGTH) {
+    throw new Error(
+      `App id ${JSON.stringify(appId)} yields a secret scope longer than ${MAX_SECRET_SCOPE_LENGTH} characters.`
+    );
+  }
+  if (TC832_RESERVED_SCOPES.includes(scope)) {
+    throw new Error(
+      `App id ${JSON.stringify(appId)} yields the reserved secret scope ${JSON.stringify(scope)}.`
+    );
+  }
+  return scope;
+}
 function canonicalizeSecretScope(scope) {
   if (scope === void 0) {
     return void 0;
@@ -6306,11 +6756,12 @@ var SecretsService = class {
     const secretPath = resolveSecretPathResult(name, options);
     if ("ok" in secretPath) return secretPath;
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    return this.vault.put(secretPath.vaultKey, {
+    const payload = {
       value,
       createdAt: now,
       updatedAt: now
-    });
+    };
+    return options?.ifAbsent === true ? this.vault.put(secretPath.vaultKey, payload, { ifNoneMatch: "*" }) : this.vault.put(secretPath.vaultKey, payload);
   }
   async delete(name, options) {
     const secretPath = resolveSecretPathResult(name, options);
@@ -7150,10 +7601,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 } : {}
@@ -7365,11 +7816,13 @@ export {
   KVListResultSchema,
   KVResponseHeadersSchema,
   KVService,
+  MAX_SECRET_SCOPE_LENGTH,
   NETWORK_NAME_PATTERN,
   NetworkIdError,
   PrefixedKVService,
   RetryPolicySchema,
   SECRET_NAME_RE,
+  SECRET_SCOPE_RE,
   SQLAction,
   SQLMigrations,
   SQLService,
@@ -7383,6 +7836,7 @@ export {
   ServiceResponseEventSchema,
   ServiceRetryEventSchema,
   ServiceSessionSchema,
+  TC832_RESERVED_SCOPES,
   TelemetryEvents,
   TelemetrySpanEventSchema,
   TinyCloudDebugLogger,
@@ -7390,6 +7844,7 @@ export {
   VaultHeaders,
   VaultPublicSpaceKVActions,
   abortedError,
+  appSecretScope,
   authExpiredError,
   authRequiredError,
   authUnauthorizedError,