@powerhousedao/reactor-attachments 6.1.0-dev.17 → 6.1.0-dev.18

package/dist/index.js

@@ -56,6 +56,80 @@ var UploadTooLarge = class extends Error {
 		this.maxBytes = maxBytes;
 	}
 };
+/**
+* Thrown by reserve() when the claimed hash is already available in the store.
+* The caller should use err.ref directly and upload nothing -- this is the
+* dedup fast path: duplicate content never leaves the client.
+*/
+var AttachmentAlreadyExists = class extends Error {
+	hash;
+	ref;
+	constructor(hash, ref) {
+		super(`Attachment already exists for hash: ${hash}`);
+		this.name = "AttachmentAlreadyExists";
+		this.hash = hash;
+		this.ref = ref;
+	}
+};
+/**
+* Thrown by send() when the server-computed hash of the uploaded bytes
+* does not match the hash claimed at reservation time. Nothing is committed;
+* the reservation is retained so the client can retry with correct bytes.
+*/
+var HashMismatch = class extends Error {
+	claimed;
+	actual;
+	constructor(claimed, actual) {
+		super(`Hash mismatch: claimed ${claimed} but computed ${actual}`);
+		this.name = "HashMismatch";
+		this.claimed = claimed;
+		this.actual = actual;
+	}
+};
+/**
+* Thrown by send() when the uploaded byte count does not equal the
+* sizeBytes declared at reservation time. The handle may reject
+* mid-stream as soon as the count exceeds the declaration.
+* Nothing is committed; the reservation is retained for retry.
+*
+* "actual" is the byte count received from the stream before aborting --
+* it includes the chunk that crossed the declaration and can exceed bytes
+* persisted. On mid-stream aborts the true total is unknown; at least
+* "actual" bytes were sent.
+*/
+var SizeMismatch = class extends Error {
+	declared;
+	actual;
+	constructor(declared, actual) {
+		super(`Size mismatch: declared ${declared} bytes but received ${actual}`);
+		this.name = "SizeMismatch";
+		this.declared = declared;
+		this.actual = actual;
+	}
+};
+/**
+* Thrown by get() when the hash is reserved by an in-flight upload and
+* bytes are not yet available anywhere. Deliberately NOT a subclass of
+* AttachmentNotFound -- callers must distinguish "retry later" from "unknown".
+* After expiresAtUtc has passed the hash reads as not found.
+*
+* metadata is populated when the reservation is local and its fields are
+* known (mimeType, fileName, sizeBytes). It is undefined when the pending
+* state is learned from a remote transport that did not supply the full
+* Attachment-Pending header (transport-pending / degraded wire case).
+*/
+var AttachmentPending = class extends Error {
+	hash;
+	expiresAtUtc;
+	metadata;
+	constructor(hash, expiresAtUtc, meta) {
+		super(`Attachment pending upload for hash: ${hash}, expires: ${expiresAtUtc}`);
+		this.name = "AttachmentPending";
+		this.hash = hash;
+		this.expiresAtUtc = expiresAtUtc;
+		this.metadata = meta;
+	}
+};
 //#endregion
 //#region src/ref.ts
 const REF_PATTERN = /^attachment:\/\/v(\d+):(.+)$/;
@@ -73,6 +147,7 @@ function createRef(hash, version = DEFAULT_VERSION) {
 }
 //#endregion
 //#region src/attachment-service.ts
+const CLIENT_HASH_PATTERN = /^[a-f0-9]{64}$/;
 var AttachmentService = class {
 	constructor(store, reservations, uploadFactory) {
 		this.store = store;
@@ -80,8 +155,9 @@ var AttachmentService = class {
 		this.uploadFactory = uploadFactory;
 	}
 	async reserve(options) {
+		if (options.clientHash !== void 0) return this.reserveHashFirst(options);
 		const reservation = await this.reservations.create(options);
-		return this.uploadFactory.createUpload(reservation.reservationId, options);
+		return this.uploadFactory.createUpload(reservation);
 	}
 	async stat(ref) {
 		const { hash } = parseRef(ref);
@@ -91,6 +167,24 @@ var AttachmentService = class {
 		const { hash } = parseRef(ref);
 		return this.store.get(hash, signal);
 	}
+	async reserveHashFirst(options) {
+		const normalized = options.clientHash.toLowerCase();
+		if (!CLIENT_HASH_PATTERN.test(normalized)) throw new Error(`clientHash must be a 64-character lowercase hex string, got: ${options.clientHash}`);
+		if (options.sizeBytes === void 0 || !Number.isInteger(options.sizeBytes) || options.sizeBytes <= 0 || !Number.isSafeInteger(options.sizeBytes)) throw new Error("sizeBytes must be a positive safe integer when clientHash is provided");
+		const normalizedOptions = {
+			...options,
+			clientHash: normalized
+		};
+		let existingHeader = null;
+		try {
+			existingHeader = await this.store.stat(normalized);
+		} catch (err) {
+			if (!(err instanceof AttachmentNotFound) && !(err instanceof AttachmentPending)) throw err;
+		}
+		if (existingHeader !== null && existingHeader.status === "available") throw new AttachmentAlreadyExists(normalized, createRef(normalized));
+		const reservation = await this.reservations.create(normalizedOptions);
+		return this.uploadFactory.createUpload(reservation);
+	}
 };
 //#endregion
 //#region src/storage/fs/attachment-fs.ts
@@ -115,13 +209,24 @@ async function writeAttachmentBytes(path, data) {
 			const { done, value } = await reader.read();
 			if (done) break;
 			bytesWritten += value.byteLength;
-			if (!writer.write(value)) await new Promise((resolve) => writer.once("drain", resolve));
+			if (!writer.write(value)) await new Promise((resolve, reject) => {
+				const onDrain = () => {
+					writer.off("error", onError);
+					resolve();
+				};
+				const onError = (err) => {
+					writer.off("drain", onDrain);
+					reject(err);
+				};
+				writer.once("drain", onDrain);
+				writer.once("error", onError);
+			});
 		}
 	} finally {
 		reader.releaseLock();
 		await new Promise((resolve, reject) => {
 			writer.end(() => resolve());
-			writer.on("error", reject);
+			writer.once("error", reject);
 		});
 	}
 	return bytesWritten;
@@ -149,9 +254,16 @@ async function deleteAttachmentBytes(path) {
 *
 * If `maxBytes` is set and the input exceeds it, the temp file is removed and
 * `UploadTooLarge` is thrown.
+*
+* If `declaredSizeBytes` is set, the byte count is enforced as a contract:
+* mid-stream, the moment the count exceeds the declaration the reader is
+* released and `SizeMismatch` is thrown without consuming the rest of the
+* stream. At stream end, if the count does not equal the declaration,
+* `SizeMismatch` is thrown. Both the `maxBytes` and `declaredSizeBytes`
+* checks apply; `maxBytes` is evaluated first on each chunk.
 */
 async function streamHashAndWrite(basePath, data, options = {}) {
-	const { maxBytes } = options;
+	const { maxBytes, declaredSizeBytes } = options;
 	const tmpDir = join(basePath, ".tmp");
 	await mkdir(tmpDir, { recursive: true });
 	const tempPath = join(tmpDir, randomUUID());
@@ -166,6 +278,7 @@ async function streamHashAndWrite(basePath, data, options = {}) {
 			if (done) break;
 			sizeBytes += value.byteLength;
 			if (maxBytes !== void 0 && sizeBytes > maxBytes) throw new UploadTooLarge(maxBytes);
+			if (declaredSizeBytes !== void 0 && sizeBytes > declaredSizeBytes) throw new SizeMismatch(declaredSizeBytes, sizeBytes);
 			hasher.update(value);
 			if (!writer.write(value)) await new Promise((resolve, reject) => {
 				const onDrain = () => {
@@ -185,17 +298,30 @@ async function streamHashAndWrite(basePath, data, options = {}) {
 	} finally {
 		reader.releaseLock();
 	}
-	await new Promise((resolve, reject) => {
-		writer.end((err) => {
-			if (err) reject(err);
-			else resolve();
+	let endError;
+	try {
+		await new Promise((resolve, reject) => {
+			writer.end((err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+			writer.once("error", reject);
 		});
-		writer.on("error", reject);
-	});
+	} catch (err) {
+		endError = err instanceof Error ? err : new Error(String(err));
+	}
 	if (caughtError) {
 		await rm(tempPath, { force: true });
 		throw caughtError;
 	}
+	if (endError) {
+		await rm(tempPath, { force: true });
+		throw endError;
+	}
+	if (declaredSizeBytes !== void 0 && sizeBytes !== declaredSizeBytes) {
+		await rm(tempPath, { force: true });
+		throw new SizeMismatch(declaredSizeBytes, sizeBytes);
+	}
 	return {
 		tempPath,
 		hash: hasher.digest("hex"),
@@ -214,7 +340,8 @@ function rowToHeader$1(row) {
 		status: row.status,
 		source: row.source,
 		createdAtUtc: row.created_at_utc,
-		lastAccessedAtUtc: row.last_accessed_at_utc
+		lastAccessedAtUtc: row.last_accessed_at_utc,
+		expiresAtUtc: null
 	};
 }
 function wrapStreamWithCleanup(source, cleanup) {
@@ -254,30 +381,62 @@ var KyselyAttachmentStore = class {
 	}
 	async stat(hash) {
 		const row = await this.db.selectFrom("attachment").selectAll().where("hash", "=", hash).executeTakeFirst();
-		if (!row) throw new AttachmentNotFound(hash);
-		return rowToHeader$1(row);
+		if (row) return rowToHeader$1(row);
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const pending = await this.findPendingReservation(hash, now);
+		if (pending) return {
+			hash,
+			mimeType: pending.mime_type,
+			fileName: pending.file_name,
+			sizeBytes: Number(pending.size_bytes),
+			extension: pending.extension,
+			status: "pending",
+			source: "local",
+			createdAtUtc: pending.created_at_utc,
+			lastAccessedAtUtc: pending.created_at_utc,
+			expiresAtUtc: pending.expires_at_utc
+		};
+		throw new AttachmentNotFound(hash);
 	}
 	async has(hash) {
 		return (await this.db.selectFrom("attachment").select("status").where("hash", "=", hash).executeTakeFirst())?.status === "available";
 	}
 	async get(hash, signal) {
 		const row = await this.db.selectFrom("attachment").selectAll().where("hash", "=", hash).executeTakeFirst();
-		if (!row) throw new AttachmentNotFound(hash);
-		if (row.status === "evicted") {
-			const remote = await this.transport.fetch(hash, signal);
-			if (!remote) throw new AttachmentNotFound(hash);
-			await this.put(hash, remote.metadata, remote.body);
-			return this.get(hash, signal);
+		if (row) {
+			if (row.status === "evicted") {
+				const remote = await this.transport.fetch(hash, signal);
+				if (remote.kind === "data") {
+					await this.put(hash, remote.response.metadata, remote.response.body);
+					return this.get(hash, signal);
+				}
+				if (remote.kind === "pending") throw new AttachmentPending(hash, remote.expiresAtUtc);
+				throw new AttachmentNotFound(hash);
+			}
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			await this.db.updateTable("attachment").set({ last_accessed_at_utc: now }).where("hash", "=", hash).execute();
+			const header = rowToHeader$1(row);
+			header.lastAccessedAtUtc = now;
+			this.acquireReader(hash);
+			return {
+				header,
+				body: wrapStreamWithCleanup(readAttachmentStream(join(this.basePath, row.storage_path)), () => this.releaseReader(hash))
+			};
 		}
 		const now = (/* @__PURE__ */ new Date()).toISOString();
-		await this.db.updateTable("attachment").set({ last_accessed_at_utc: now }).where("hash", "=", hash).execute();
-		const header = rowToHeader$1(row);
-		header.lastAccessedAtUtc = now;
-		this.acquireReader(hash);
-		return {
-			header,
-			body: wrapStreamWithCleanup(readAttachmentStream(join(this.basePath, row.storage_path)), () => this.releaseReader(hash))
-		};
+		const pending = await this.findPendingReservation(hash, now);
+		if (pending) throw new AttachmentPending(hash, pending.expires_at_utc, {
+			mimeType: pending.mime_type,
+			fileName: pending.file_name,
+			sizeBytes: pending.size_bytes
+		});
+		const remote = await this.transport.fetch(hash, signal);
+		if (remote.kind === "data") {
+			await this.put(hash, remote.response.metadata, remote.response.body);
+			return this.get(hash, signal);
+		}
+		if (remote.kind === "pending") throw new AttachmentPending(hash, remote.expiresAtUtc);
+		throw new AttachmentNotFound(hash);
 	}
 	async put(hash, metadata, data) {
 		const existing = await this.db.selectFrom("attachment").select(["hash", "status"]).where("hash", "=", hash).executeTakeFirst();
@@ -317,6 +476,25 @@ var KyselyAttachmentStore = class {
 		const result = await this.db.selectFrom("attachment").select(sql`COALESCE(SUM(size_bytes), 0)`.as("total")).where("status", "=", "available").executeTakeFirst();
 		return Number(result?.total ?? 0);
 	}
+	async findPendingReservation(hash, now) {
+		const row = await this.db.selectFrom("attachment_reservation as r").leftJoin("attachment as a", "a.hash", "r.client_hash").select([
+			"r.mime_type",
+			"r.file_name",
+			"r.extension",
+			"r.size_bytes",
+			"r.created_at_utc",
+			"r.expires_at_utc"
+		]).where("r.client_hash", "=", hash).where("r.deleted_at_utc", "is", null).where("r.expires_at_utc", ">", now).where("r.size_bytes", "is not", null).where("a.hash", "is", null).orderBy("r.expires_at_utc", "desc").executeTakeFirst();
+		if (!row) return null;
+		return {
+			mime_type: row.mime_type,
+			file_name: row.file_name,
+			extension: row.extension,
+			size_bytes: Number(row.size_bytes),
+			created_at_utc: row.created_at_utc,
+			expires_at_utc: row.expires_at_utc
+		};
+	}
 	acquireReader(hash) {
 		this.activeReaders.set(hash, (this.activeReaders.get(hash) ?? 0) + 1);
 	}
@@ -339,7 +517,9 @@ function rowToReservation(row) {
 		fileName: row.file_name,
 		extension: row.extension,
 		createdAtUtc: row.created_at_utc,
-		expiresAtUtc: row.expires_at_utc
+		expiresAtUtc: row.expires_at_utc,
+		clientHash: row.client_hash,
+		sizeBytes: row.size_bytes !== null ? Number(row.size_bytes) : null
 	};
 }
 var KyselyReservationStore = class {
@@ -359,7 +539,9 @@ var KyselyReservationStore = class {
 			file_name: options.fileName,
 			extension: options.extension ?? null,
 			created_at_utc: now,
-			expires_at_utc: expiresAt
+			expires_at_utc: expiresAt,
+			client_hash: options.clientHash ?? null,
+			size_bytes: options.sizeBytes ?? null
 		}).returningAll().executeTakeFirstOrThrow());
 	}
 	async get(reservationId) {
@@ -379,72 +561,89 @@ var KyselyReservationStore = class {
 //#endregion
 //#region src/storage/migrations/001_create_attachment_table.ts
 var _001_create_attachment_table_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$4,
-	up: () => up$4
+	down: () => down$5,
+	up: () => up$5
 });
-async function up$4(db) {
+async function up$5(db) {
 	await db.schema.createTable("attachment").addColumn("hash", "text", (col) => col.primaryKey()).addColumn("mime_type", "text", (col) => col.notNull()).addColumn("file_name", "text", (col) => col.notNull()).addColumn("size_bytes", "bigint", (col) => col.notNull()).addColumn("extension", "text").addColumn("status", "text", (col) => col.notNull().defaultTo("available")).addColumn("storage_path", "text", (col) => col.notNull()).addColumn("source", "text", (col) => col.notNull().defaultTo("local")).addColumn("created_at_utc", "text", (col) => col.notNull()).addColumn("last_accessed_at_utc", "text", (col) => col.notNull()).execute();
 	await db.schema.createIndex("idx_attachment_status").on("attachment").column("status").execute();
 	await db.schema.createIndex("idx_attachment_lru").on("attachment").columns(["status", "last_accessed_at_utc"]).execute();
 }
-async function down$4(db) {
+async function down$5(db) {
 	await db.schema.dropTable("attachment").ifExists().execute();
 }
 //#endregion
 //#region src/storage/migrations/002_create_reservation_table.ts
 var _002_create_reservation_table_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$3,
-	up: () => up$3
+	down: () => down$4,
+	up: () => up$4
 });
-async function up$3(db) {
+async function up$4(db) {
 	await db.schema.createTable("attachment_reservation").addColumn("reservation_id", "text", (col) => col.primaryKey()).addColumn("mime_type", "text", (col) => col.notNull()).addColumn("file_name", "text", (col) => col.notNull()).addColumn("extension", "text").addColumn("created_at_utc", "text", (col) => col.notNull()).execute();
 }
-async function down$3(db) {
+async function down$4(db) {
 	await db.schema.dropTable("attachment_reservation").ifExists().execute();
 }
 //#endregion
 //#region src/storage/migrations/003_add_reservation_expires_at.ts
 var _003_add_reservation_expires_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$2,
-	up: () => up$2
+	down: () => down$3,
+	up: () => up$3
 });
-async function up$2(db) {
+async function up$3(db) {
 	await db.schema.alterTable("attachment_reservation").addColumn("expires_at_utc", "text").execute();
 	await db.updateTable("attachment_reservation").set({ expires_at_utc: sql`created_at_utc` }).where("expires_at_utc", "is", null).execute();
 	await db.schema.alterTable("attachment_reservation").alterColumn("expires_at_utc", (col) => col.setNotNull()).execute();
 	await db.schema.createIndex("idx_reservation_expires_at").on("attachment_reservation").column("expires_at_utc").execute();
 }
-async function down$2(db) {
+async function down$3(db) {
 	await db.schema.dropIndex("idx_reservation_expires_at").ifExists().execute();
 	await db.schema.alterTable("attachment_reservation").dropColumn("expires_at_utc").execute();
 }
 //#endregion
 //#region src/storage/migrations/004_add_reservation_soft_delete.ts
 var _004_add_reservation_soft_delete_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$1,
-	up: () => up$1
+	down: () => down$2,
+	up: () => up$2
 });
-async function up$1(db) {
+async function up$2(db) {
 	await db.schema.alterTable("attachment_reservation").addColumn("deleted_at_utc", "text").execute();
 }
-async function down$1(db) {
+async function down$2(db) {
 	await db.schema.alterTable("attachment_reservation").dropColumn("deleted_at_utc").execute();
 }
 //#endregion
 //#region src/storage/migrations/005_add_reservation_active_index.ts
 var _005_add_reservation_active_index_exports = /* @__PURE__ */ __exportAll({
-	down: () => down,
-	up: () => up
+	down: () => down$1,
+	up: () => up$1
 });
-async function up(db) {
+async function up$1(db) {
 	await db.schema.dropIndex("idx_reservation_expires_at").ifExists().execute();
 	await db.schema.createIndex("idx_reservation_expires_at_active").on("attachment_reservation").column("expires_at_utc").where(sql`deleted_at_utc IS NULL`).execute();
 }
-async function down(db) {
+async function down$1(db) {
 	await db.schema.dropIndex("idx_reservation_expires_at_active").ifExists().execute();
 	await db.schema.createIndex("idx_reservation_expires_at").on("attachment_reservation").column("expires_at_utc").execute();
 }
 //#endregion
+//#region src/storage/migrations/006_add_reservation_client_hash.ts
+var _006_add_reservation_client_hash_exports = /* @__PURE__ */ __exportAll({
+	down: () => down,
+	up: () => up
+});
+async function up(db) {
+	await db.schema.alterTable("attachment_reservation").addColumn("client_hash", "text").execute();
+	await db.schema.alterTable("attachment_reservation").addColumn("size_bytes", "bigint").execute();
+	await db.schema.alterTable("attachment_reservation").addCheckConstraint("attachment_reservation_hash_size_check", sql`client_hash is null or size_bytes is not null`).execute();
+	await db.schema.createIndex("idx_reservation_client_hash").on("attachment_reservation").column("client_hash").execute();
+}
+async function down(db) {
+	await db.schema.dropIndex("idx_reservation_client_hash").ifExists().execute();
+	await db.schema.alterTable("attachment_reservation").dropColumn("size_bytes").execute();
+	await db.schema.alterTable("attachment_reservation").dropColumn("client_hash").execute();
+}
+//#endregion
 //#region src/storage/migrations/migrator.ts
 const ATTACHMENT_SCHEMA = "attachments";
 const migrations = {
@@ -452,7 +651,8 @@ const migrations = {
 	"002_create_reservation_table": _002_create_reservation_table_exports,
 	"003_add_reservation_expires_at": _003_add_reservation_expires_at_exports,
 	"004_add_reservation_soft_delete": _004_add_reservation_soft_delete_exports,
-	"005_add_reservation_active_index": _005_add_reservation_active_index_exports
+	"005_add_reservation_active_index": _005_add_reservation_active_index_exports,
+	"006_add_reservation_client_hash": _006_add_reservation_client_hash_exports
 };
 var ProgrammaticMigrationProvider = class {
 	getMigrations() {
@@ -507,21 +707,35 @@ function rowToHeader(row) {
 		status: row.status,
 		source: row.source,
 		createdAtUtc: row.created_at_utc,
-		lastAccessedAtUtc: row.last_accessed_at_utc
+		lastAccessedAtUtc: row.last_accessed_at_utc,
+		expiresAtUtc: null
 	};
 }
 var DirectAttachmentUpload = class {
 	reservationId;
-	constructor(reservationId, options, db, basePath, reservations, maxBytes) {
-		this.options = options;
+	ref;
+	expiresAtUtc;
+	constructor(reservation, db, basePath, reservations, maxBytes) {
+		this.reservation = reservation;
 		this.db = db;
 		this.basePath = basePath;
 		this.reservations = reservations;
 		this.maxBytes = maxBytes;
-		this.reservationId = reservationId;
+		this.reservationId = reservation.reservationId;
+		this.ref = reservation.clientHash != null ? createRef(reservation.clientHash) : null;
+		this.expiresAtUtc = reservation.expiresAtUtc;
 	}
 	async send(data) {
-		const { tempPath, hash, sizeBytes } = await streamHashAndWrite(this.basePath, data, { maxBytes: this.maxBytes });
+		if (this.reservation.clientHash != null && this.reservation.sizeBytes == null) throw new Error("hash-first reservation missing sizeBytes");
+		const declaredSizeBytes = this.reservation.clientHash != null ? this.reservation.sizeBytes ?? void 0 : void 0;
+		const { tempPath, hash, sizeBytes } = await streamHashAndWrite(this.basePath, data, {
+			maxBytes: this.maxBytes,
+			declaredSizeBytes
+		});
+		if (this.reservation.clientHash != null && hash !== this.reservation.clientHash) {
+			await rm(tempPath, { force: true });
+			throw new HashMismatch(this.reservation.clientHash, hash);
+		}
 		try {
 			const existing = await this.db.selectFrom("attachment").select(["hash", "status"]).where("hash", "=", hash).executeTakeFirst();
 			if (existing?.status === "available") await rm(tempPath, { force: true });
@@ -533,10 +747,10 @@ var DirectAttachmentUpload = class {
 				const now = (/* @__PURE__ */ new Date()).toISOString();
 				if (!existing) await this.db.insertInto("attachment").values({
 					hash,
-					mime_type: this.options.mimeType,
-					file_name: this.options.fileName,
+					mime_type: this.reservation.mimeType,
+					file_name: this.reservation.fileName,
 					size_bytes: sizeBytes,
-					extension: this.options.extension ?? null,
+					extension: this.reservation.extension ?? null,
 					status: "available",
 					storage_path: relPath,
 					source: "local",
@@ -572,8 +786,8 @@ var DirectAttachmentUploadFactory = class {
 		this.reservations = reservations;
 		this.maxBytes = maxBytes;
 	}
-	createUpload(reservationId, options) {
-		return new DirectAttachmentUpload(reservationId, options, this.db, this.basePath, this.reservations, this.maxBytes);
+	createUpload(reservation) {
+		return new DirectAttachmentUpload(reservation, this.db, this.basePath, this.reservations, this.maxBytes);
 	}
 };
 //#endregion
@@ -604,15 +818,28 @@ var SwitchboardAttachmentTransport = class {
 			signal,
 			headers
 		});
-		if (response.status === 404) return null;
+		if (response.status === 202) {
+			const expiresAtUtc = this.parsePendingExpiry(response);
+			if (!expiresAtUtc) throw new Error("Attachment fetch returned 202 with missing or malformed Attachment-Pending header");
+			return {
+				kind: "pending",
+				hash,
+				expiresAtUtc,
+				retryAfterMs: parseRetryAfterMs(response)
+			};
+		}
+		if (response.status === 404) return { kind: "not-found" };
 		if (!response.ok) throw new Error(`Attachment fetch failed: ${response.status} ${response.statusText}`);
 		const metadata = this.parseMetadataHeaders(response);
 		const body = response.body;
 		if (!body) throw new Error("Response body is null");
 		return {
-			hash,
-			metadata,
-			body
+			kind: "data",
+			response: {
+				hash,
+				metadata,
+				body
+			}
 		};
 	}
 	async announce(_hash) {}
@@ -627,6 +854,18 @@ var SwitchboardAttachmentTransport = class {
 		});
 		if (!response.ok) throw new Error(`Attachment push failed: ${response.status} ${response.statusText}`);
 	}
+	parsePendingExpiry(response) {
+		const header = response.headers.get("Attachment-Pending");
+		if (!header) return null;
+		try {
+			const parsed = JSON.parse(header);
+			if (!isRecord$3(parsed)) return null;
+			if (typeof parsed.expiresAtUtc !== "string") return null;
+			return parsed.expiresAtUtc;
+		} catch {
+			return null;
+		}
+	}
 	parseMetadataHeaders(response) {
 		let fallbackCache;
 		const fallback = () => {
@@ -636,7 +875,7 @@ var SwitchboardAttachmentTransport = class {
 		const metaHeader = response.headers.get("Attachment-Metadata");
 		if (metaHeader) try {
 			const parsed = JSON.parse(metaHeader);
-			if (isRecord$2(parsed)) {
+			if (isRecord$3(parsed)) {
 				if (parsed.extension === void 0) parsed.extension = null;
 				if (parsed.createdAtUtc === void 0) parsed.createdAtUtc = fallback().createdAtUtc;
 				if (parsed.lastAccessedAtUtc === void 0) parsed.lastAccessedAtUtc = fallback().lastAccessedAtUtc;
@@ -646,11 +885,19 @@ var SwitchboardAttachmentTransport = class {
 		return fallback();
 	}
 };
-function isRecord$2(value) {
+const DEFAULT_RETRY_AFTER_MS = 5e3;
+function parseRetryAfterMs(response) {
+	const retryAfter = response.headers.get("Retry-After");
+	if (!retryAfter) return DEFAULT_RETRY_AFTER_MS;
+	const seconds = Number(retryAfter);
+	if (!Number.isFinite(seconds) || seconds < 0) return DEFAULT_RETRY_AFTER_MS;
+	return Math.round(seconds * 1e3);
+}
+function isRecord$3(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isAttachmentMetadata$1(value) {
-	if (!isRecord$2(value)) return false;
+	if (!isRecord$3(value)) return false;
 	if (typeof value.mimeType !== "string") return false;
 	if (typeof value.fileName !== "string") return false;
 	if (typeof value.sizeBytes !== "number" || !Number.isFinite(value.sizeBytes) || value.sizeBytes < 0) return false;
@@ -678,7 +925,7 @@ function contentTypeFallback$1(response) {
 }
 //#endregion
 //#region src/switchboard/remote-reservation-store.ts
-function isRecord$1(value) {
+function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function deriveExtension(fileName) {
@@ -686,8 +933,8 @@ function deriveExtension(fileName) {
 	if (idx <= 0 || idx === fileName.length - 1) return null;
 	return fileName.slice(idx + 1).toLowerCase();
 }
-function isReservation(value) {
-	if (!isRecord$1(value)) return false;
+function isReservationBase(value) {
+	if (!isRecord$2(value)) return false;
 	if (typeof value.reservationId !== "string") return false;
 	if (typeof value.mimeType !== "string") return false;
 	if (typeof value.fileName !== "string") return false;
@@ -696,6 +943,12 @@ function isReservation(value) {
 	if (typeof value.expiresAtUtc !== "string") return false;
 	return true;
 }
+function isReservation(value) {
+	if (!isReservationBase(value)) return false;
+	if (value.clientHash !== void 0 && value.clientHash !== null && typeof value.clientHash !== "string") return false;
+	if (value.sizeBytes !== void 0 && value.sizeBytes !== null && typeof value.sizeBytes !== "number") return false;
+	return true;
+}
 var RemoteReservationStore = class {
 	remoteUrl;
 	jwtHandler;
@@ -709,28 +962,60 @@ var RemoteReservationStore = class {
 		const url = `${this.remoteUrl}/attachments/reservations`;
 		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
 		const extension = options.extension ?? deriveExtension(options.fileName);
+		const bodyObj = {
+			mimeType: options.mimeType,
+			fileName: options.fileName,
+			extension
+		};
+		if (options.clientHash !== void 0) bodyObj.clientHash = options.clientHash;
+		if (options.sizeBytes !== void 0) bodyObj.sizeBytes = options.sizeBytes;
 		const response = await this.fetchFn(url, {
 			method: "POST",
 			headers: {
 				...authHeaders,
 				"Content-Type": "application/json"
 			},
-			body: JSON.stringify({
-				mimeType: options.mimeType,
-				fileName: options.fileName,
-				extension
-			})
+			body: JSON.stringify(bodyObj)
 		});
+		if (response.status === 409) {
+			let body;
+			try {
+				body = await response.json();
+			} catch {
+				throw new Error(`Reservation create failed: ${response.status} ${response.statusText}`);
+			}
+			if (isRecord$2(body) && body.error === "already_exists" && options.clientHash !== void 0) {
+				let ref;
+				if (typeof body.ref === "string") try {
+					parseRef(body.ref);
+					ref = body.ref;
+				} catch {
+					ref = createRef(options.clientHash);
+				}
+				else ref = createRef(options.clientHash);
+				throw new AttachmentAlreadyExists(options.clientHash, ref);
+			}
+			throw new Error(`Reservation create failed: ${response.status} ${response.statusText}`);
+		}
 		if (!response.ok) throw new Error(`Reservation create failed: ${response.status} ${response.statusText}`);
-		const json = await response.json();
+		let json;
+		try {
+			json = await response.json();
+		} catch {
+			throw new Error("Reservation create returned non-JSON response");
+		}
+		if (typeof json !== "object" || json === null || typeof json.reservationId !== "string" || json.reservationId.length === 0) throw new Error("Reservation create returned a payload missing a non-empty reservationId string");
+		const body = json;
 		const now = /* @__PURE__ */ new Date();
 		return {
-			reservationId: json.reservationId,
+			reservationId: body.reservationId,
 			mimeType: options.mimeType,
 			fileName: options.fileName,
 			extension,
-			createdAtUtc: json.createdAtUtc ?? now.toISOString(),
-			expiresAtUtc: json.expiresAtUtc ?? new Date(now.getTime() + 1440 * 60 * 1e3).toISOString()
+			createdAtUtc: body.createdAtUtc ?? now.toISOString(),
+			expiresAtUtc: body.expiresAtUtc ?? new Date(now.getTime() + 1440 * 60 * 1e3).toISOString(),
+			clientHash: options.clientHash ?? null,
+			sizeBytes: options.sizeBytes ?? null
 		};
 	}
 	async get(reservationId) {
@@ -746,7 +1031,16 @@ var RemoteReservationStore = class {
 			throw new Error("Reservation get returned non-JSON response");
 		}
 		if (!isReservation(parsed)) throw new Error("Reservation get returned a payload that does not match the Reservation shape");
-		return parsed;
+		return {
+			reservationId: parsed.reservationId,
+			mimeType: parsed.mimeType,
+			fileName: parsed.fileName,
+			extension: parsed.extension,
+			createdAtUtc: parsed.createdAtUtc,
+			expiresAtUtc: parsed.expiresAtUtc,
+			clientHash: parsed.clientHash ?? null,
+			sizeBytes: parsed.sizeBytes ?? null
+		};
 	}
 	async delete(reservationId) {
 		const url = `${this.remoteUrl}/attachments/reservations/${encodeURIComponent(reservationId)}`;
@@ -763,15 +1057,20 @@ var RemoteReservationStore = class {
 };
 //#endregion
 //#region src/switchboard/remote-attachment-upload.ts
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 var RemoteAttachmentUpload = class {
 	reservationId;
+	ref;
+	expiresAtUtc;
 	remoteUrl;
 	jwtHandler;
 	fetchFn;
-	options;
-	constructor(reservationId, options, config) {
-		this.reservationId = reservationId;
-		this.options = options;
+	constructor(reservation, config) {
+		this.reservationId = reservation.reservationId;
+		this.ref = reservation.clientHash !== null ? createRef(reservation.clientHash) : null;
+		this.expiresAtUtc = reservation.expiresAtUtc;
 		this.remoteUrl = config.remoteUrl;
 		this.jwtHandler = config.jwtHandler;
 		this.fetchFn = (config.fetchFn ?? globalThis.fetch).bind(globalThis);
@@ -788,6 +1087,19 @@ var RemoteAttachmentUpload = class {
 			},
 			body
 		});
+		if (response.status === 422) {
+			let errorBody;
+			try {
+				errorBody = await response.json();
+			} catch {
+				throw new Error(`Attachment upload failed: ${response.status} ${response.statusText}`);
+			}
+			if (isRecord$1(errorBody)) {
+				if (errorBody.error === "hash_mismatch" && typeof errorBody.claimed === "string" && typeof errorBody.actual === "string") throw new HashMismatch(errorBody.claimed, errorBody.actual);
+				if (errorBody.error === "size_mismatch" && typeof errorBody.declared === "number" && typeof errorBody.actual === "number") throw new SizeMismatch(errorBody.declared, errorBody.actual);
+			}
+			throw new Error(`Attachment upload failed: ${response.status} ${response.statusText}`);
+		}
 		if (!response.ok) throw new Error(`Attachment upload failed: ${response.status} ${response.statusText}`);
 		return await response.json();
 	}
@@ -798,8 +1110,8 @@ var RemoteAttachmentUploadFactory = class {
 	constructor(config) {
 		this.config = config;
 	}
-	createUpload(reservationId, options) {
-		return new RemoteAttachmentUpload(reservationId, options, this.config);
+	createUpload(reservation) {
+		return new RemoteAttachmentUpload(reservation, this.config);
 	}
 };
 //#endregion
@@ -852,6 +1164,33 @@ function parseMetadata(response) {
 	} catch {}
 	return fallback();
 }
+function parsePendingExpiry(response) {
+	const header = response.headers.get("Attachment-Pending");
+	if (!header) return null;
+	try {
+		const parsed = JSON.parse(header);
+		if (!isRecord(parsed)) return null;
+		if (typeof parsed.expiresAtUtc !== "string") return null;
+		const result = { expiresAtUtc: parsed.expiresAtUtc };
+		if (typeof parsed.mimeType === "string") result.mimeType = parsed.mimeType;
+		if (typeof parsed.fileName === "string") result.fileName = parsed.fileName;
+		if (typeof parsed.sizeBytes === "number" && Number.isFinite(parsed.sizeBytes) && parsed.sizeBytes >= 0) result.sizeBytes = parsed.sizeBytes;
+		return result;
+	} catch {
+		return null;
+	}
+}
+function parsePendingHeader(response) {
+	const partial = parsePendingExpiry(response);
+	if (!partial) return null;
+	if (typeof partial.mimeType !== "string" || typeof partial.fileName !== "string" || partial.sizeBytes === void 0) return null;
+	return {
+		expiresAtUtc: partial.expiresAtUtc,
+		mimeType: partial.mimeType,
+		fileName: partial.fileName,
+		sizeBytes: partial.sizeBytes
+	};
+}
 var RemoteAttachmentStore = class {
 	remoteUrl;
 	jwtHandler;
@@ -861,6 +1200,13 @@ var RemoteAttachmentStore = class {
 		this.jwtHandler = config.jwtHandler;
 		this.fetchFn = (config.fetchFn ?? globalThis.fetch).bind(globalThis);
 	}
+	/**
+	* Get attachment metadata. Normally returns a pending AttachmentHeader
+	* (status: 'pending') when the server responds 202 with a full
+	* Attachment-Pending header. When only expiresAtUtc is present in the
+	* header (degraded wire), throws AttachmentPending instead -- the
+	* AttachmentPending throw is the degraded-wire case.
+	*/
 	async stat(hash) {
 		const url = `${this.remoteUrl}/attachments/${hash}`;
 		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
@@ -868,6 +1214,13 @@ var RemoteAttachmentStore = class {
 			method: "HEAD",
 			headers: authHeaders
 		});
+		if (response.status === 202) {
+			const fullPending = parsePendingHeader(response);
+			if (fullPending) return buildPendingHeader(hash, fullPending);
+			const partial = parsePendingExpiry(response);
+			if (partial) throw new AttachmentPending(hash, partial.expiresAtUtc);
+			throw new Error("Attachment stat returned 202 with missing or malformed Attachment-Pending header");
+		}
 		if (response.status === 404) throw new AttachmentNotFound(hash);
 		if (!response.ok) throw new Error(`Attachment stat failed: ${response.status} ${response.statusText}`);
 		return buildHeader(hash, parseMetadata(response));
@@ -882,6 +1235,11 @@ var RemoteAttachmentStore = class {
 			signal,
 			headers
 		});
+		if (response.status === 202) {
+			const pending = parsePendingExpiry(response);
+			if (!pending) throw new Error("Attachment fetch returned 202 with missing or malformed Attachment-Pending header");
+			throw new AttachmentPending(hash, pending.expiresAtUtc);
+		}
 		if (response.status === 404) throw new AttachmentNotFound(hash);
 		if (!response.ok) throw new Error(`Attachment fetch failed: ${response.status} ${response.statusText}`);
 		if (!response.body) throw new Error("Response body is null");
@@ -901,7 +1259,23 @@ function buildHeader(hash, metadata) {
 		status: "available",
 		source: "sync",
 		createdAtUtc: metadata.createdAtUtc,
-		lastAccessedAtUtc: metadata.lastAccessedAtUtc ?? metadata.createdAtUtc
+		lastAccessedAtUtc: metadata.lastAccessedAtUtc ?? metadata.createdAtUtc,
+		expiresAtUtc: null
+	};
+}
+function buildPendingHeader(hash, pending) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		hash,
+		mimeType: pending.mimeType,
+		fileName: pending.fileName,
+		sizeBytes: pending.sizeBytes,
+		extension: null,
+		status: "pending",
+		source: "sync",
+		createdAtUtc: now,
+		lastAccessedAtUtc: now,
+		expiresAtUtc: pending.expiresAtUtc
 	};
 }
 //#endregion
@@ -915,11 +1289,11 @@ function createRemoteAttachmentService(config) {
 //#region src/null-attachment-transport.ts
 /**
 * No-op transport for deployments without remote sync.
-* fetch() always returns null, announce() and push() are no-ops.
+* fetch() always returns not-found, announce() and push() are no-ops.
 */
 var NullAttachmentTransport = class {
 	fetch() {
-		return Promise.resolve(null);
+		return Promise.resolve({ kind: "not-found" });
 	}
 	announce() {
 		return Promise.resolve();
@@ -934,6 +1308,7 @@ var AttachmentBuilder = class {
 	transport = new NullAttachmentTransport();
 	customUploadFactory;
 	maxUploadBytes;
+	reservationSweepMs;
 	constructor(db, storagePath) {
 		this.db = db;
 		this.storagePath = storagePath;
@@ -950,6 +1325,18 @@ var AttachmentBuilder = class {
 		this.maxUploadBytes = maxBytes;
 		return this;
 	}
+	/**
+	* Configure a recurring sweep that deletes expired reservations.
+	* The sweep calls reservations.deleteExpired() on the given interval.
+	* When set, the built result's destroy() clears the timer.
+	* Without this option no sweep runs -- deleteExpired() is never called
+	* automatically. Call withReservationSweepMs in production to prevent
+	* expired reservation rows from accumulating indefinitely.
+	*/
+	withReservationSweepMs(intervalMs) {
+		this.reservationSweepMs = intervalMs;
+		return this;
+	}
 	async build() {
 		const result = await runAttachmentMigrations(this.db, ATTACHMENT_SCHEMA);
 		if (!result.success && result.error) throw result.error;
@@ -957,15 +1344,31 @@ var AttachmentBuilder = class {
 		const store = new KyselyAttachmentStore(scopedDb, this.transport, this.storagePath);
 		const reservations = new KyselyReservationStore(scopedDb);
 		const uploadFactory = this.customUploadFactory ?? new DirectAttachmentUploadFactory(scopedDb, this.storagePath, reservations, this.maxUploadBytes);
+		const service = new AttachmentService(store, reservations, uploadFactory);
+		let sweepTimer;
+		if (this.reservationSweepMs !== void 0) {
+			const intervalMs = this.reservationSweepMs;
+			sweepTimer = setInterval(() => {
+				reservations.deleteExpired().catch(() => {});
+			}, intervalMs);
+			if (typeof sweepTimer.unref === "function") sweepTimer.unref();
+		}
+		const destroy = () => {
+			if (sweepTimer !== void 0) {
+				clearInterval(sweepTimer);
+				sweepTimer = void 0;
+			}
+		};
 		return {
-			service: new AttachmentService(store, reservations, uploadFactory),
+			service,
 			store,
 			reservations,
-			uploadFactory
+			uploadFactory,
+			destroy
 		};
 	}
 };
 //#endregion
-export { ATTACHMENT_SCHEMA, AttachmentBuilder, AttachmentNotFound, AttachmentService, DirectAttachmentUpload, DirectAttachmentUploadFactory, InvalidAttachmentRef, KyselyAttachmentStore, KyselyReservationStore, NullAttachmentTransport, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, ReservationNotFound, SwitchboardAttachmentTransport, createRef, createRemoteAttachmentService, parseRef, runAttachmentMigrations };
+export { ATTACHMENT_SCHEMA, AttachmentAlreadyExists, AttachmentBuilder, AttachmentNotFound, AttachmentPending, AttachmentService, DEFAULT_RESERVATION_TTL_MS, DirectAttachmentUpload, DirectAttachmentUploadFactory, HashMismatch, InvalidAttachmentRef, KyselyAttachmentStore, KyselyReservationStore, NullAttachmentTransport, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, ReservationNotFound, SizeMismatch, SwitchboardAttachmentTransport, UploadTooLarge, createRef, createRemoteAttachmentService, parseRef, runAttachmentMigrations };
 
 //# sourceMappingURL=index.js.map