cursedbelt-server 4.33.0 → 4.34.0

package/dist/server/d1/fakeD1.js

@@ -83,7 +83,8 @@ class FakeD1Statement {
         this.params = params;
     }
     bind(...values) {
-        values.forEach((v, i) => assertD1Bindable(v, i));
+        for (const [i, v] of values.entries())
+            assertD1Bindable(v, i);
         // A real binding stores what it was given; the ArrayBuffer→Uint8Array conversion
         // here is `bun:sqlite`'s requirement, not D1's, and happens below the emulated edge.
         const stored = values.map((v) => (v instanceof ArrayBuffer ? new Uint8Array(v) : v));

package/dist/server/d1/pullD1.d.ts

@@ -129,6 +129,11 @@ export interface PullD1Options {
     /** Run after the rows are loaded — where an app REBUILDS its search index (never copied). */
     afterLoadSql?: string;
     wrangler: Wrangler;
+    /**
+     * Where a page D1 refused is reported (default: stderr). Before 4.33.1 a halving was silent,
+     * so the only symptom of a slow spell was a backup that took hours.
+     */
+    log?: (line: string) => void;
 }
 /** How a table is walked in pages: by a rowid keyset, or — a `WITHOUT ROWID` table — by offset. */
 export interface TablePlan {

package/dist/server/d1/pullD1.js

@@ -202,8 +202,15 @@ export function pageSql(plan, limit, after) {
     const order = plan.order.map(sqlIdent).join(', ');
     return `SELECT ${values} FROM ${sqlIdent(plan.table)} ORDER BY ${order} LIMIT ${limit} OFFSET ${after.offset ?? 0}`;
 }
-/** Every row of one table as `INSERT INTO …;` lines, read in pages that never block D1. */
-function dumpTable(wrangler, database, plan) {
+/**
+ * Every row of one table as `INSERT INTO …;` lines, read in pages that never block D1.
+ *
+ * A page D1 refuses is asked again at half the size, and 🔴 every page that SUCCEEDS doubles the
+ * size back toward {@link PAGE_ROWS}. Before 4.33.1 nothing grew it back: desk's first launchd
+ * backup (2026-09-25) hit a few slow calls early and read its 3,381-row table 15 rows per call —
+ * 225 two-minute calls, on course for hours. Only a refusal at ONE row is fatal.
+ */
+function dumpTable(wrangler, database, plan, log) {
     const into = `INSERT INTO ${sqlIdent(plan.table)} (${plan.columns.map(sqlIdent).join(', ')}) VALUES (`;
     const lines = [];
     let limit = PAGE_ROWS;
@@ -214,11 +221,14 @@ function dumpTable(wrangler, database, plan) {
             page = execute(wrangler, database, pageSql(plan, limit, after))[0] ?? [];
         }
         catch (error) {
+            const message = error.message;
             if (limit > 1) {
-                limit = Math.max(1, Math.floor(limit / 2));
+                const next = Math.max(1, Math.floor(limit / 2));
+                log(`pull D1: \`${plan.table}\` refused a page of ${limit} — asking for ${next}: ${message}`);
+                limit = next;
                 continue;
             }
-            throw new Error(`could not read \`${plan.table}\` from D1: ${error.message}`);
+            throw new Error(`could not read \`${plan.table}\` from D1: ${message}`);
         }
         for (const row of page) {
             const literals = plan.columns.map((_, i) => row[`c${i}`]);
@@ -230,6 +240,7 @@ function dumpTable(wrangler, database, plan) {
         if (page.length < limit)
             break;
         after = plan.key ? { key: Number(page[page.length - 1]?.k) } : { offset: (after.offset ?? 0) + page.length };
+        limit = Math.min(PAGE_ROWS, limit * 2);
     }
     return { text: lines.join('\n'), rows: lines.length };
 }
@@ -243,6 +254,7 @@ function dumpTable(wrangler, database, plan) {
  */
 export async function pullD1ToSqlite(options) {
     const { destination, database, wrangler } = options;
+    const log = options.log ?? ((line) => console.error(line));
     let rows;
     try {
         rows = (execute(wrangler, database, "select name, sql from sqlite_master where type = 'table'")[0] ?? []);
@@ -265,7 +277,7 @@ export async function pullD1ToSqlite(options) {
     const dumps = tables.map((table, i) => {
         const cols = (columnSets[i] ?? []);
         const plan = tablePlan(table, rows.find((r) => r.name === table)?.sql ?? null, cols);
-        return { table, ...dumpTable(wrangler, database, plan) };
+        return { table, ...dumpTable(wrangler, database, plan, log) };
     });
     if (dumps.every((d) => d.rows === 0)) {
         throw new Error('the D1 pull contains no rows — refusing to snapshot an empty database as if it were the library');

package/dist/server/storage/binaryStore.d.ts

@@ -405,6 +405,29 @@ export declare function binaryStoreTenant(appId: string, env?: Record<string, st
  * apps and that is precisely why the difference goes unnoticed when it is not.
  */
 export declare function resolvedMediaTenant(appId: string, env?: Record<string, string | undefined>): string | null;
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export declare function storeUnreachableStatus(status: number): boolean;
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export declare class BinaryStoreUnreachableError extends Error {
+    readonly status = 503;
+    readonly code = "BYTE_STORE_UNREACHABLE";
+    constructor(op: string, key: string, detail: string);
+    getResponse(): Response;
+}
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):

package/dist/server/storage/binaryStore.js

@@ -430,7 +430,11 @@ export function createBinaryStore(cfg) {
                 method: 'PUT',
                 headers: mime ? { 'content-type': mime } : undefined,
                 body: bytes,
+            }).catch((cause) => {
+                throw new BinaryStoreUnreachableError('put', key, cause instanceof Error ? cause.message : String(cause));
             });
+            if (storeUnreachableStatus(res.status))
+                throw new BinaryStoreUnreachableError('put', key, String(res.status));
             if (!res.ok) {
                 // A 413 that reaches here despite the threshold above means the edge's
                 // real cap is lower than we think, or the caller disabled the
@@ -499,7 +503,12 @@ export function createBinaryStore(cfg) {
                     method: 'PUT',
                     headers: mime ? { 'content-type': mime } : undefined,
                     body: slice,
+                }).catch((cause) => {
+                    throw new BinaryStoreUnreachableError('putLarge', key, cause instanceof Error ? cause.message : String(cause));
                 });
+                if (storeUnreachableStatus(res.status)) {
+                    throw new BinaryStoreUnreachableError('putLarge', key, `chunk ${ci + 1}/${total}: ${res.status}`);
+                }
                 if (!res.ok) {
                     throw new Error(`[binary-store] putLarge ${key} chunk ${ci + 1}/${total}: ${res.status}`);
                 }
@@ -752,6 +761,40 @@ export function binaryStoreTenant(appId, env = process.env) {
 export function resolvedMediaTenant(appId, env = process.env) {
     return readBinaryStoreEnv(appId, env)?.appId ?? null;
 }
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export function storeUnreachableStatus(status) {
+    return status === 502 || status === 503 || status === 504 || (status >= 520 && status <= 530);
+}
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export class BinaryStoreUnreachableError extends Error {
+    status = 503;
+    code = 'BYTE_STORE_UNREACHABLE';
+    constructor(op, key, detail) {
+        super(`[binary-store] ${op} ${key}: the file store did not answer (${detail}) — nothing was saved; ` +
+            'everything already stored still opens. Try again when the home server is on.');
+        this.name = 'BinaryStoreUnreachableError';
+    }
+    getResponse() {
+        return new Response(JSON.stringify({
+            error: this.code,
+            message: 'The file store did not answer, so nothing was saved. Everything already stored still opens — try again in a moment.',
+        }), { status: 503, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': '30' } });
+    }
+}
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.33.0",
+	"version": "4.34.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.",

package/src/server/d1/fakeD1.ts

@@ -88,7 +88,7 @@ class FakeD1Statement implements D1BindingStatement {
 	) {}
 
 	bind(...values: unknown[]): D1BindingStatement {
-		values.forEach((v, i) => assertD1Bindable(v, i));
+		for (const [i, v] of values.entries()) assertD1Bindable(v, i);
 		// A real binding stores what it was given; the ArrayBuffer→Uint8Array conversion
 		// here is `bun:sqlite`'s requirement, not D1's, and happens below the emulated edge.
 		const stored = values.map((v) => (v instanceof ArrayBuffer ? new Uint8Array(v) : v));

package/src/server/d1/pullD1.spec.ts

@@ -144,6 +144,7 @@ describe('pulling D1 down — paged SELECTs, table by table, never an export', (
 			requiredTable: 'items',
 			afterLoadSql: REBUILD,
 			wrangler: run,
+			log: () => {},
 		});
 	const opened = (dir: string) => new Database(join(dir, 'pulled.sqlite'), { readonly: true });
 
@@ -222,6 +223,62 @@ describe('pulling D1 down — paged SELECTs, table by table, never an export', (
 		);
 	});
 
+	test('🔴 one refused page does not shrink the rest of the table — the size doubles back to PAGE_ROWS (desk, 2026-09-25: 15 rows per call for hours)', async () => {
+		const dir = scratch();
+		const n = PAGE_ROWS * 3 + 7;
+		const source = live(
+			`WITH RECURSIVE s(i) AS (SELECT 1 UNION ALL SELECT i + 1 FROM s WHERE i < ${n}) INSERT INTO items_fts_map (item_id, text) SELECT 'i' || i, 't' FROM s; INSERT INTO items VALUES ('i1', 'x');`,
+		);
+		let failed = false;
+		const { run, seen } = d1(source, {
+			failWhen: (sql) => {
+				if (failed || !sql.includes('FROM "items_fts_map"')) return false;
+				failed = true;
+				return true;
+			},
+		});
+		const logged: string[] = [];
+		await pullD1ToSqlite({
+			destination: join(dir, 'pulled.sqlite'),
+			database: 'collections',
+			schemaSql: SCHEMA,
+			requiredTable: 'items',
+			afterLoadSql: REBUILD,
+			wrangler: run,
+			log: (line) => logged.push(line),
+		});
+		const db = opened(dir);
+		expect((db.query('select count(*) n from items_fts_map').get() as { n: number }).n).toBe(n);
+		db.close();
+		const limits = seen
+			.map((a) => a[a.indexOf('--command') + 1] as string)
+			.filter((sql) => sql.includes('FROM "items_fts_map"'))
+			.map((sql) => Number(/LIMIT (\d+)/.exec(sql)?.[1]));
+		// refused at 500, read at 250, then back to 500 for the rest.
+		expect(limits.slice(0, 3)).toEqual([PAGE_ROWS, PAGE_ROWS / 2, PAGE_ROWS]);
+		expect(limits.slice(2).every((limit) => limit === PAGE_ROWS)).toBe(true);
+		expect(logged).toHaveLength(1);
+		expect(logged[0]).toContain('D1 said no');
+		expect(logged[0]).toContain(`page of ${PAGE_ROWS}`);
+	});
+
+	test('a table D1 refuses on every call still THROWS with D1\'s own words, after logging each halving', async () => {
+		const source = live("INSERT INTO items VALUES ('i1', 'a');");
+		const logged: string[] = [];
+		await expect(
+			pullD1ToSqlite({
+				destination: join(scratch(), 'pulled.sqlite'),
+				database: 'collections',
+				schemaSql: SCHEMA,
+				requiredTable: 'items',
+				wrangler: d1(source, { failWhen: (sql) => sql.includes('FROM "items"') }).run,
+				log: (line) => logged.push(line),
+			}),
+		).rejects.toThrow(/could not read `items` from D1: ✘ D1 said no/);
+		// 500 → 250 → 125 → 62 → 31 → 15 → 7 → 3 → 1: eight halvings, then the refusal at one row.
+		expect(logged).toHaveLength(8);
+	});
+
 	test('🔴 a table D1 holds that the schema does not declare is created from D1\'s own DDL', async () => {
 		const dir = scratch();
 		const ddl = 'CREATE TABLE art_lookups (key TEXT PRIMARY KEY, art_key TEXT)';

package/src/server/d1/pullD1.ts

@@ -202,6 +202,11 @@ export interface PullD1Options {
 	/** Run after the rows are loaded — where an app REBUILDS its search index (never copied). */
 	afterLoadSql?: string;
 	wrangler: Wrangler;
+	/**
+	 * Where a page D1 refused is reported (default: stderr). Before 4.33.1 a halving was silent,
+	 * so the only symptom of a slow spell was a backup that took hours.
+	 */
+	log?: (line: string) => void;
 }
 
 const sqlIdent = (name: string): string => `"${name.replaceAll('"', '""')}"`;
@@ -250,8 +255,20 @@ export function pageSql(plan: TablePlan, limit: number, after: { key?: number; o
 	return `SELECT ${values} FROM ${sqlIdent(plan.table)} ORDER BY ${order} LIMIT ${limit} OFFSET ${after.offset ?? 0}`;
 }
 
-/** Every row of one table as `INSERT INTO …;` lines, read in pages that never block D1. */
-function dumpTable(wrangler: Wrangler, database: string, plan: TablePlan): { text: string; rows: number } {
+/**
+ * Every row of one table as `INSERT INTO …;` lines, read in pages that never block D1.
+ *
+ * A page D1 refuses is asked again at half the size, and 🔴 every page that SUCCEEDS doubles the
+ * size back toward {@link PAGE_ROWS}. Before 4.33.1 nothing grew it back: desk's first launchd
+ * backup (2026-09-25) hit a few slow calls early and read its 3,381-row table 15 rows per call —
+ * 225 two-minute calls, on course for hours. Only a refusal at ONE row is fatal.
+ */
+function dumpTable(
+	wrangler: Wrangler,
+	database: string,
+	plan: TablePlan,
+	log: (line: string) => void,
+): { text: string; rows: number } {
 	const into = `INSERT INTO ${sqlIdent(plan.table)} (${plan.columns.map(sqlIdent).join(', ')}) VALUES (`;
 	const lines: string[] = [];
 	let limit = PAGE_ROWS;
@@ -261,11 +278,14 @@ function dumpTable(wrangler: Wrangler, database: string, plan: TablePlan): { tex
 		try {
 			page = execute(wrangler, database, pageSql(plan, limit, after))[0] ?? [];
 		} catch (error) {
+			const message = (error as Error).message;
 			if (limit > 1) {
-				limit = Math.max(1, Math.floor(limit / 2));
+				const next = Math.max(1, Math.floor(limit / 2));
+				log(`pull D1: \`${plan.table}\` refused a page of ${limit} — asking for ${next}: ${message}`);
+				limit = next;
 				continue;
 			}
-			throw new Error(`could not read \`${plan.table}\` from D1: ${(error as Error).message}`);
+			throw new Error(`could not read \`${plan.table}\` from D1: ${message}`);
 		}
 		for (const row of page) {
 			const literals = plan.columns.map((_, i) => row[`c${i}`]);
@@ -276,6 +296,7 @@ function dumpTable(wrangler: Wrangler, database: string, plan: TablePlan): { tex
 		}
 		if (page.length < limit) break;
 		after = plan.key ? { key: Number(page[page.length - 1]?.k) } : { offset: (after.offset ?? 0) + page.length };
+		limit = Math.min(PAGE_ROWS, limit * 2);
 	}
 	return { text: lines.join('\n'), rows: lines.length };
 }
@@ -290,6 +311,7 @@ function dumpTable(wrangler: Wrangler, database: string, plan: TablePlan): { tex
  */
 export async function pullD1ToSqlite(options: PullD1Options): Promise<void> {
 	const { destination, database, wrangler } = options;
+	const log = options.log ?? ((line: string) => console.error(line));
 	let rows: Array<{ name: string; sql: string | null }>;
 	try {
 		rows = (execute(wrangler, database, "select name, sql from sqlite_master where type = 'table'")[0] ?? []) as typeof rows;
@@ -313,7 +335,7 @@ export async function pullD1ToSqlite(options: PullD1Options): Promise<void> {
 	const dumps = tables.map((table, i) => {
 		const cols = (columnSets[i] ?? []) as Array<{ name: string; pk: number }>;
 		const plan = tablePlan(table, rows.find((r) => r.name === table)?.sql ?? null, cols);
-		return { table, ...dumpTable(wrangler, database, plan) };
+		return { table, ...dumpTable(wrangler, database, plan, log) };
 	});
 	if (dumps.every((d) => d.rows === 0)) {
 		throw new Error('the D1 pull contains no rows — refusing to snapshot an empty database as if it were the library');

package/src/server/storage/binaryStore.spec.ts

@@ -34,6 +34,7 @@ import {
   BINARY_REPEAT_THRESHOLD,
   BINARY_REPEAT_WINDOW_MS,
   type BinaryStoreConfig,
+  BinaryStoreUnreachableError,
   binaryStoreTenant,
   createBinaryStore,
   normalizePrivateKeyPem,
@@ -41,6 +42,7 @@ import {
   repeatedBinaryKeys,
   resetRepeatedBinaryKeys,
   resolvedMediaTenant,
+  storeUnreachableStatus,
   wantsFresh,
 } from './binaryStore.js';
 import { binaryStoreFakeDefaults } from './binaryStoreFake.js';
@@ -962,3 +964,58 @@ describe('binaryStoreFakeDefaults', () => {
     expect(await fake.signToken({ k: 'c/a' }, 60)).toBe('fake-token');
   });
 });
+
+describe('🔴 a write the store could not ANSWER is a 503 that names it (2026-09-26)', () => {
+  it('502-504 and 52x/530 are the origin unreachable; everything else is its own answer', () => {
+    for (const status of [502, 503, 504, 520, 522, 524, 530]) expect(storeUnreachableStatus(status)).toBe(true);
+    for (const status of [400, 403, 404, 413, 422, 500, 507]) expect(storeUnreachableStatus(status)).toBe(false);
+  });
+
+  it('put on a 530 throws the typed error, keeping the [binary-store] head batch callers print', async () => {
+    reply = () => new Response('tunnel gone', { status: 530 });
+    const error = await makeStore().put('art/a.png', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toStartWith('[binary-store] put art/a.png: the file store did not answer (530)');
+    expect((error as BinaryStoreUnreachableError).status).toBe(503);
+  });
+
+  it('a fetch that THROWS is the same fact', async () => {
+    const store = makeStore({ fetch: () => Promise.reject(new Error('connection refused')) });
+    const error = await store.put('k', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toContain('connection refused');
+  });
+
+  it('putLarge says which chunk found the store gone', async () => {
+    reply = () => new Response('', { status: 502 });
+    const error = await makeStore()
+      .putLarge('v.mp4', new Uint8Array(10), 'video/mp4', { chunkBytes: 4 })
+      .catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toContain('chunk 1/3: 502');
+  });
+
+  it('🔴 getResponse() is the 503 a Hono app answers with when the error escapes a route', async () => {
+    const res = new BinaryStoreUnreachableError('put', 'k', '530').getResponse();
+    expect(res.status).toBe(503);
+    expect(res.headers.get('retry-after')).toBe('30');
+    expect(((await res.json()) as { error: string }).error).toBe('BYTE_STORE_UNREACHABLE');
+  });
+
+  it('…and a real Hono app DOES answer it, with no onError of its own', async () => {
+    const { Hono } = await import('hono');
+    const app = new Hono().post('/upload', () => {
+      throw new BinaryStoreUnreachableError('put', 'k', '530');
+    });
+    const res = await app.request('/upload', { method: 'POST' });
+    expect(res.status).toBe(503);
+    expect(((await res.json()) as { error: string }).error).toBe('BYTE_STORE_UNREACHABLE');
+  });
+
+  it("the origin's own refusals are unchanged — a 403 is still the plain status error", async () => {
+    reply = () => new Response('', { status: 403 });
+    const error = await makeStore().put('k', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).not.toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toBe('[binary-store] put k: 403');
+  });
+});

package/src/server/storage/binaryStore.ts

@@ -725,7 +725,10 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
           headers: mime ? { 'content-type': mime } : undefined,
           body: bytes as unknown as BodyInit,
         },
-      );
+      ).catch((cause: unknown) => {
+        throw new BinaryStoreUnreachableError('put', key, cause instanceof Error ? cause.message : String(cause));
+      });
+      if (storeUnreachableStatus(res.status)) throw new BinaryStoreUnreachableError('put', key, String(res.status));
       if (!res.ok) {
         // A 413 that reaches here despite the threshold above means the edge's
         // real cap is lower than we think, or the caller disabled the
@@ -805,7 +808,12 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
             headers: mime ? { 'content-type': mime } : undefined,
             body: slice,
           },
-        );
+        ).catch((cause: unknown) => {
+          throw new BinaryStoreUnreachableError('putLarge', key, cause instanceof Error ? cause.message : String(cause));
+        });
+        if (storeUnreachableStatus(res.status)) {
+          throw new BinaryStoreUnreachableError('putLarge', key, `chunk ${ci + 1}/${total}: ${res.status}`);
+        }
         if (!res.ok) {
           throw new Error(`[binary-store] putLarge ${key} chunk ${ci + 1}/${total}: ${res.status}`);
         }
@@ -1071,6 +1079,48 @@ export function resolvedMediaTenant(
   return readBinaryStoreEnv(appId, env)?.appId ?? null;
 }
 
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export function storeUnreachableStatus(status: number): boolean {
+  return status === 502 || status === 503 || status === 504 || (status >= 520 && status <= 530);
+}
+
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export class BinaryStoreUnreachableError extends Error {
+  readonly status = 503;
+  readonly code = 'BYTE_STORE_UNREACHABLE';
+  constructor(op: string, key: string, detail: string) {
+    super(
+      `[binary-store] ${op} ${key}: the file store did not answer (${detail}) — nothing was saved; ` +
+        'everything already stored still opens. Try again when the home server is on.',
+    );
+    this.name = 'BinaryStoreUnreachableError';
+  }
+  getResponse(): Response {
+    return new Response(
+      JSON.stringify({
+        error: this.code,
+        message:
+          'The file store did not answer, so nothing was saved. Everything already stored still opens — try again in a moment.',
+      }),
+      { status: 503, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': '30' } },
+    );
+  }
+}
+
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):