cursedbelt-server 4.37.0 → 4.38.0

package/dist/server/ctgrChunkDurable.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The ctgr chunk store on a Cloudflare Worker: ONE Durable Object per multi-chunk payload, so
+ * every chunk of it meets every other chunk no matter which isolate answered it.
+ *
+ * ── Why this exists (2026-09-26, desk task 2185) ─────────────────────────────
+ * A GET-only device splits any body over 1800 bytes into several `/ctgr<xx>` GETs, and
+ * {@link mountCtgrTunnel} reassembles them in a {@link ChunkStore} — memory. On a Worker, memory
+ * is one isolate: chunk 2 answered by another isolate (another colo, a recycled isolate, load
+ * spread across several) finds no chunk 1, answers 202, and the payload is silently never
+ * delivered. desk's large saves were exposed; auth's login body is one chunk.
+ *
+ * ── The object is a rendezvous, not a decoder ────────────────────────────────
+ * It keeps each chunk's raw query params by index and, when the last one arrives, hands the
+ * whole ordered set back. The Worker then runs them through a fresh {@link ChunkStore} — the
+ * SAME crc/sha/size/decode path a Mac process uses — so nothing about verification is
+ * re-implemented here, and the object never parses a body. A single-chunk twin (the norm)
+ * never reaches the object at all.
+ *
+ * ── One object per payload ───────────────────────────────────────────────────
+ * Addressed by `ctgr:<_cid>` (a `crypto.randomUUID()` the client mints per request), so the
+ * chunks of one request are serialised through one object and different requests never
+ * contend. The partial lives in the object's memory: chunks arrive milliseconds apart, the idle
+ * TTL is 30 s, and an object is only evicted after minutes idle — a partial it loses is one a
+ * deploy would have lost too. An object holding nothing costs nothing.
+ *
+ * ── Types are structural ────────────────────────────────────────────────────
+ * No `@cloudflare/workers-types`, and the classic `fetch` interface — the same reasons as
+ * `loginThrottleDurable.ts`.
+ */
+import { type ChunkStoreOpts } from 'cursedbelt-core/ctgr/chunk-store';
+import type { CtgrChunkSink } from './ctgrTunnel.js';
+/** The members of a `DurableObjectNamespace` binding the store calls. */
+export interface CtgrChunkNamespaceLike {
+    idFromName(name: string): unknown;
+    get(id: unknown): {
+        fetch(request: Request): Promise<Response>;
+    };
+}
+/**
+ * The Durable Object. Re-export it from the Worker's entry under the `class_name` your
+ * `wrangler.jsonc` binds, and add it in a migration (`new_sqlite_classes`):
+ *
+ *     export { CtgrChunkObject as DeskCtgrChunks } from "cursedbelt-server/ctgr-tunnel/durable";
+ */
+export declare class CtgrChunkObject {
+    private partial;
+    private readonly maxPayloadBytes;
+    private readonly ttlMs;
+    private readonly now;
+    /** `options` is for tests; the runtime passes `(state, env)` only. */
+    constructor(_state?: unknown, _env?: unknown, options?: ChunkStoreOpts);
+    fetch(request: Request): Promise<Response>;
+    private add;
+}
+/**
+ * The Worker half: a {@link CtgrChunkSink} for {@link mountCtgrTunnel} whose multi-chunk
+ * partials live in the object. Cheap to build — build it per request over `env.<BINDING>`.
+ *
+ * An object that cannot be reached THROWS, and the tunnel answers 503: a payload half-held in
+ * one isolate's memory is exactly the silent loss this exists to end, so there is no fallback.
+ */
+export declare function createDurableChunkStore(namespace: CtgrChunkNamespaceLike, options?: ChunkStoreOpts): CtgrChunkSink;

package/dist/server/ctgrChunkDurable.js

@@ -0,0 +1,155 @@
+/**
+ * The ctgr chunk store on a Cloudflare Worker: ONE Durable Object per multi-chunk payload, so
+ * every chunk of it meets every other chunk no matter which isolate answered it.
+ *
+ * ── Why this exists (2026-09-26, desk task 2185) ─────────────────────────────
+ * A GET-only device splits any body over 1800 bytes into several `/ctgr<xx>` GETs, and
+ * {@link mountCtgrTunnel} reassembles them in a {@link ChunkStore} — memory. On a Worker, memory
+ * is one isolate: chunk 2 answered by another isolate (another colo, a recycled isolate, load
+ * spread across several) finds no chunk 1, answers 202, and the payload is silently never
+ * delivered. desk's large saves were exposed; auth's login body is one chunk.
+ *
+ * ── The object is a rendezvous, not a decoder ────────────────────────────────
+ * It keeps each chunk's raw query params by index and, when the last one arrives, hands the
+ * whole ordered set back. The Worker then runs them through a fresh {@link ChunkStore} — the
+ * SAME crc/sha/size/decode path a Mac process uses — so nothing about verification is
+ * re-implemented here, and the object never parses a body. A single-chunk twin (the norm)
+ * never reaches the object at all.
+ *
+ * ── One object per payload ───────────────────────────────────────────────────
+ * Addressed by `ctgr:<_cid>` (a `crypto.randomUUID()` the client mints per request), so the
+ * chunks of one request are serialised through one object and different requests never
+ * contend. The partial lives in the object's memory: chunks arrive milliseconds apart, the idle
+ * TTL is 30 s, and an object is only evicted after minutes idle — a partial it loses is one a
+ * deploy would have lost too. An object holding nothing costs nothing.
+ *
+ * ── Types are structural ────────────────────────────────────────────────────
+ * No `@cloudflare/workers-types`, and the classic `fetch` interface — the same reasons as
+ * `loginThrottleDurable.ts`.
+ */
+import { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import { parseChunk } from 'cursedbelt-core/ctgr';
+const DEFAULT_MAX_PAYLOAD_BYTES = 10 * 1024 * 1024;
+const DEFAULT_TTL_MS = 30_000;
+const json = (value, status = 200) => new Response(JSON.stringify(value), { status, headers: { 'content-type': 'application/json' } });
+/**
+ * The Durable Object. Re-export it from the Worker's entry under the `class_name` your
+ * `wrangler.jsonc` binds, and add it in a migration (`new_sqlite_classes`):
+ *
+ *     export { CtgrChunkObject as DeskCtgrChunks } from "cursedbelt-server/ctgr-tunnel/durable";
+ */
+export class CtgrChunkObject {
+    partial = null;
+    maxPayloadBytes;
+    ttlMs;
+    now;
+    /** `options` is for tests; the runtime passes `(state, env)` only. */
+    constructor(_state, _env, options = {}) {
+        this.maxPayloadBytes = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.now = options.now ?? Date.now;
+    }
+    async fetch(request) {
+        const path = new URL(request.url).pathname;
+        if (request.method !== 'POST' || path !== '/ctgr/chunk') {
+            return json({ error: `${request.method} ${path}: only POST /ctgr/chunk` }, 404);
+        }
+        let params;
+        let chunk;
+        try {
+            params = (await request.json());
+            chunk = parseChunk(params);
+        }
+        catch (error) {
+            return json({ error: error instanceof Error ? error.message : String(error) }, 400);
+        }
+        return json(this.add(params, chunk));
+    }
+    add(params, chunk) {
+        if (this.partial && this.partial.updatedAt < this.now() - this.ttlMs)
+            this.partial = null;
+        if (chunk.payloadLength > this.maxPayloadBytes)
+            return { error: 'ctgr: payload exceeds size cap' };
+        let entry = this.partial;
+        if (!entry) {
+            entry = {
+                cid: chunk.cid,
+                total: chunk.total,
+                payloadLength: chunk.payloadLength,
+                gzip: chunk.gzip,
+                method: chunk.method,
+                parts: new Array(chunk.total),
+                received: 0,
+                bytes: 0,
+                updatedAt: this.now(),
+            };
+            this.partial = entry;
+        }
+        else if (entry.cid !== chunk.cid ||
+            entry.total !== chunk.total ||
+            entry.payloadLength !== chunk.payloadLength ||
+            entry.gzip !== chunk.gzip ||
+            entry.method !== chunk.method) {
+            // A payload's framing must not change mid-stream — the same rule `ChunkStore` keeps.
+            this.partial = null;
+            return { error: 'ctgr: inconsistent chunk metadata' };
+        }
+        entry.updatedAt = this.now();
+        if (entry.parts[chunk.index] === undefined) {
+            entry.parts[chunk.index] = params;
+            entry.received += 1;
+            entry.bytes += chunk.bytes.length;
+            if (entry.bytes > this.maxPayloadBytes) {
+                this.partial = null;
+                return { error: 'ctgr: payload exceeds size cap' };
+            }
+        }
+        if (entry.received < entry.total)
+            return { pending: true };
+        this.partial = null;
+        return { chunks: entry.parts };
+    }
+}
+/**
+ * The Worker half: a {@link CtgrChunkSink} for {@link mountCtgrTunnel} whose multi-chunk
+ * partials live in the object. Cheap to build — build it per request over `env.<BINDING>`.
+ *
+ * An object that cannot be reached THROWS, and the tunnel answers 503: a payload half-held in
+ * one isolate's memory is exactly the silent loss this exists to end, so there is no fallback.
+ */
+export function createDurableChunkStore(namespace, options = {}) {
+    return {
+        async add(input) {
+            const params = input instanceof URLSearchParams ? Object.fromEntries(input) : { ...input };
+            let chunk;
+            try {
+                chunk = parseChunk(params);
+            }
+            catch (error) {
+                return error instanceof Error ? error : new Error(String(error));
+            }
+            // One chunk needs no rendezvous — decode it here, in this isolate.
+            if (chunk.total === 1)
+                return new ChunkStore(options).add(params);
+            const stub = namespace.get(namespace.idFromName(`ctgr:${chunk.cid}`));
+            const response = await stub.fetch(new Request('https://ctgr-chunks.invalid/ctgr/chunk', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(params),
+            }));
+            const reply = (await response.json().catch(() => null));
+            if (!reply)
+                throw new Error(`ctgr chunk object answered ${response.status} with no JSON`);
+            if ('error' in reply)
+                return new Error(reply.error);
+            if ('pending' in reply)
+                return false;
+            // Every chunk is here: the one verify/decode path, in a store that lives for this call.
+            const assemble = new ChunkStore(options);
+            let result = new Error('ctgr: empty chunk set');
+            for (const part of reply.chunks)
+                result = await assemble.add(part);
+            return result;
+        },
+    };
+}

package/dist/server/ctgrTunnel.d.ts

@@ -1,15 +1,27 @@
-import { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import { type CtgrDecoded } from 'cursedbelt-core/ctgr/types';
 import type { Env, Hono } from 'hono';
+/**
+ * What the tunnel needs of an accumulator: a {@link ChunkStore}, or the Worker's
+ * `createDurableChunkStore` (`cursedbelt-server/ctgr-tunnel/durable`), whose partials every
+ * isolate shares. `false` is an intermediate chunk (→ 202), an `Error` a bad payload (→ 400);
+ * a THROW means the store itself could not answer (→ 503).
+ */
+export interface CtgrChunkSink {
+    add(params: Record<string, string> | URLSearchParams): Promise<CtgrDecoded | false | Error>;
+}
 export interface CtgrTunnelOptions {
     /**
      * The accumulator for multi-chunk payloads. Share ONE across an app (the default is
      * a fresh singleton); pass your own to tune the DoS caps ({@link ChunkStore}).
+     * 🔴 On a Cloudflare Worker a module-scope `ChunkStore` is one ISOLATE's memory — pass
+     * `createDurableChunkStore(env.<BINDING>)` there, or a multi-chunk payload whose chunks
+     * land on different isolates is silently never delivered.
      */
-    store?: ChunkStore;
+    store?: CtgrChunkSink;
 }
 /**
  * Mount the GET-only tunnel on `app`. Call once, on the Hono app whose real routes sit
  * at the paths the twins mirror (a twin path is `/ctgr<xx>` + the real path). Returns
- * the {@link ChunkStore} in use, for tests and metrics.
+ * the store in use, for tests and metrics.
  */
-export declare function mountCtgrTunnel<E extends Env = Env>(app: Hono<E>, options?: CtgrTunnelOptions): ChunkStore;
+export declare function mountCtgrTunnel<E extends Env = Env>(app: Hono<E>, options?: CtgrTunnelOptions): CtgrChunkSink;

package/dist/server/ctgrTunnel.js

@@ -23,7 +23,7 @@ const isCtgrParam = (key) => key === '_d' || key === '_sha' || key.startsWith('_
 /**
  * Mount the GET-only tunnel on `app`. Call once, on the Hono app whose real routes sit
  * at the paths the twins mirror (a twin path is `/ctgr<xx>` + the real path). Returns
- * the {@link ChunkStore} in use, for tests and metrics.
+ * the store in use, for tests and metrics.
  */
 export function mountCtgrTunnel(app, options = {}) {
     const store = options.store ?? new ChunkStore();
@@ -36,7 +36,14 @@ export function mountCtgrTunnel(app, options = {}) {
         if (!pathMethod) {
             return c.json({ error: 'not found', code: 'NOT_FOUND' }, 404);
         }
-        const result = params._cv === undefined ? legacy.add(params, pathMethod) : await store.add(params);
+        let result;
+        try {
+            result = params._cv === undefined ? legacy.add(params, pathMethod) : await store.add(params);
+        }
+        catch (error) {
+            console.error(`[ctgr] the chunk store could not answer: ${error instanceof Error ? error.message : String(error)}`);
+            return c.json({ error: 'ctgr: the chunk store could not answer — send it again', code: 'CTGR_STORE_UNAVAILABLE' }, 503);
+        }
         if (result === false)
             return c.json({ acknowledged: true }, 202);
         if (result instanceof Error) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.37.0",
+	"version": "4.38.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -65,6 +65,12 @@
 			"source": "./src/server/ctgrTunnel.ts",
 			"import": "./dist/server/ctgrTunnel.js"
 		},
+		"./ctgr-tunnel/durable": {
+			"types": "./dist/server/ctgrChunkDurable.d.ts",
+			"bun": "./src/server/ctgrChunkDurable.ts",
+			"source": "./src/server/ctgrChunkDurable.ts",
+			"import": "./dist/server/ctgrChunkDurable.js"
+		},
 		"./analytics": {
 			"types": "./dist/server/analytics/index.d.ts",
 			"bun": "./src/server/analytics/index.ts",

package/src/server/ctgrChunkDurable.spec.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from 'bun:test';
+import { encodeRequest } from 'cursedbelt-core/ctgr';
+import { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import { Hono } from 'hono';
+import { type CtgrChunkNamespaceLike, CtgrChunkObject, createDurableChunkStore } from './ctgrChunkDurable.js';
+import { mountCtgrTunnel } from './ctgrTunnel.js';
+
+/** A namespace like the runtime's: one object per name, however many isolates ask. */
+function fakeNamespace(clock?: () => number) {
+  const objects = new Map<string, CtgrChunkObject>();
+  const calls: string[] = [];
+  const namespace: CtgrChunkNamespaceLike = {
+    idFromName: (name) => name,
+    get: (id) => ({
+      fetch: async (request: Request) => {
+        const name = id as string;
+        calls.push(name);
+        let object = objects.get(name);
+        if (!object) {
+          object = new CtgrChunkObject(undefined, undefined, clock ? { now: clock } : {});
+          objects.set(name, object);
+        }
+        return object.fetch(request);
+      },
+    }),
+  };
+  return { namespace, objects, calls };
+}
+
+const bigBody = { note: 'x'.repeat(9000), n: 7 };
+
+async function multiChunk() {
+  // Incompressible enough to stay multi-chunk after gzip.
+  const random = Array.from({ length: 6000 }, (_, i) => ((i * 2654435761) >>> 0).toString(36)).join('');
+  const { chunks } = await encodeRequest('POST', '/api/v1/notes', { ...bigBody, random });
+  expect(chunks.length).toBeGreaterThan(2);
+  return { chunks, body: { ...bigBody, random } };
+}
+
+describe('createDurableChunkStore — two isolates, one object', () => {
+  test('chunks alternating between two isolates reassemble, in any order', async () => {
+    const { namespace } = fakeNamespace();
+    const isolates = [createDurableChunkStore(namespace), createDurableChunkStore(namespace)];
+    const { chunks, body } = await multiChunk();
+    const order = chunks.map((_, i) => i).reverse();
+    const results = [];
+    for (const [n, i] of order.entries()) results.push(await isolates[n % 2].add(chunks[i].params));
+    for (const intermediate of results.slice(0, -1)) expect(intermediate).toBe(false);
+    const last = results.at(-1);
+    expect(last).not.toBeInstanceOf(Error);
+    expect(last && !(last instanceof Error) ? last.body : null).toEqual(body);
+  });
+
+  test('🔴 the failure it replaces: two per-isolate ChunkStores never finish the payload', async () => {
+    const isolates = [new ChunkStore(), new ChunkStore()];
+    const { chunks } = await multiChunk();
+    const results = [];
+    for (const [n, chunk] of chunks.entries()) results.push(await isolates[n % 2].add(chunk.params));
+    expect(results.every((r) => r === false)).toBe(true);
+  });
+
+  test('a single-chunk twin never reaches an object', async () => {
+    const { namespace, calls } = fakeNamespace();
+    const { chunks } = await encodeRequest('POST', '/api/v1/notes', { small: true });
+    expect(chunks).toHaveLength(1);
+    const result = await createDurableChunkStore(namespace).add(chunks[0].params);
+    expect(result && !(result instanceof Error) ? result.body : null).toEqual({ small: true });
+    expect(calls).toHaveLength(0);
+  });
+
+  test('each payload has its own object, and a finished one holds nothing', async () => {
+    const { namespace, calls } = fakeNamespace();
+    const store = createDurableChunkStore(namespace);
+    const a = await multiChunk();
+    for (const chunk of a.chunks) await store.add(chunk.params);
+    expect(new Set(calls)).toEqual(new Set([`ctgr:${a.chunks[0].params._cid}`]));
+    // Replaying the first chunk starts a fresh partial rather than re-finishing the old one.
+    expect(await store.add(a.chunks[0].params)).toBe(false);
+  });
+
+  test('a corrupted chunk is a 4xx Error in the isolate, before any object is asked', async () => {
+    const { namespace, calls } = fakeNamespace();
+    const { chunks } = await multiChunk();
+    const bad = { ...chunks[1].params, _d: `${chunks[1].params._d.slice(0, -4)}AAAA` };
+    expect(await createDurableChunkStore(namespace).add(bad)).toBeInstanceOf(Error);
+    expect(calls).toHaveLength(0);
+  });
+
+  test('framing that changes mid-payload is refused, as ChunkStore refuses it', async () => {
+    const { namespace } = fakeNamespace();
+    const store = createDurableChunkStore(namespace);
+    const { chunks } = await multiChunk();
+    const other = await encodeRequest('PATCH', '/api/v1/notes/1', (await multiChunk()).body);
+    expect(await store.add(chunks[0].params)).toBe(false);
+    const forged = { ...other.chunks[1].params, _cid: chunks[0].params._cid };
+    expect(await store.add(forged)).toBeInstanceOf(Error);
+  });
+
+  test('a partial idle past the TTL is dropped, so a late chunk cannot complete it', async () => {
+    let now = 0;
+    const { namespace } = fakeNamespace(() => now);
+    const store = createDurableChunkStore(namespace);
+    const { chunks } = await multiChunk();
+    for (const chunk of chunks.slice(0, -1)) expect(await store.add(chunk.params)).toBe(false);
+    now = 31_000;
+    expect(await store.add(chunks.at(-1)!.params)).toBe(false);
+  });
+
+  test('an object that cannot answer is a THROW — the tunnel turns it into a 503', async () => {
+    const down: CtgrChunkNamespaceLike = {
+      idFromName: (name) => name,
+      get: () => ({ fetch: async () => new Response('Internal error', { status: 500 }) }),
+    };
+    const app = new Hono();
+    mountCtgrTunnel(app, { store: createDurableChunkStore(down) });
+    app.post('/api/v1/notes', (c) => c.json({ reached: true }));
+    const { chunks } = await multiChunk();
+    const res = await app.fetch(new Request(`http://localhost${chunks[0].url}`));
+    expect(res.status).toBe(503);
+    expect(((await res.json()) as { code: string }).code).toBe('CTGR_STORE_UNAVAILABLE');
+  });
+
+  test('the whole tunnel over two isolates: every handler reached once, with the body', async () => {
+    const { namespace } = fakeNamespace();
+    const reached: unknown[] = [];
+    const isolate = () => {
+      const app = new Hono();
+      mountCtgrTunnel(app, { store: createDurableChunkStore(namespace) });
+      app.post('/api/v1/notes', async (c) => {
+        reached.push(await c.req.json());
+        return c.json({ ok: true }, 201);
+      });
+      return app;
+    };
+    const apps = [isolate(), isolate()];
+    const { chunks, body } = await multiChunk();
+    const statuses: number[] = [];
+    for (const [n, chunk] of chunks.entries()) {
+      statuses.push((await apps[n % 2].fetch(new Request(`http://localhost${chunk.url}`))).status);
+    }
+    expect(statuses).toEqual([...chunks.slice(1).map(() => 202), 201]);
+    expect(reached).toEqual([body]);
+  });
+});

package/src/server/ctgrChunkDurable.ts

@@ -0,0 +1,188 @@
+/**
+ * The ctgr chunk store on a Cloudflare Worker: ONE Durable Object per multi-chunk payload, so
+ * every chunk of it meets every other chunk no matter which isolate answered it.
+ *
+ * ── Why this exists (2026-09-26, desk task 2185) ─────────────────────────────
+ * A GET-only device splits any body over 1800 bytes into several `/ctgr<xx>` GETs, and
+ * {@link mountCtgrTunnel} reassembles them in a {@link ChunkStore} — memory. On a Worker, memory
+ * is one isolate: chunk 2 answered by another isolate (another colo, a recycled isolate, load
+ * spread across several) finds no chunk 1, answers 202, and the payload is silently never
+ * delivered. desk's large saves were exposed; auth's login body is one chunk.
+ *
+ * ── The object is a rendezvous, not a decoder ────────────────────────────────
+ * It keeps each chunk's raw query params by index and, when the last one arrives, hands the
+ * whole ordered set back. The Worker then runs them through a fresh {@link ChunkStore} — the
+ * SAME crc/sha/size/decode path a Mac process uses — so nothing about verification is
+ * re-implemented here, and the object never parses a body. A single-chunk twin (the norm)
+ * never reaches the object at all.
+ *
+ * ── One object per payload ───────────────────────────────────────────────────
+ * Addressed by `ctgr:<_cid>` (a `crypto.randomUUID()` the client mints per request), so the
+ * chunks of one request are serialised through one object and different requests never
+ * contend. The partial lives in the object's memory: chunks arrive milliseconds apart, the idle
+ * TTL is 30 s, and an object is only evicted after minutes idle — a partial it loses is one a
+ * deploy would have lost too. An object holding nothing costs nothing.
+ *
+ * ── Types are structural ────────────────────────────────────────────────────
+ * No `@cloudflare/workers-types`, and the classic `fetch` interface — the same reasons as
+ * `loginThrottleDurable.ts`.
+ */
+import { ChunkStore, type ChunkStoreOpts } from 'cursedbelt-core/ctgr/chunk-store';
+import { parseChunk, type ParsedChunk } from 'cursedbelt-core/ctgr';
+import type { CtgrDecoded } from 'cursedbelt-core/ctgr/types';
+import type { CtgrChunkSink } from './ctgrTunnel.js';
+
+/** The members of a `DurableObjectNamespace` binding the store calls. */
+export interface CtgrChunkNamespaceLike {
+  idFromName(name: string): unknown;
+  get(id: unknown): { fetch(request: Request): Promise<Response> };
+}
+
+/** What the object answers `POST /ctgr/chunk` with. */
+type ChunkReply = { pending: true } | { chunks: Record<string, string>[] } | { error: string };
+
+const DEFAULT_MAX_PAYLOAD_BYTES = 10 * 1024 * 1024;
+const DEFAULT_TTL_MS = 30_000;
+
+const json = (value: ChunkReply, status = 200): Response =>
+  new Response(JSON.stringify(value), { status, headers: { 'content-type': 'application/json' } });
+
+interface Partial {
+  cid: string;
+  total: number;
+  payloadLength: number;
+  gzip: boolean;
+  method: string;
+  parts: (Record<string, string> | undefined)[];
+  received: number;
+  bytes: number;
+  updatedAt: number;
+}
+
+/**
+ * The Durable Object. Re-export it from the Worker's entry under the `class_name` your
+ * `wrangler.jsonc` binds, and add it in a migration (`new_sqlite_classes`):
+ *
+ *     export { CtgrChunkObject as DeskCtgrChunks } from "cursedbelt-server/ctgr-tunnel/durable";
+ */
+export class CtgrChunkObject {
+  private partial: Partial | null = null;
+  private readonly maxPayloadBytes: number;
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  /** `options` is for tests; the runtime passes `(state, env)` only. */
+  constructor(_state?: unknown, _env?: unknown, options: ChunkStoreOpts = {}) {
+    this.maxPayloadBytes = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.now = options.now ?? Date.now;
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const path = new URL(request.url).pathname;
+    if (request.method !== 'POST' || path !== '/ctgr/chunk') {
+      return json({ error: `${request.method} ${path}: only POST /ctgr/chunk` }, 404);
+    }
+    let params: Record<string, string>;
+    let chunk: ParsedChunk;
+    try {
+      params = (await request.json()) as Record<string, string>;
+      chunk = parseChunk(params);
+    } catch (error) {
+      return json({ error: error instanceof Error ? error.message : String(error) }, 400);
+    }
+    return json(this.add(params, chunk));
+  }
+
+  private add(params: Record<string, string>, chunk: ParsedChunk): ChunkReply {
+    if (this.partial && this.partial.updatedAt < this.now() - this.ttlMs) this.partial = null;
+    if (chunk.payloadLength > this.maxPayloadBytes) return { error: 'ctgr: payload exceeds size cap' };
+
+    let entry = this.partial;
+    if (!entry) {
+      entry = {
+        cid: chunk.cid,
+        total: chunk.total,
+        payloadLength: chunk.payloadLength,
+        gzip: chunk.gzip,
+        method: chunk.method,
+        parts: new Array(chunk.total),
+        received: 0,
+        bytes: 0,
+        updatedAt: this.now(),
+      };
+      this.partial = entry;
+    } else if (
+      entry.cid !== chunk.cid ||
+      entry.total !== chunk.total ||
+      entry.payloadLength !== chunk.payloadLength ||
+      entry.gzip !== chunk.gzip ||
+      entry.method !== chunk.method
+    ) {
+      // A payload's framing must not change mid-stream — the same rule `ChunkStore` keeps.
+      this.partial = null;
+      return { error: 'ctgr: inconsistent chunk metadata' };
+    }
+
+    entry.updatedAt = this.now();
+    if (entry.parts[chunk.index] === undefined) {
+      entry.parts[chunk.index] = params;
+      entry.received += 1;
+      entry.bytes += chunk.bytes.length;
+      if (entry.bytes > this.maxPayloadBytes) {
+        this.partial = null;
+        return { error: 'ctgr: payload exceeds size cap' };
+      }
+    }
+    if (entry.received < entry.total) return { pending: true };
+
+    this.partial = null;
+    return { chunks: entry.parts as Record<string, string>[] };
+  }
+}
+
+/**
+ * The Worker half: a {@link CtgrChunkSink} for {@link mountCtgrTunnel} whose multi-chunk
+ * partials live in the object. Cheap to build — build it per request over `env.<BINDING>`.
+ *
+ * An object that cannot be reached THROWS, and the tunnel answers 503: a payload half-held in
+ * one isolate's memory is exactly the silent loss this exists to end, so there is no fallback.
+ */
+export function createDurableChunkStore(
+  namespace: CtgrChunkNamespaceLike,
+  options: ChunkStoreOpts = {},
+): CtgrChunkSink {
+  return {
+    async add(input) {
+      const params =
+        input instanceof URLSearchParams ? Object.fromEntries(input) : { ...input };
+      let chunk: ParsedChunk;
+      try {
+        chunk = parseChunk(params);
+      } catch (error) {
+        return error instanceof Error ? error : new Error(String(error));
+      }
+      // One chunk needs no rendezvous — decode it here, in this isolate.
+      if (chunk.total === 1) return new ChunkStore(options).add(params);
+
+      const stub = namespace.get(namespace.idFromName(`ctgr:${chunk.cid}`));
+      const response = await stub.fetch(
+        new Request('https://ctgr-chunks.invalid/ctgr/chunk', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(params),
+        }),
+      );
+      const reply = (await response.json().catch(() => null)) as ChunkReply | null;
+      if (!reply) throw new Error(`ctgr chunk object answered ${response.status} with no JSON`);
+      if ('error' in reply) return new Error(reply.error);
+      if ('pending' in reply) return false;
+
+      // Every chunk is here: the one verify/decode path, in a store that lives for this call.
+      const assemble = new ChunkStore(options);
+      let result: CtgrDecoded | false | Error = new Error('ctgr: empty chunk set');
+      for (const part of reply.chunks) result = await assemble.add(part);
+      return result;
+    },
+  };
+}

package/src/server/ctgrTunnel.ts

@@ -28,23 +28,36 @@ import { CTGR_ROUTE_PATTERN } from './ctgr.js';
 const isCtgrParam = (key: string): boolean =>
   key === '_d' || key === '_sha' || key.startsWith('_c');
 
+/**
+ * What the tunnel needs of an accumulator: a {@link ChunkStore}, or the Worker's
+ * `createDurableChunkStore` (`cursedbelt-server/ctgr-tunnel/durable`), whose partials every
+ * isolate shares. `false` is an intermediate chunk (→ 202), an `Error` a bad payload (→ 400);
+ * a THROW means the store itself could not answer (→ 503).
+ */
+export interface CtgrChunkSink {
+  add(params: Record<string, string> | URLSearchParams): Promise<CtgrDecoded | false | Error>;
+}
+
 export interface CtgrTunnelOptions {
   /**
    * The accumulator for multi-chunk payloads. Share ONE across an app (the default is
    * a fresh singleton); pass your own to tune the DoS caps ({@link ChunkStore}).
+   * 🔴 On a Cloudflare Worker a module-scope `ChunkStore` is one ISOLATE's memory — pass
+   * `createDurableChunkStore(env.<BINDING>)` there, or a multi-chunk payload whose chunks
+   * land on different isolates is silently never delivered.
    */
-  store?: ChunkStore;
+  store?: CtgrChunkSink;
 }
 
 /**
  * Mount the GET-only tunnel on `app`. Call once, on the Hono app whose real routes sit
  * at the paths the twins mirror (a twin path is `/ctgr<xx>` + the real path). Returns
- * the {@link ChunkStore} in use, for tests and metrics.
+ * the store in use, for tests and metrics.
  */
 export function mountCtgrTunnel<E extends Env = Env>(
   app: Hono<E>,
   options: CtgrTunnelOptions = {},
-): ChunkStore {
+): CtgrChunkSink {
   const store = options.store ?? new ChunkStore();
   const legacy = new V0ChunkStore();
 
@@ -57,8 +70,13 @@ export function mountCtgrTunnel<E extends Env = Env>(
       return c.json({ error: 'not found', code: 'NOT_FOUND' }, 404);
     }
 
-    const result =
-      params._cv === undefined ? legacy.add(params, pathMethod) : await store.add(params);
+    let result: CtgrDecoded | false | Error;
+    try {
+      result = params._cv === undefined ? legacy.add(params, pathMethod) : await store.add(params);
+    } catch (error) {
+      console.error(`[ctgr] the chunk store could not answer: ${error instanceof Error ? error.message : String(error)}`);
+      return c.json({ error: 'ctgr: the chunk store could not answer — send it again', code: 'CTGR_STORE_UNAVAILABLE' }, 503);
+    }
 
     if (result === false) return c.json({ acknowledged: true }, 202);
     if (result instanceof Error) {