@muhkoo/connect 0.15.0-alpha.4 → 0.15.0-alpha.6

package/dist/server/index.js

@@ -2742,6 +2742,106 @@ class BroadcastChannel {
     }
 }
 
+/**
+ * `HttpError` — thrown for any non-2xx accelerator response.
+ *
+ * In a module of its own so that `PaymentRequiredError` can extend it while
+ * `HttpClient`, which throws both, imports `PaymentRequiredError`: with the
+ * class in `HttpClient.ts`, the two modules would import each other, and
+ * whichever loaded second would extend a class not yet defined. `HttpClient`
+ * re-exports it, so `import { HttpError } from "./HttpClient"` still works.
+ */
+/** Thrown for any non-2xx accelerator response. Carries the HTTP status. */
+class HttpError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "HttpError";
+    }
+}
+
+/**
+ * `PaymentRequiredError` — a write the accelerator refused for payment
+ * (accelerator spec 2026-10-06-paid-accounts-and-past-due, "Interfaces and
+ * contracts").
+ *
+ * The accelerator answers such a write with a 402 whose body carries one of
+ * three codes:
+ *   - `user_plan_required`: the app takes paid Muhkoo plans only, and the
+ *     signed-in user is on Free;
+ *   - `user_payment_past_due`: the user's own Muhkoo payment is past due. Only
+ *     first-party apps are told this; every other app is told
+ *     `user_plan_required` instead;
+ *   - `owner_payment_past_due`: the app owner's payment is past due, so the
+ *     app stores nothing new for anyone.
+ * Reads, sign-in and deletes still work in all three cases.
+ *
+ * Every other 402 — the Free-tier refusals that carry `quotaExceeded`,
+ * `requiresPaidTier` or `freeTierFull` — has no `code`, and stays a plain
+ * `HttpError`, as before.
+ */
+const CODES = new Set([
+    "user_plan_required",
+    "user_payment_past_due",
+    "owner_payment_past_due",
+]);
+/** True for one of the three {@link PaymentRequiredCode}s. */
+function isPaymentRequiredCode(value) {
+    return typeof value === "string" && CODES.has(value);
+}
+/** `url` when it is an absolute http(s) URL, else undefined: an app may put it straight into a link. */
+function absoluteHttpUrl(url) {
+    return typeof url === "string" && /^https?:\/\/[^/]/i.test(url) ? url : undefined;
+}
+/** Thrown for a 402 whose body carries one of the three {@link PaymentRequiredCode}s. */
+class PaymentRequiredError extends HttpError {
+    /** Why the write was refused. */
+    code;
+    /**
+     * Where to send the user: the portal's upgrade page or its billing page,
+     * as an absolute URL. Set only when the server sent an absolute http(s)
+     * URL. The relative `upgradeUrl` of the Free-tier refusals is never here:
+     * those are not this error.
+     */
+    upgradeUrl;
+    constructor(message, code, body, upgradeUrl) {
+        super(message, 402, body);
+        this.name = "PaymentRequiredError";
+        this.code = code;
+        if (upgradeUrl !== undefined)
+            this.upgradeUrl = upgradeUrl;
+    }
+}
+/**
+ * The error to throw for a refused response: a {@link PaymentRequiredError}
+ * for a 402 whose body carries one of the three codes, and null for anything
+ * else, so the caller throws what it threw before. `body` is the parsed JSON,
+ * or the raw text of the response, which is parsed here.
+ */
+function paymentRequiredFrom(status, body) {
+    if (status !== 402)
+        return null;
+    let parsed = body;
+    if (typeof parsed === "string") {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const { code, error, upgradeUrl } = parsed;
+    if (!isPaymentRequiredCode(code))
+        return null;
+    const message = typeof error === "string" && error ? error : `Payment required (${code})`;
+    return new PaymentRequiredError(message, code, parsed, absoluteHttpUrl(upgradeUrl));
+}
+
 function _loadWasmModule (sync, filepath, src, imports) {
   function _instantiateOrCompile(source, imports, stream) {
     var instantiateFunc = WebAssembly.instantiate;
@@ -5261,14 +5361,19 @@ function nonceHexToFieldString(nonceHex) {
  */
 async function parseOrThrow$1(response, label) {
     if (!response.ok) {
-        let detail = "";
+        let text = "";
         try {
-            const text = await response.text();
-            detail = text ? `: ${text}` : "";
+            text = await response.text();
         }
         catch {
             // ignore — we'll just use the status code
         }
+        // A put refused for payment: its own class. Every other failure is the
+        // plain Error it always was.
+        const refused = paymentRequiredFrom(response.status, text);
+        if (refused)
+            throw refused;
+        const detail = text ? `: ${text}` : "";
         throw new Error(`PersonalSpaceClient ${label} failed (${response.status})${detail}`);
     }
     return (await response.json());
@@ -5916,6 +6021,8 @@ class ShardClient {
     baseUrl;
     pathPrefix;
     fetchFn;
+    /** What a PUT goes through: {@link ShardClientOptions.fetchWithRecovery} when given, else {@link fetchFn}. */
+    putFn;
     cache;
     /** Hashes waiting for the next batch, each with everyone awaiting it and its size if a caller gave it. */
     pendingShards;
@@ -5940,6 +6047,7 @@ class ShardClient {
             throw new Error("ShardClient: `globalThis.fetch` is unavailable; pass an explicit fetch.");
         }
         this.fetchFn = f.bind(globalThis);
+        this.putFn = opts.fetchWithRecovery ?? this.fetchFn;
         this.cache = opts.cache;
         // Coalescing state. `batchSupported` latches false against a deployment
         // without the batch route, so we degrade once rather than per request.
@@ -5983,7 +6091,7 @@ class ShardClient {
         }
         let response;
         try {
-            response = await this.fetchFn(url, {
+            response = await this.putFn(url, {
                 method: "PUT",
                 headers: { "content-type": "application/octet-stream" },
                 // BufferSource is what fetch's body expects; a Uint8Array satisfies it.
@@ -6001,7 +6109,10 @@ class ShardClient {
         }
         if (!response.ok) {
             const text = await safeText(response);
-            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
+            // Refused for payment: its own class, which the offline queue keeps
+            // and an app can tell from any other failure.
+            throw paymentRequiredFrom(response.status, text)
+                ?? new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
         }
         let dedup = false;
         try {
@@ -6053,14 +6164,15 @@ class ShardClient {
     /** PUT the shard bytes to origin, verifying the server accepted them.
      *  Used by the background-upload path; throws on network/HTTP failure. */
     async uploadToOrigin(url, hash, bytes) {
-        const response = await this.fetchFn(url, {
+        const response = await this.putFn(url, {
             method: "PUT",
             headers: { "content-type": "application/octet-stream" },
             body: bytes,
         });
         if (!response.ok) {
             const text = await safeText(response);
-            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
+            throw paymentRequiredFrom(response.status, text)
+                ?? new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
         }
     }
     /**
@@ -6344,6 +6456,15 @@ async function safeText(response) {
  * manifest and reassembles the plaintext; {@link FileStorage.readFile} first
  * fetches the manifest from the space.
  */
+/**
+ * How many chunks past the one being read a multi-chunk read fetches ahead
+ * (see `chunksInOrder`). Two: enough to keep requests overlapping on a link
+ * where each one waits on its round trip. While the caller holds chunk k,
+ * up to `READ_AHEAD_CHUNKS + 1` more chunks can be in flight (the next
+ * starts as k is handed over), so at the default 4 MB chunk about 16 MB of
+ * reads in flight per file, on top of the chunk held.
+ */
+const READ_AHEAD_CHUNKS = 2;
 class FileStorage {
     space;
     shards;
@@ -6449,11 +6570,10 @@ class FileStorage {
         await this.codec.ready(this.rsWasmModule);
         // Materialize each chunk into plaintext, then concatenate. We don't
         // stream across chunks here because the consuming surface returns
-        // `Uint8Array`; a streaming variant would reuse `readChunk` unchanged.
+        // `Uint8Array`; `readChunksFromShards` is the streaming variant.
         const plaintextChunks = [];
-        for (const chunkManifest of [...manifest.chunks].sort((a, b) => a.chunkIndex - b.chunkIndex)) {
-            plaintextChunks.push(await this.readChunk(chunkManifest));
-        }
+        for await (const chunk of this.chunksInOrder(manifest))
+            plaintextChunks.push(chunk);
         let total = 0;
         for (const c of plaintextChunks)
             total += c.length;
@@ -6474,8 +6594,48 @@ class FileStorage {
      */
     async *readChunksFromShards(manifest) {
         await this.codec.ready(this.rsWasmModule);
-        for (const chunkManifest of [...manifest.chunks].sort((a, b) => a.chunkIndex - b.chunkIndex)) {
-            yield await this.readChunk(chunkManifest);
+        yield* this.chunksInOrder(manifest);
+    }
+    /**
+     * Each chunk's plaintext, in order, with the next {@link READ_AHEAD_CHUNKS}
+     * already being fetched.
+     *
+     * One chunk at a time, a large file cost a full round trip per 4 MB chunk
+     * with nothing overlapping it: a 33 MB file was eight serial requests,
+     * each mostly waiting. Within a chunk the shard reads were already
+     * parallel; this overlaps the chunks too.
+     *
+     * Bounded on purpose: while the caller holds a yielded chunk, at most
+     * `1 + READ_AHEAD_CHUNKS` more are in flight, and nothing new starts until
+     * it asks for the next — a slow consumer of the stream is not run away
+     * from. A failure surfaces at its own chunk, in order; reads already
+     * started past it are let finish, their failures swallowed rather than
+     * left unhandled. If the caller stops early (`break` or `return()`), no
+     * further read starts and the ones in flight settle on their own; they are
+     * not awaited, so `return()` is not delayed by a slow shard.
+     */
+    async *chunksInOrder(manifest) {
+        const ordered = [...manifest.chunks].sort((a, b) => a.chunkIndex - b.chunkIndex);
+        const ahead = [];
+        let next = 0;
+        const start = () => {
+            const read = this.readChunk(ordered[next++]);
+            read.catch(() => { }); // reported when its turn comes
+            ahead.push(read);
+        };
+        while (next < ordered.length && ahead.length < 1 + READ_AHEAD_CHUNKS)
+            start();
+        try {
+            while (ahead.length > 0) {
+                const chunk = await ahead.shift();
+                if (next < ordered.length)
+                    start();
+                yield chunk;
+            }
+        }
+        finally {
+            next = ordered.length; // nothing more is started
+            ahead.length = 0; // in-flight reads settle unobserved; each has its own .catch
         }
     }
     // -------------------------------------------------------------------------
@@ -6723,6 +6883,10 @@ async function parseOrThrow(response, op) {
         // non-JSON body
     }
     if (!response.ok) {
+        // A manifest write refused for payment (a gated Space write): its own class.
+        const refused = paymentRequiredFrom(response.status, parsed);
+        if (refused)
+            throw refused;
         const msg = parsed && typeof parsed === "object" && "error" in parsed
             ? String(parsed.error)
             : `${response.status} ${response.statusText}`;
@@ -6739,7 +6903,7 @@ async function parseOrThrow(response, op) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.15.0-alpha.4";
+const VERSION = "0.15.0-alpha.6";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -6784,17 +6948,6 @@ function reqPath(input) {
         return "?";
     }
 }
-/** Thrown for any non-2xx accelerator response. Carries the HTTP status. */
-class HttpError extends Error {
-    status;
-    body;
-    constructor(message, status, body) {
-        super(message);
-        this.status = status;
-        this.body = body;
-        this.name = "HttpError";
-    }
-}
 class HttpClient {
     baseUrl;
     /** Origin of {@link baseUrl} — credentials are only attached same-origin. */
@@ -6923,7 +7076,9 @@ class HttpClient {
             const msg = parsed && typeof parsed === "object" && "error" in parsed
                 ? String(parsed.error)
                 : `${res.status} ${res.statusText}`;
-            throw new HttpError(msg, res.status, parsed);
+            // A refusal for payment is its own class, so an app can tell it from
+            // any other 4xx; every other error is the HttpError it always was.
+            throw paymentRequiredFrom(res.status, parsed) ?? new HttpError(msg, res.status, parsed);
         }
         return parsed;
     }
@@ -9667,6 +9822,7 @@ class StorageNamespace {
                 baseUrl: this.deps.baseUrl,
                 pathPrefix: "/api/shards",
                 fetch: this.deps.http.fetch,
+                fetchWithRecovery: this.deps.http.fetchWithRecovery,
                 cache: this.deps.shardCache,
                 deferUpload: this.deps.deferShardUpload,
             });
@@ -9685,6 +9841,59 @@ class StorageNamespace {
     }
 }
 
+/**
+ * `POST /api/storage/commit` and `/api/storage/release`: take or drop a
+ * reference to a manifest's shards.
+ *
+ * The commit is what meters a file's bytes to the app and reference-counts
+ * its shards, so garbage collection keeps them; the release drops that
+ * reference. The body is `{ hashes, bytes }` and nothing else. The accelerator
+ * keys its reference ledger on the caller, the app, the bytes and the sorted
+ * hashes, so this body must not change: a commit sent in another shape would
+ * take a second reference instead of finding the first.
+ *
+ * Shared by `Space` (`putFile`, `commitFile`, `releaseFile`) and by
+ * `client.vfs`, which takes and drops references here directly. A reference
+ * names only shards and needs no Space; opening the content space to take one
+ * created that space for a user who had never written a file, which a
+ * paid-only app refuses for a Free user (accelerator spec
+ * 2026-10-06-paid-accounts-and-past-due, D12).
+ *
+ * Internal: not re-exported from any barrel.
+ */
+/**
+ * Commit or release `manifest`'s shards through `fetchFn`, which should be
+ * `HttpClient.fetchWithRecovery`, so a dead session is re-established once
+ * rather than refused three times. Best-effort: tries three times, or once
+ * for a 401, then warns and returns, without failing the caller's write.
+ */
+async function commitManifest(fetchFn, httpBaseUrl, manifest, action) {
+    const hashes = manifest.chunks.flatMap((c) => c.shardHashes);
+    if (hashes.length === 0)
+        return;
+    const body = JSON.stringify({ hashes, bytes: manifest.size });
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const res = await fetchFn(`${httpBaseUrl}/api/storage/${action}`, {
+                method: "POST", headers: { "Content-Type": "application/json" }, body,
+            });
+            if (res.ok)
+                return;
+            // A 401 that `fetchFn`'s recovery could not fix. Another try
+            // would only run that recovery again (`auth.zk.recover()`, and
+            // `onSessionExpired` for the app) and be refused again.
+            if (res.status === 401)
+                break;
+        }
+        catch { /* retry */ }
+        await new Promise((r) => setTimeout(r, 400 * (attempt + 1)));
+    }
+    // Best-effort: a missed commit leaves the shards to orphan-GC (still not
+    // durable-unmetered long-term); a missed release just delays GC. Reconciled
+    // by the platform sweep. Don't fail the caller's write on a metering hiccup.
+    console.warn(`[muhkoo] storage ${action} did not confirm for ${hashes.length} shard(s)`);
+}
+
 /**
  * SpaceCipher — pure crypto for the fan-out group-encryption layer.
  *
@@ -11068,25 +11277,10 @@ class Space {
     }
     /** Commit/release a manifest's shards with the accelerator (metering + refcount). */
     async commitShards(manifest, action) {
-        const hashes = manifest.chunks.flatMap((c) => c.shardHashes);
-        if (hashes.length === 0)
-            return;
-        const body = JSON.stringify({ hashes, bytes: manifest.size });
-        for (let attempt = 0; attempt < 3; attempt++) {
-            try {
-                const res = await this.deps.fetch(`${this.deps.httpBaseUrl}/api/storage/${action}`, {
-                    method: "POST", headers: { "Content-Type": "application/json" }, body,
-                });
-                if (res.ok)
-                    return;
-            }
-            catch { /* retry */ }
-            await new Promise((r) => setTimeout(r, 400 * (attempt + 1)));
-        }
-        // Best-effort: a missed commit leaves the shards to orphan-GC (still not
-        // durable-unmetered long-term); a missed release just delays GC. Reconciled
-        // by the platform sweep. Don't fail the caller's write on a metering hiccup.
-        console.warn(`[muhkoo] storage ${action} did not confirm for ${hashes.length} shard(s)`);
+        // Through the client's 401 recovery when there is one: the commit refuses
+        // a dead session with 401, and three tries with the same token only
+        // delayed the warning.
+        await commitManifest(this.deps.fetchWithRecovery ?? this.deps.fetch, this.deps.httpBaseUrl, manifest, action);
     }
     fileStorage(backgroundUpload = false) {
         // Global, content-addressed shard store — same store `client.storage`
@@ -11097,6 +11291,7 @@ class Space {
             baseUrl: this.deps.httpBaseUrl,
             pathPrefix: "/api/shards",
             fetch: this.deps.fetch,
+            fetchWithRecovery: this.deps.fetchWithRecovery,
             cache: this.deps.shardCache,
             deferUpload: this.deps.deferShardUpload,
             peers: this.peerNet?.exchange,
@@ -11500,6 +11695,7 @@ class MessageNamespace {
             wsBaseUrl: this.deps.wsBaseUrl,
             httpBaseUrl: this.deps.http.baseUrl,
             fetch: this.deps.http.fetch,
+            fetchWithRecovery: this.deps.http.fetchWithRecovery,
             myId: () => this.myId(),
             fetchTicket: () => this.fetchTicket(),
         });
@@ -13821,6 +14017,7 @@ class SpaceNamespace {
                 wsBaseUrl: this.deps.wsBaseUrl,
                 httpBaseUrl: this.deps.http.baseUrl,
                 fetch: this.deps.http.fetch,
+                fetchWithRecovery: this.deps.http.fetchWithRecovery,
                 myId: () => memberId,
                 fetchTicket: () => this.fetchTicket(),
                 historyPolicy,
@@ -13876,6 +14073,7 @@ class SpaceNamespace {
             wsBaseUrl: this.deps.wsBaseUrl,
             httpBaseUrl: this.deps.http.baseUrl,
             fetch: this.deps.http.fetch,
+            fetchWithRecovery: this.deps.http.fetchWithRecovery,
             myId: () => memberId,
             fetchTicket: () => this.fetchTicket(),
             keyring,
@@ -14251,6 +14449,66 @@ class AccessTokensNamespace {
     }
 }
 
+/**
+ * `client.app` — what the signed-in user may do in this app (accelerator spec
+ * 2026-10-06-paid-accounts-and-past-due, B6 and B8).
+ *
+ * An app's owner can turn on "Paid Muhkoo accounts only" in the portal. The
+ * accelerator then refuses a Free user's writes that add data, with a 402 the
+ * SDK throws as `PaymentRequiredError`. Reads, sign-in and deletes still work.
+ * The same refusal reaches every user of an app whose owner's payment is past
+ * due, whether or not the setting is on.
+ *
+ * `access()` asks up front, so an app can show the right screen before the
+ * first refusal.
+ */
+class AppNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Whether the signed-in user may add data in this app and, if not, why
+     * and where to send them. Needs the app key and a session; a stale session
+     * is re-established once, as for every request. The route is never
+     * refused for payment. Throws `HttpError` for anything else, among them a
+     * 401 without a session and a 404 from an accelerator older than the
+     * route.
+     *
+     * Each `allowed: true` also sends any writes the offline queue kept after
+     * a refusal for payment, without waiting for them. Call it after sign-in,
+     * and again when the user comes back from the portal.
+     */
+    async access() {
+        const body = await this.deps.http.get("/api/app/access");
+        const access = {
+            paidAccountsOnly: body?.paidAccountsOnly === true,
+            // Fail open on a malformed answer: the server enforces the gate
+            // whatever this says, so a wrong "allowed" costs a refused write,
+            // and a wrong "not allowed" would lock the user out for nothing.
+            allowed: body?.allowed !== false,
+        };
+        if (!access.allowed) {
+            if (isPaymentRequiredCode(body?.reason))
+                access.reason = body.reason;
+            const upgradeUrl = absoluteHttpUrl(body?.upgradeUrl);
+            if (upgradeUrl)
+                access.upgradeUrl = upgradeUrl;
+        }
+        else if (this.deps.onAllowed) {
+            // A drain that fails, or a callback that throws, must not turn a
+            // good answer into an error: the writes stay queued for the next
+            // reconnect.
+            Promise.resolve()
+                .then(() => this.deps.onAllowed())
+                .catch((err) => {
+                console.warn("[client.app] sending the kept writes failed (they stay queued):", err);
+            });
+        }
+        return access;
+    }
+}
+
 /**
  * POST /api/auth/identity (SpecA §4.1 as amended by CS-7). An unknown name
  * answers a deterministic decoy, so a lookup never says whether an account
@@ -20158,9 +20416,14 @@ class ConnectivityManager {
  * mutation by re-invoking the real namespace method (with an `isReplay` flag so
  * it doesn't re-enqueue). `drain()` replays entries in HLC order:
  *   - success → remove the entry;
- *   - permanent failure (4xx, or a Space whose member list refuses this user)
- *     → drop it and surface a `SYNC_ERROR` (a write the server will never
- *     accept must not wedge the queue forever);
+ *   - refused for payment (`PaymentRequiredError`: the app takes paid plans
+ *     only, or someone's payment is past due) → keep it and everything after
+ *     it, stop, and surface a `SYNC_ERROR` with `dropped: false`. The server
+ *     accepts it once the user or the app owner pays, so it waits for the next
+ *     reconnect, or for `client.app.access()` to report the app allowed;
+ *   - permanent failure (any other 4xx, or a Space whose member list refuses
+ *     this user) → drop it and surface a `SYNC_ERROR` (a write the server will
+ *     never accept must not wedge the queue forever);
  *   - transient/network failure → stop draining and leave the rest for the next
  *     reconnect.
  *
@@ -20185,14 +20448,34 @@ class OutboundQueue {
     register(domain, replayer) {
         this.replayers.set(domain, replayer);
     }
-    /** Record a mutation for later replay; resolves with its assigned seq. */
+    /**
+     * Record a mutation for later replay; resolves with its assigned seq.
+     * Stamped with the signed-in user's commitment, so that it is only ever
+     * sent under their session (see {@link waiting}).
+     */
     enqueue(entry) {
-        return this.store.enqueue(entry);
+        const who = entry.commitment ?? this.opts.commitment?.();
+        return this.store.enqueue(who ? { ...entry, commitment: who } : entry);
     }
-    /** Number of writes still awaiting sync. */
+    /** Number of writes still awaiting sync, every user's. */
     async pending() {
         return (await this.store.queued()).length;
     }
+    /**
+     * The writes a drain would send now, in order: the signed-in user's, and
+     * any an older SDK queued without saying whose they are. Every tab of an
+     * origin shares this queue, and every replayer builds its request from
+     * the session signed in when it runs, so another user's write sent now
+     * would land in this user's space, or overwrite their data. It stays
+     * queued, as it is, until its own user signs in on this device again.
+     */
+    async waiting() {
+        return (await this.store.queued()).filter((entry) => this.sendable(entry));
+    }
+    /** True for an entry this drain may send: the signed-in user's, or one with no user. */
+    sendable(entry) {
+        return !entry.commitment || entry.commitment === this.opts.commitment?.();
+    }
     /**
      * Replay queued mutations in HLC order. Coalesces concurrent calls into a
      * single in-flight drain. Stops on the first transient failure, leaving the
@@ -20214,21 +20497,36 @@ class OutboundQueue {
      */
     async drainOnce() {
         const who = this.opts.commitment?.();
-        if (!this.opts.tryLock || !who)
-            return this.runDrain();
+        if (!this.opts.tryLock || !who) {
+            await this.runDrain();
+            return;
+        }
         await this.opts.tryLock(`muhkoo:offline-drain:${who}`, async () => {
             // A tab that found this one draining skipped its own drain, and
             // what it queued after this pass read the queue was left to this
-            // tab. So drain until a pass leaves nothing; a transient failure
-            // still stops it, by throwing.
+            // tab. So drain until a pass leaves nothing of this user's; a
+            // transient failure still stops it, by throwing. So does a write
+            // refused for payment, which stays queued: another pass would
+            // only be refused again, at once and without end. Another user's
+            // writes never leave, so counting them would loop for ever too.
             do {
-                await this.runDrain();
-            } while ((await this.store.queued()).length > 0);
+                if (!(await this.runDrain()))
+                    return;
+            } while ((await this.waiting()).length > 0);
         });
     }
+    /**
+     * One pass over the queue. False when a write refused for payment stopped
+     * it, which leaves that write and everything after it queued.
+     */
     async runDrain() {
         const entries = await this.store.queued();
         for (const entry of entries) {
+            // Another user's write, theirs to send under their own session.
+            // Asked per entry, so a sign-out in the middle of a pass stops
+            // the rest of it going out under the next user's session.
+            if (!this.sendable(entry))
+                continue;
             const replayer = this.replayers.get(entry.domain);
             if (!replayer) {
                 // No handler registered (namespace not wired) — drop it rather
@@ -20245,6 +20543,22 @@ class OutboundQueue {
                 });
             }
             catch (err) {
+                // Asked before `isPermanent`, which would drop it as a 4xx.
+                if (err instanceof PaymentRequiredError) {
+                    // The user's plan, or a payment past due: the server will
+                    // accept this write once that changes. Keep it, and keep
+                    // every write after it in order; a delete queued after an
+                    // upload never goes first. Stop rather than send the rest,
+                    // which the server would refuse for the same reason.
+                    EventCore.emit(EventCoreEvents.SYNC_ERROR, {
+                        domain: entry.domain,
+                        method: entry.method,
+                        error: err.message,
+                        code: err.code,
+                        dropped: false,
+                    });
+                    return false;
+                }
                 if (isPermanent(err)) {
                     await this.store.dequeue(entry.seq);
                     EventCore.emit(EventCoreEvents.SYNC_ERROR, {
@@ -20259,12 +20573,14 @@ class OutboundQueue {
                 throw err;
             }
         }
+        return true;
     }
 }
 /** A 4xx is the server permanently refusing the write, and so is a Space whose
  *  member list does not admit this user (design §4.5.12): the relay refuses
  *  their frames. Anything else, a locked session included, is worth retrying
- *  on the next reconnect. */
+ *  on the next reconnect. A refusal for payment is a 4xx that is not
+ *  permanent; `runDrain` keeps it before asking this. */
 function isPermanent(err) {
     if (err instanceof AdmissionDeniedError)
         return true;
@@ -20537,6 +20853,22 @@ class OfflineManager {
             args: { hash },
         });
     }
+    /**
+     * Replay the queue now, as a reconnect does, if anything is waiting in it.
+     * `client.app.access()` calls this each time it reports the app allowed,
+     * so writes kept after a refusal for payment go out once the user or the
+     * app owner has paid, without waiting for the next reconnect. One drain per
+     * call, never on a timer. With nothing of the signed-in user's queued it
+     * does not drain at all, so the app sees no "syncing". A drain also runs the
+     * catch-up tasks (Space history paging), as a reconnect does.
+     */
+    async resume() {
+        if (!this.enabled)
+            return;
+        if ((await this.queue.waiting()).length === 0)
+            return;
+        await this.sync.run();
+    }
     /** Resolve once the clock + node id are loaded. */
     ready() {
         return this.bootPromise;
@@ -21086,6 +21418,8 @@ class Client {
     functions;
     /** Access tokens — `client.accessTokens.create(appId, …)`, etc. */
     accessTokens;
+    /** This app — `client.app.access()`: may the signed-in user add data here? */
+    app;
     /** Offline cache + sync — `client.offline.status`, `client.offline.snapshot`, etc. */
     offline;
     session;
@@ -21265,12 +21599,15 @@ class Client {
                 // the capability path, so it keeps working for a file whose
                 // handle was shared from someone else's filesystem.
                 read: async (manifest) => (await this.storage.readByManifest(manifest)).data,
-                release: async (manifest) => {
-                    await (await resolveContentSpace()).releaseFile(manifest);
-                },
-                retain: async (manifest) => {
-                    await (await resolveContentSpace()).commitFile(manifest);
-                },
+                // A reference names only shards, so taking or dropping one needs
+                // no Space. Opening the content space here created it for a user
+                // who had never written a file: a checkout, a copy, a delete, or
+                // Cloud Drive's move of its pre-VFS files. A paid-only app refuses
+                // that creation for a Free user (accelerator spec
+                // 2026-10-06-paid-accounts-and-past-due, D12). Same body as
+                // `Space.commitFile`, so it is the same reference.
+                release: (manifest) => commitManifest(this.http.fetchWithRecovery, this.baseUrl, manifest, "release"),
+                retain: (manifest) => commitManifest(this.http.fetchWithRecovery, this.baseUrl, manifest, "commit"),
             },
         });
         // Sealed into the SAME personal store as the VFS metadata, so a project
@@ -21339,6 +21676,9 @@ class Client {
         this.agents = new AgentsNamespace({ http: this.http });
         this.functions = new FunctionsNamespace({ http: this.http, fnHostSuffix: options.functionsHostSuffix });
         this.accessTokens = new AccessTokensNamespace({ http: this.http });
+        // Each "allowed" sends what the offline queue kept after a refusal for
+        // payment, without waiting for the next reconnect.
+        this.app = new AppNamespace({ http: this.http, onAllowed: () => this.offline.resume() });
         // Replay deferred shard uploads on reconnect. The bytes live in the
         // Cache API keyed by hash; re-PUT them through a (defer-free) shard
         // client so a failure surfaces as transient and the entry stays queued.
@@ -21347,6 +21687,7 @@ class Client {
                 baseUrl: this.baseUrl,
                 pathPrefix: "/api/shards",
                 fetch: this.http.fetch,
+                fetchWithRecovery: this.http.fetchWithRecovery,
                 cache: this.offline.fileCache,
             });
             this.offline.registerReplayer("file", async (entry) => {
@@ -21758,5 +22099,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
   default: loadRsWasm
 });
 
-export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES$1 as AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES$1 as AES_GCM_TAG_BYTES, AccessTokensNamespace, AdmissionDeniedError, AgentsNamespace, AuthClient, AuthHttpError, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, CircuitIntegrityError, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_BRANCH, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, DevicePairingError, DeviceRevokedError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IdentityLockedError, IdentityUnavailableError, IndexedDbStore, KEEPER_MEMBER_ID$1 as KEEPER_MEMBER_ID, KeyStore, KeyringClient, KeyringHttpError, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NOT_MEMBER_CLOSE_CODE, NOT_MEMBER_RECHECK_MS, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PINNED_CIRCUIT_DIGESTS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, ROOT_ID, Ready, ReauthRequiredError, ReedSolomonCodec, Repo, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, SpaceTrustError, StorageNamespace, SyncEngine, VERSION, VFS_ROOT_INFO, VaultProtocolMismatchError, VaultUnavailableError, VcsError, VcsNamespace, VfsConflictError, VfsCorruptRecordError, VfsLimitError, VfsLockedError, VfsNamespace, VfsNotFoundError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes$1 as concatBytes, configureDeviceStore, createPasskeyWithPrf, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultRpId, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, dirKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, evaluatePasskeyPrf, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$2 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, headKey, historyKey, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, isSameOriginPath, loadDeviceIdentity, log, manifestToStat, materializeRow, merge3, merge3Text, mergeKey, mergeMap, mergeMessage, mergeRegister, messageKey, objectKey, pack, padHandle, pairingVerificationCode, passkeyPrfCapable, passkeySupported, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, refKey, refsIndexKey, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$2 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
+export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES$1 as AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES$1 as AES_GCM_TAG_BYTES, AccessTokensNamespace, AdmissionDeniedError, AgentsNamespace, AppNamespace, AuthClient, AuthHttpError, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, CircuitIntegrityError, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_BRANCH, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, DevicePairingError, DeviceRevokedError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IdentityLockedError, IdentityUnavailableError, IndexedDbStore, KEEPER_MEMBER_ID$1 as KEEPER_MEMBER_ID, KeyStore, KeyringClient, KeyringHttpError, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NOT_MEMBER_CLOSE_CODE, NOT_MEMBER_RECHECK_MS, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PINNED_CIRCUIT_DIGESTS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PaymentRequiredError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, ROOT_ID, Ready, ReauthRequiredError, ReedSolomonCodec, Repo, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, SpaceTrustError, StorageNamespace, SyncEngine, VERSION, VFS_ROOT_INFO, VaultProtocolMismatchError, VaultUnavailableError, VcsError, VcsNamespace, VfsConflictError, VfsCorruptRecordError, VfsLimitError, VfsLockedError, VfsNamespace, VfsNotFoundError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes$1 as concatBytes, configureDeviceStore, createPasskeyWithPrf, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultRpId, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, dirKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, evaluatePasskeyPrf, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$2 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, headKey, historyKey, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, isSameOriginPath, loadDeviceIdentity, log, manifestToStat, materializeRow, merge3, merge3Text, mergeKey, mergeMap, mergeMessage, mergeRegister, messageKey, objectKey, pack, padHandle, pairingVerificationCode, passkeyPrfCapable, passkeySupported, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, refKey, refsIndexKey, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$2 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map