deepspace 0.19.5 → 0.21.0

package/dist/worker.js

@@ -351,6 +351,9 @@ var MSG = {
   CRON_PAUSE: "cron.pause",
   CRON_RESUME: "cron.resume",
   CRON_STATUS: "cron.status",
+  // Per-mutation receipt, sent only to the socket whose trigger/pause/
+  // resume carried a `requestId` — frames without one stay fire-and-forget.
+  CRON_ACK: "cron.ack",
   // ---- JobRoom ---------------------------------------------------------
   // Background-job queue with durable, alarm-driven execution. See
   // server/rooms/job-room.ts. Clients enqueue and subscribe to updates;
@@ -1063,9 +1066,9 @@ var clientBuild = {
   canvasUndo: () => ({ type: MSG.CANVAS_UNDO, payload: EMPTY }),
   canvasRedo: () => ({ type: MSG.CANVAS_REDO, payload: EMPTY }),
   // Cron
-  cronTrigger: (taskName) => ({ type: MSG.CRON_TRIGGER, payload: { taskName } }),
-  cronPause: (taskName) => ({ type: MSG.CRON_PAUSE, payload: { taskName } }),
-  cronResume: (taskName) => ({ type: MSG.CRON_RESUME, payload: { taskName } }),
+  cronTrigger: (taskName, requestId) => ({ type: MSG.CRON_TRIGGER, payload: { taskName, requestId } }),
+  cronPause: (taskName, requestId) => ({ type: MSG.CRON_PAUSE, payload: { taskName, requestId } }),
+  cronResume: (taskName, requestId) => ({ type: MSG.CRON_RESUME, payload: { taskName, requestId } }),
   // Jobs
   jobEnqueue: (requestId, type, payload, maxAttempts) => ({
     type: MSG.JOB_ENQUEUE,
@@ -1119,6 +1122,14 @@ var serverBuild = {
   cronTasks: (tasks) => ({ type: MSG.CRON_TASKS, payload: { tasks } }),
   cronHistory: (history) => ({ type: MSG.CRON_HISTORY, payload: { history } }),
   cronStatus: (tasks, recentHistory) => ({ type: MSG.CRON_STATUS, payload: { tasks, recentHistory } }),
+  cronAckSuccess: (requestId, taskName) => ({
+    type: MSG.CRON_ACK,
+    payload: { requestId, taskName, ok: true }
+  }),
+  cronAckFailure: (requestId, reason, error, taskName) => ({
+    type: MSG.CRON_ACK,
+    payload: { requestId, taskName, ok: false, reason, error }
+  }),
   // Jobs
   jobSnapshot: (jobs) => ({ type: MSG.JOB_UPDATE, payload: { kind: "snapshot", jobs } }),
   jobEnqueued: (job, requestId) => ({
@@ -3992,40 +4003,88 @@ var CronRoom = class extends BaseRoom {
   }
   async onMessage(ws, user, message) {
     this.ensureInitialized();
-    const { type, payload } = message;
+    const { type, payload = {} } = message;
     if (CRON_WRITE_TYPES.has(type) && !user.canWrite) {
-      this.sendTo(ws, {
-        type: MSG.ERROR,
-        payload: { error: "Write access denied: viewer role cannot modify cron tasks" }
+      const error = "Write access denied: viewer role cannot modify cron tasks";
+      this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+      this.ackMutation(ws, payload.requestId, {
+        ok: false,
+        taskName: payload.taskName,
+        reason: "read_only",
+        error
       });
       return;
     }
+    try {
+      await this.dispatchMessage(ws, type, payload);
+    } catch (error) {
+      try {
+        this.ackMutation(ws, payload.requestId, {
+          ok: false,
+          taskName: payload.taskName,
+          reason: "failed",
+          error: error instanceof Error ? error.message : String(error)
+        });
+      } catch {
+      }
+      throw error;
+    }
+  }
+  async dispatchMessage(ws, type, payload) {
     switch (type) {
       case MSG.CRON_TRIGGER: {
         const taskName = payload.taskName;
         if (!taskName) {
-          this.sendTo(ws, { type: MSG.ERROR, payload: { error: "Missing taskName" } });
+          const error = "Missing taskName";
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, { ok: false, reason: "failed", error });
           return;
         }
-        if (!await this.executeTask(taskName)) {
-          this.sendTo(ws, {
-            type: MSG.ERROR,
-            payload: { error: `Unknown cron task: ${taskName}` }
+        const execution = await this.executeTask(taskName);
+        if (!execution) {
+          const error = `Unknown cron task: ${taskName}`;
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, {
+            ok: false,
+            taskName,
+            reason: "unknown_task",
+            error
           });
+          break;
         }
+        this.ackMutation(
+          ws,
+          payload.requestId,
+          execution.success ? { ok: true, taskName } : { ok: false, taskName, reason: "failed", error: execution.error }
+        );
         break;
       }
-      case MSG.CRON_PAUSE: {
-        const taskName = payload.taskName;
-        this.sql.exec(`UPDATE cron_tasks SET paused = 1 WHERE name = ?`, taskName);
-        this.broadcastStatus();
-        break;
-      }
+      case MSG.CRON_PAUSE:
       case MSG.CRON_RESUME: {
         const taskName = payload.taskName;
-        this.sql.exec(`UPDATE cron_tasks SET paused = 0 WHERE name = ?`, taskName);
-        this.scheduleNextAlarm();
+        if (!taskName) {
+          const error = "Missing taskName";
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, { ok: false, reason: "failed", error });
+          return;
+        }
+        const known = this.sql.exec(`SELECT name FROM cron_tasks WHERE name = ?`, taskName).toArray().length > 0;
+        if (!known) {
+          const error = `Unknown cron task: ${taskName}`;
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, {
+            ok: false,
+            taskName,
+            reason: "unknown_task",
+            error
+          });
+          break;
+        }
+        const paused = type === MSG.CRON_PAUSE;
+        this.sql.exec(`UPDATE cron_tasks SET paused = ? WHERE name = ?`, paused ? 1 : 0, taskName);
+        if (!paused) this.scheduleNextAlarm();
         this.broadcastStatus();
+        this.ackMutation(ws, payload.requestId, { ok: true, taskName });
         break;
       }
       case MSG.CRON_TASKS: {
@@ -4068,7 +4127,7 @@ var CronRoom = class extends BaseRoom {
   // ==========================================================================
   async executeTask(taskName) {
     const taskRow = this.sql.exec(`SELECT interval_minutes, schedule, timezone FROM cron_tasks WHERE name = ?`, taskName).toArray()[0];
-    if (!taskRow) return false;
+    if (!taskRow) return null;
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const start = Date.now();
     let success = true;
@@ -4104,7 +4163,7 @@ var CronRoom = class extends BaseRoom {
       `DELETE FROM cron_history WHERE id NOT IN (SELECT id FROM cron_history ORDER BY id DESC LIMIT 500)`
     );
     this.broadcastStatus();
-    return true;
+    return { taskName, startedAt, completedAt, success, durationMs, error };
   }
   // ==========================================================================
   // Scheduling
@@ -4174,6 +4233,21 @@ var CronRoom = class extends BaseRoom {
       }
     });
   }
+  /**
+   * Receipt for a mutation frame, addressed only to its sender. Receipts
+   * are opt-in by correlation id: frames without a `requestId` keep the
+   * fire-and-forget contract, so the (untyped) `requestId` from the wire
+   * is the single gate here rather than a check at every call site.
+   * Frames go through the shared `serverBuild` constructors so the wire
+   * shape is enforced by the protocol types, not re-spelled here.
+   */
+  ackMutation(ws, requestId, result) {
+    if (typeof requestId !== "string") return;
+    this.sendTo(
+      ws,
+      result.ok ? serverBuild.cronAckSuccess(requestId, result.taskName) : serverBuild.cronAckFailure(requestId, result.reason, result.error, result.taskName)
+    );
+  }
 };
 function computeNextRunAt(task, from) {
   if (task.interval_minutes) {
@@ -6093,9 +6167,6 @@ var DANGEROUS_MIME_TYPES = /* @__PURE__ */ new Set([
   "application/ecmascript",
   "text/ecmascript"
 ]);
-function activeContentMessage(mimeType) {
-  return `${mimeType} is not accepted: the files API serves your app's own origin, so stored HTML/SVG/JavaScript would execute there with your users' sessions. Ship it as a build asset under \`public/\` instead, where it is served as part of your app rather than as user-uploaded content.`;
-}
 function formatBytes(bytes) {
   if (bytes >= 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GiB`;
   if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
@@ -6115,21 +6186,479 @@ function oversizePartMessage(bytes) {
   return `This part carries ${formatBytes(bytes)}; a part may carry ${formatBytes(UPLOAD_PART_BYTES)} \u2014 the size the upload advertised.`;
 }
 
-// src/server/utils/scoped-r2-files.ts
+// src/server/utils/r2-storage-quota.ts
 var CORS_HEADERS3 = { "Access-Control-Allow-Origin": "*" };
+var QUOTA_SUMMARY_VERSION = 1;
+var MAX_QUOTA_SCAN_OBJECTS = 5e5;
+var MAX_QUOTA_SCAN_LISTS = 900;
+var QUOTA_REPAIR_COOLDOWN_MS = 6e4;
+var PENDING_MARKER_MAX_AGE_MS = 60 * 6e4;
+var EMPTY_MULTIPART_MARKER_MAX_AGE_MS = 60 * 6e4;
+var ACTIVE_MULTIPART_MARKER_MAX_AGE_MS = 8 * 24 * 60 * 6e4;
 function fail(status, error, code, extra) {
   return Response.json(
     { error, ...code ? { code } : {}, ...extra },
     { status, headers: CORS_HEADERS3 }
   );
 }
-function contentDisposition(originalName) {
+function quotaUnavailable(message) {
+  return fail(503, message, "storage_limit_unavailable");
+}
+function quotaKeySegment(value) {
+  return encodeURIComponent(value);
+}
+function markerPrefix(storage, kind) {
+  return `__deepspace/quota/${kind}/${quotaKeySegment(storage.quotaKey)}/`;
+}
+function pendingMarkerPrefix(storage) {
+  return markerPrefix(storage, "pending");
+}
+function multipartMarkerPrefix(storage) {
+  return markerPrefix(storage, "multipart");
+}
+function multipartMarkerKey(storage, reservationId) {
+  return `${multipartMarkerPrefix(storage)}${quotaKeySegment(reservationId)}`;
+}
+function accountPrefixesEqual(left, right) {
+  return left.length === right.length && left.every((prefix, index) => prefix === right[index]);
+}
+async function allocationPrefixes(storage) {
+  const siblings = storage.siblingPrefixes ? await storage.siblingPrefixes() : [];
+  if (siblings === null) return null;
+  return [.../* @__PURE__ */ new Set([storage.prefix, ...siblings])].sort();
+}
+function countScan(budget, count) {
+  budget.lists++;
+  budget.objects += count;
+  if (budget.lists > MAX_QUOTA_SCAN_LISTS || budget.objects > MAX_QUOTA_SCAN_OBJECTS) {
+    throw new Error("quota scan work limit exceeded");
+  }
+}
+async function prefixUsage(bucket, prefix, budget) {
+  let total = 0;
+  let cursor;
+  do {
+    const page = await bucket.list({ prefix, cursor, limit: 1e3 });
+    countScan(budget, page.objects.length);
+    for (const object of page.objects) total += object.size;
+    cursor = page.truncated ? page.cursor : void 0;
+  } while (cursor !== void 0);
+  return total;
+}
+function markerBytes(object) {
+  const raw = object.customMetadata?.reservedBytes;
+  const bytes = raw === void 0 ? NaN : Number(raw);
+  if (!Number.isSafeInteger(bytes) || bytes < 0) throw new Error("invalid quota marker");
+  return bytes;
+}
+function markerMaxAge(object, fallback) {
+  if (object.customMetadata?.quotaKind !== "multipart") return fallback;
+  return object.customMetadata.active === "true" ? ACTIVE_MULTIPART_MARKER_MAX_AGE_MS : EMPTY_MULTIPART_MARKER_MAX_AGE_MS;
+}
+async function markerUsage(bucket, prefix, maxAgeMs, budget, excludedKey) {
+  let total = 0;
+  let cursor;
+  const now = Date.now();
+  do {
+    const options = {
+      prefix,
+      cursor,
+      limit: 1e3,
+      include: ["customMetadata"]
+    };
+    const page = await bucket.list(options);
+    countScan(budget, page.objects.length);
+    for (const object of page.objects) {
+      if (now - object.uploaded.getTime() > markerMaxAge(object, maxAgeMs)) {
+        if (budget.staleKeys.length < 1e3) budget.staleKeys.push(object.key);
+      } else if (object.key !== excludedKey) {
+        total += markerBytes(object);
+      }
+    }
+    cursor = page.truncated ? page.cursor : void 0;
+  } while (cursor !== void 0);
+  return total;
+}
+async function measuredAllocationUsage(bucket, storage, prefixes, excludedMarkerKey) {
+  const budget = { lists: 0, objects: 0, staleKeys: [] };
+  let total = 0;
+  for (const prefix of prefixes) total += await prefixUsage(bucket, prefix, budget);
+  total += await markerUsage(
+    bucket,
+    pendingMarkerPrefix(storage),
+    PENDING_MARKER_MAX_AGE_MS,
+    budget,
+    excludedMarkerKey
+  );
+  total += await markerUsage(
+    bucket,
+    multipartMarkerPrefix(storage),
+    ACTIVE_MULTIPART_MARKER_MAX_AGE_MS,
+    budget,
+    excludedMarkerKey
+  );
+  if (budget.staleKeys.length > 0) {
+    await bucket.delete(budget.staleKeys).catch((error) => {
+      console.error("[files:quota] stale marker cleanup:", error);
+    });
+  }
+  return total;
+}
+function isQuotaSummary(value) {
+  if (!value || typeof value !== "object") return false;
+  const summary = value;
+  return summary.version === QUOTA_SUMMARY_VERSION && Array.isArray(summary.prefixes) && summary.prefixes.every((prefix) => typeof prefix === "string") && Number.isSafeInteger(summary.usedBytes) && (summary.usedBytes ?? -1) >= 0 && Number.isSafeInteger(summary.measuredAt) && (summary.measuredAt ?? -1) >= 0 && typeof summary.dirty === "boolean";
+}
+async function readQuotaSummary(bucket, key) {
+  const object = await bucket.get(key);
+  if (!object) return { etag: null, summary: null };
+  try {
+    const parsed = await object.json();
+    return { etag: object.etag, summary: isQuotaSummary(parsed) ? parsed : null };
+  } catch {
+    return { etag: object.etag, summary: null };
+  }
+}
+async function writeQuotaSummary(bucket, key, previousEtag, summary) {
+  const onlyIf = previousEtag ? { etagMatches: previousEtag } : new Headers({ "If-None-Match": "*" });
+  const object = await bucket.put(key, JSON.stringify(summary), {
+    onlyIf,
+    httpMetadata: { contentType: "application/json" }
+  });
+  return object ? { etag: object.etag, summary } : null;
+}
+async function ensureQuotaSummary(bucket, storage, prefixes, forceMeasure = false, excludedMarkerKey) {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    const current = await readQuotaSummary(bucket, storage.quotaKey);
+    if (!forceMeasure && current.summary && accountPrefixesEqual(current.summary.prefixes, prefixes)) {
+      return current;
+    }
+    const usedBytes = await measuredAllocationUsage(bucket, storage, prefixes, excludedMarkerKey);
+    const repaired = await writeQuotaSummary(bucket, storage.quotaKey, current.etag, {
+      version: QUOTA_SUMMARY_VERSION,
+      prefixes,
+      usedBytes,
+      measuredAt: Date.now(),
+      dirty: false
+    });
+    if (repaired) return repaired;
+  }
+  return null;
+}
+async function markQuotaDirty(bucket, storage) {
+  if (!storage) return;
+  try {
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const current = await readQuotaSummary(bucket, storage.quotaKey);
+      if (!current.summary || current.summary.dirty) return;
+      const written = await writeQuotaSummary(bucket, storage.quotaKey, current.etag, {
+        ...current.summary,
+        dirty: true
+      });
+      if (written) return;
+    }
+    console.error("[files:quota] could not mark summary reclaimable after concurrent writes");
+  } catch (error) {
+    console.error("[files:quota] could not mark summary reclaimable:", error);
+  }
+}
+async function neutralizeMarker(bucket, markerKey) {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    const marker = await bucket.get(markerKey);
+    if (!marker) return true;
+    if (markerBytes(marker) === 0) return true;
+    const body = await marker.arrayBuffer();
+    const object = await bucket.put(markerKey, body, {
+      onlyIf: { etagMatches: marker.etag },
+      customMetadata: {
+        ...marker.customMetadata,
+        reservedBytes: "0",
+        releasedAt: String(Date.now())
+      }
+    });
+    if (object) return true;
+  }
+  return false;
+}
+async function releaseQuotaMarker(bucket, storage, markerKey, summaryMayBeStale) {
+  try {
+    if (markerKey && !await neutralizeMarker(bucket, markerKey)) {
+      console.error("[files:quota] could not neutralize reservation marker");
+      return false;
+    }
+    if (summaryMayBeStale) await markQuotaDirty(bucket, storage);
+    if (markerKey) {
+      for (let attempt = 0; attempt < 4; attempt++) {
+        try {
+          await bucket.delete(markerKey);
+          break;
+        } catch (error) {
+          if (attempt === 3) throw error;
+        }
+      }
+    }
+    return true;
+  } catch (error) {
+    console.error("[files:quota] reservation cleanup:", error);
+    return false;
+  }
+}
+function parseMultipartMarker(value) {
+  if (!value || typeof value !== "object") return null;
+  const marker = value;
+  if (marker.version !== 1 || typeof marker.reservationId !== "string" || !marker.reservationId || typeof marker.uploadId !== "string" || !marker.uploadId || typeof marker.objectKey !== "string" || !marker.objectKey || typeof marker.uploadKey !== "string" || !marker.uploadKey || typeof marker.admitted !== "boolean" || !Number.isSafeInteger(marker.declaredBytes) || (marker.declaredBytes ?? -1) < 0) {
+    return null;
+  }
+  return marker;
+}
+function multipartMarkerBody(reservation) {
+  return JSON.stringify({
+    version: 1,
+    reservationId: reservation.reservationId,
+    uploadId: reservation.uploadId,
+    objectKey: reservation.objectKey,
+    uploadKey: reservation.uploadKey,
+    admitted: reservation.admitted,
+    declaredBytes: reservation.declaredBytes
+  });
+}
+async function readMultipartReservation(bucket, storage, reservationId) {
+  if (!storage) return null;
+  const key = multipartMarkerKey(storage, reservationId);
+  let object;
+  try {
+    object = await bucket.get(key);
+  } catch (error) {
+    console.error("[files:quota] reservation read:", error);
+    return "invalid";
+  }
+  if (!object) return null;
+  let marker = null;
+  try {
+    marker = parseMultipartMarker(await object.json());
+  } catch {
+    return "invalid";
+  }
+  if (!marker || marker.reservationId !== reservationId) return "invalid";
+  let reservedBytes;
+  try {
+    reservedBytes = markerBytes(object);
+  } catch {
+    return "invalid";
+  }
+  return {
+    key,
+    etag: object.etag,
+    reservationId,
+    uploadId: marker.uploadId,
+    objectKey: marker.objectKey,
+    uploadKey: marker.uploadKey,
+    admitted: marker.admitted,
+    declaredBytes: marker.declaredBytes,
+    reservedBytes
+  };
+}
+async function refreshMultipartReservation(bucket, storage, reservationId, uploadId, objectKey) {
+  if (!storage) return null;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    const reservation = await readMultipartReservation(bucket, storage, reservationId);
+    if (reservation === null || reservation === "invalid") return reservation ?? "invalid";
+    if (!reservation.admitted || reservation.uploadId !== uploadId || reservation.objectKey !== objectKey) {
+      return "invalid";
+    }
+    const object = await bucket.put(reservation.key, multipartMarkerBody(reservation), {
+      onlyIf: { etagMatches: reservation.etag },
+      customMetadata: {
+        quotaKind: "multipart",
+        reservedBytes: String(reservation.reservedBytes),
+        active: "true"
+      }
+    });
+    if (object) return { ...reservation, etag: object.etag };
+  }
+  return "busy";
+}
+async function activateMultipartReservation(bucket, storage, reservationId) {
+  if (!storage) return null;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    const reservation = await readMultipartReservation(bucket, storage, reservationId);
+    if (!reservation || reservation === "invalid") return null;
+    if (reservation.admitted) return reservation;
+    const next = { ...reservation, admitted: true };
+    const object = await bucket.put(reservation.key, multipartMarkerBody(next), {
+      onlyIf: { etagMatches: reservation.etag },
+      customMetadata: {
+        quotaKind: "multipart",
+        reservedBytes: String(reservation.reservedBytes),
+        active: "false"
+      }
+    });
+    if (object) {
+      return { ...next, etag: object.etag };
+    }
+  }
+  return null;
+}
+function quotaExceeded(incomingBytes, summaryBytes, replacedBytes, limitBytes) {
+  const usedBytes = Math.max(0, summaryBytes - replacedBytes);
+  return fail(
+    409,
+    storageQuotaMessage(incomingBytes, usedBytes, limitBytes),
+    "storage_quota_exceeded",
+    { usedBytes, limitBytes }
+  );
+}
+async function reserveQuotaSummary(bucket, storage, prefixes, initial, chargeBytes, incomingBytes, replacedBytes, limitBytes, markerKey) {
+  if (chargeBytes === 0) return null;
+  let current = initial;
+  let repaired = false;
+  for (let attempt = 0; attempt < 8; attempt++) {
+    if (!current.summary || !accountPrefixesEqual(current.summary.prefixes, prefixes)) {
+      const ensured = await ensureQuotaSummary(
+        bucket,
+        storage,
+        prefixes,
+        false,
+        markerKey ?? void 0
+      );
+      if (!ensured) {
+        return quotaUnavailable(
+          "The storage used by this account could not be verified. Retry shortly."
+        );
+      }
+      current = ensured;
+    }
+    const summary = current.summary;
+    if (!summary) {
+      return quotaUnavailable(
+        "The storage used by this account could not be verified. Retry shortly."
+      );
+    }
+    if (summary.usedBytes + chargeBytes > limitBytes) {
+      const recentlyMeasured = Date.now() - summary.measuredAt < QUOTA_REPAIR_COOLDOWN_MS;
+      if (repaired || !summary.dirty && recentlyMeasured) {
+        return quotaExceeded(incomingBytes, summary.usedBytes, replacedBytes, limitBytes);
+      }
+      const refreshed = await ensureQuotaSummary(
+        bucket,
+        storage,
+        prefixes,
+        true,
+        markerKey ?? void 0
+      );
+      if (!refreshed?.summary) {
+        return quotaUnavailable(
+          "The storage used by this account could not be verified. Retry shortly."
+        );
+      }
+      current = refreshed;
+      repaired = true;
+      continue;
+    }
+    const written = await writeQuotaSummary(bucket, storage.quotaKey, current.etag, {
+      ...summary,
+      usedBytes: summary.usedBytes + chargeBytes
+    });
+    if (written) return null;
+    current = await readQuotaSummary(bucket, storage.quotaKey);
+  }
+  return quotaUnavailable("Storage is busy with other uploads. Retry shortly.");
+}
+async function admitStorage(bucket, storage, incomingBytes, replacedBytes, marker) {
+  if (!storage) return { markerKey: null };
+  let markerKey = null;
+  try {
+    const limit = await storage.limitBytes();
+    if (limit === null) {
+      return quotaUnavailable(
+        "The storage limit for this app could not be verified; nothing was uploaded. Retry shortly."
+      );
+    }
+    const prefixes = await allocationPrefixes(storage);
+    if (prefixes === null) {
+      return quotaUnavailable(
+        "The apps in this storage allocation could not be enumerated; nothing was uploaded. Retry shortly."
+      );
+    }
+    const initial = await ensureQuotaSummary(bucket, storage, prefixes);
+    if (!initial) {
+      return quotaUnavailable(
+        "The storage already used by this account could not be measured; nothing was uploaded. Retry shortly."
+      );
+    }
+    const chargeBytes = Math.max(0, incomingBytes - replacedBytes);
+    const effectiveMarker = marker ?? (chargeBytes > 0 ? {
+      key: `${pendingMarkerPrefix(storage)}${crypto.randomUUID()}`,
+      metadata: { quotaKind: "pending" }
+    } : null);
+    if (effectiveMarker) {
+      const object = await bucket.put(effectiveMarker.key, effectiveMarker.body ?? "", {
+        onlyIf: new Headers({ "If-None-Match": "*" }),
+        customMetadata: {
+          ...effectiveMarker.metadata,
+          reservedBytes: String(chargeBytes)
+        }
+      });
+      if (!object) {
+        return fail(
+          409,
+          "An upload with this request id is already in progress.",
+          "reservation_conflict"
+        );
+      }
+      markerKey = effectiveMarker.key;
+    }
+    const refusal = await reserveQuotaSummary(
+      bucket,
+      storage,
+      prefixes,
+      initial,
+      chargeBytes,
+      incomingBytes,
+      replacedBytes,
+      limit,
+      effectiveMarker?.key ?? null
+    );
+    if (refusal) {
+      await releaseQuotaMarker(bucket, storage, effectiveMarker?.key ?? null, false);
+      return refusal;
+    }
+    return { markerKey: effectiveMarker?.key ?? null };
+  } catch (error) {
+    console.error("[files:quota] admission:", error);
+    await releaseQuotaMarker(bucket, storage, markerKey, true);
+    return quotaUnavailable(
+      "The storage used by this account could not be verified. Retry shortly."
+    );
+  }
+}
+async function storageUsage(bucket, storage) {
+  try {
+    const prefixes = await allocationPrefixes(storage);
+    if (prefixes === null) return null;
+    const current = await ensureQuotaSummary(bucket, storage, prefixes);
+    return current?.summary?.usedBytes ?? null;
+  } catch (error) {
+    console.error("[files:quota] usage:", error);
+    return null;
+  }
+}
+
+// src/server/utils/scoped-r2-files.ts
+var CORS_HEADERS4 = { "Access-Control-Allow-Origin": "*" };
+function fail2(status, error, code, extra) {
+  return Response.json(
+    { error, ...code ? { code } : {}, ...extra },
+    { status, headers: CORS_HEADERS4 }
+  );
+}
+function contentDisposition(originalName, disposition) {
   const safe = originalName.replace(/[^\x20-\x7e]|["\\]/g, "_") || "download";
   const encoded = encodeURIComponent(originalName).replace(
     /[!'()*]/g,
     (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`
   );
-  return `inline; filename="${safe}"; filename*=UTF-8''${encoded}`;
+  return `${disposition}; filename="${safe}"; filename*=UTF-8''${encoded}`;
 }
 function sanitizeSubpath(raw) {
   if (!raw) return "";
@@ -6139,24 +6668,24 @@ function sanitizeSubpath(raw) {
 }
 function overRequestBound(bytes, slack = 0) {
   if (bytes <= MAX_UPLOAD_REQUEST_BYTES + slack) return null;
-  return fail(413, oversizeRequestMessage(bytes), "too_large", {
+  return fail2(413, oversizeRequestMessage(bytes), "too_large", {
     maxBytes: MAX_UPLOAD_REQUEST_BYTES,
     partSize: UPLOAD_PART_BYTES
   });
 }
 function overCeiling(bytes) {
   if (bytes <= MAX_APP_FILE_BYTES) return null;
-  return fail(413, oversizeMessage(bytes), "too_large", { maxBytes: MAX_APP_FILE_BYTES });
+  return fail2(413, oversizeMessage(bytes), "too_large", { maxBytes: MAX_APP_FILE_BYTES });
 }
 function overPartBound(bytes) {
   if (bytes <= UPLOAD_PART_BYTES) return null;
-  return fail(413, oversizePartMessage(bytes), "too_large", { maxBytes: UPLOAD_PART_BYTES });
+  return fail2(413, oversizePartMessage(bytes), "too_large", { maxBytes: UPLOAD_PART_BYTES });
 }
 function declaredLength(request, what) {
   const raw = request.headers.get("content-length");
   const declared = raw === null ? NaN : Number(raw);
   if (!Number.isSafeInteger(declared) || declared < 0) {
-    return fail(
+    return fail2(
       411,
       `${what} must declare a Content-Length. A chunked or length-less body is refused: R2 cannot size a write it has no length for.`,
       "length_required"
@@ -6164,78 +6693,18 @@ function declaredLength(request, what) {
   }
   return declared;
 }
-function isKeyWithinPrefix(key, prefix) {
-  return key.startsWith(prefix);
+function isKeyWithinScope(key, prefix, excludedPrefixes) {
+  return key.startsWith(prefix) && !excludedPrefixes.some((excluded) => key.startsWith(excluded));
 }
-async function prefixUsage(bucket, prefix) {
-  let total = 0;
-  let cursor;
-  do {
-    const page = await bucket.list({ prefix, cursor, limit: 1e3 });
-    for (const object of page.objects) total += object.size;
-    cursor = page.truncated ? page.cursor : void 0;
-  } while (cursor !== void 0);
-  return total;
-}
-async function allocationUsage(bucket, storage) {
-  const siblings = storage.siblingPrefixes ? await storage.siblingPrefixes() : [];
-  if (siblings === null) return null;
-  const prefixes = [storage.prefix, ...siblings.filter((p) => p !== storage.prefix)];
-  const totals = await Promise.all(prefixes.map((prefix) => prefixUsage(bucket, prefix)));
-  return totals.reduce((sum, bytes) => sum + bytes, 0);
+function scopeRelativeKey(key, prefix) {
+  return key.slice(prefix.length);
 }
-async function admitStorage(bucket, storage, incomingBytes, replacesKey) {
-  if (!storage) return null;
-  const limit = await storage.limitBytes();
-  if (limit === null) {
-    return fail(
-      503,
-      "The storage limit for this app could not be verified; nothing was uploaded. Retry shortly.",
-      "storage_limit_unavailable"
-    );
-  }
-  const stored = await allocationUsage(bucket, storage);
-  if (stored === null) {
-    return fail(
-      503,
-      "The storage already used by this account could not be measured; nothing was uploaded. Retry shortly.",
-      "storage_limit_unavailable"
-    );
-  }
-  const replaced = replacesKey === null ? 0 : (await bucket.head(replacesKey))?.size ?? 0;
-  const used = stored - replaced;
-  if (used + incomingBytes <= limit) return null;
-  return fail(409, storageQuotaMessage(incomingBytes, used, limit), "storage_quota_exceeded", {
-    usedBytes: used,
-    limitBytes: limit
-  });
-}
-async function admitAssembledObject(bucket, storage, key, objectBytes) {
-  if (!storage) return null;
-  const limit = await storage.limitBytes();
-  if (limit === null) {
-    console.error("[files:quota] limit unavailable at complete; keeping", key);
-    return null;
-  }
-  const stored = await allocationUsage(bucket, storage);
-  if (stored === null) {
-    console.error("[files:quota] account usage unmeasurable at complete; keeping", key);
-    return null;
-  }
-  if (stored <= limit) return null;
-  await bucket.delete(key).catch(() => void 0);
-  return fail(
-    409,
-    `${storageQuotaMessage(objectBytes, stored - objectBytes, limit)} The assembled upload was not kept.`,
-    "storage_quota_exceeded",
-    { usedBytes: stored - objectBytes, limitBytes: limit }
-  );
-}
-function anchorKey(raw, prefix) {
+function anchorKey(raw, prefix, excludedPrefixes) {
   const safe = sanitizeSubpath(raw);
-  if (safe === null) return fail(400, "Invalid key: traversal not allowed", "invalid_key");
-  if (!safe) return fail(400, "Invalid key: empty", "invalid_key");
-  return { key: `${prefix}${safe}` };
+  if (safe === null) return fail2(400, "Invalid key: traversal not allowed", "invalid_key");
+  if (!safe) return fail2(400, "Invalid key: empty", "invalid_key");
+  const key = `${prefix}${safe}`;
+  return isKeyWithinScope(key, prefix, excludedPrefixes) ? { key } : fail2(403, "Access denied: key belongs to a private scope", "forbidden");
 }
 var VERB_ROUTES = /* @__PURE__ */ new Set([
   "POST upload",
@@ -6249,7 +6718,7 @@ function isFilesVerbPath(method, subpath) {
 }
 function resolveMimeType(raw) {
   const mimeType = raw.split(";")[0].trim().toLowerCase() || "application/octet-stream";
-  return DANGEROUS_MIME_TYPES.has(mimeType) ? fail(415, activeContentMessage(mimeType), "active_content") : { mimeType };
+  return mimeType;
 }
 function r2ErrorCode(error) {
   const message = error instanceof Error ? error.message : String(error);
@@ -6259,7 +6728,7 @@ function r2ErrorCode(error) {
 function multipartFailure(error) {
   switch (r2ErrorCode(error)) {
     case 10024:
-      return fail(
+      return fail2(
         404,
         "That upload does not exist \u2014 it was completed, abandoned, or expired. Start a new one.",
         "unknown_upload"
@@ -6269,7 +6738,7 @@ function multipartFailure(error) {
     case 10025:
     // InvalidPart — a named part was never uploaded
     case 10048:
-      return fail(
+      return fail2(
         400,
         "The parts do not assemble: every part except the last must be exactly the size the upload advertised, and each must be uploaded before it is named.",
         "bad_parts"
@@ -6277,11 +6746,15 @@ function multipartFailure(error) {
     case 10012:
     // MetadataTooLarge
     case 10020:
-      return fail(400, "The upload names a key or metadata R2 will not accept.", "invalid_key");
+      return fail2(400, "The upload names a key or metadata R2 will not accept.", "invalid_key");
     default: {
       const message = error instanceof Error ? error.message : String(error);
       console.error("[files:multipart] R2 error:", message);
-      return fail(503, "The files service could not complete that upload. Retry shortly.", "r2_error");
+      return fail2(
+        503,
+        "The files service could not complete that upload. Retry shortly.",
+        "r2_error"
+      );
     }
   }
 }
@@ -6294,73 +6767,79 @@ function createScopedR2Handler(config) {
     } catch {
       return Response.json(
         { error: "Invalid path encoding" },
-        { status: 400, headers: CORS_HEADERS3 }
+        { status: 400, headers: CORS_HEADERS4 }
       );
     }
     const subpath = sanitizeSubpath(subpathRaw);
     if (subpath === null) {
       return Response.json(
         { error: "Invalid path: traversal not allowed" },
-        { status: 400, headers: CORS_HEADERS3 }
+        { status: 400, headers: CORS_HEADERS4 }
       );
     }
     const scope = url.searchParams.get("scope") || "self";
     if (scope !== "self" && scope !== "app") {
-      return Response.json({ error: "Invalid scope" }, { status: 400, headers: CORS_HEADERS3 });
+      return Response.json({ error: "Invalid scope" }, { status: 400, headers: CORS_HEADERS4 });
     }
     const result = config.resolvePrefix(scope, { userId: auth.userId, url });
     if (!result.prefix) {
       const errorMsg = result.error ?? "Invalid scope";
       const status = errorMsg.toLowerCase().includes("auth") ? 401 : 400;
-      return Response.json({ error: errorMsg }, { status, headers: CORS_HEADERS3 });
+      return Response.json({ error: errorMsg }, { status, headers: CORS_HEADERS4 });
     }
     const prefix = result.prefix;
+    const excludedPrefixes = result.excludedPrefixes ?? [];
     if (isFilesVerbPath(request.method, subpath)) {
       if (requireAuthForMutations && !auth.userId) {
         await request.body?.cancel().catch(() => void 0);
-        return fail(401, "Authentication required", "unauthorized");
+        return fail2(401, "Authentication required", "unauthorized");
       }
-      return subpath === "upload" ? handleUpload(request, url, bucket, prefix, auth, scope) : handleMultipart(request, url, bucket, prefix, auth, scope, subpath);
+      return subpath === "upload" ? handleUpload(request, url, bucket, prefix, excludedPrefixes, auth, scope) : handleMultipart(request, url, bucket, prefix, excludedPrefixes, auth, scope, subpath);
     }
     if (!subpath && request.method === "GET") {
-      return handleList(bucket, prefix, url, scope, auth);
+      return handleList(bucket, prefix, excludedPrefixes, url, scope, auth);
     }
     if (subpath && request.method === "GET") {
-      if (!isKeyWithinPrefix(subpath, prefix)) {
+      if (!isKeyWithinScope(subpath, prefix, excludedPrefixes)) {
         return Response.json(
           { error: "Access denied: key outside scope" },
-          { status: 403, headers: CORS_HEADERS3 }
+          { status: 403, headers: CORS_HEADERS4 }
         );
       }
-      return handleDownload(bucket, subpath, scope);
+      return handleDownload(request, bucket, subpath, scope);
     }
     if (subpath && request.method === "DELETE") {
       if (requireAuthForMutations && !auth.userId) {
         return Response.json(
           { error: "Authentication required" },
-          { status: 401, headers: CORS_HEADERS3 }
+          { status: 401, headers: CORS_HEADERS4 }
         );
       }
-      if (!isKeyWithinPrefix(subpath, prefix)) {
+      if (!isKeyWithinScope(subpath, prefix, excludedPrefixes)) {
         return Response.json(
           { error: "Access denied: key outside scope" },
-          { status: 403, headers: CORS_HEADERS3 }
+          { status: 403, headers: CORS_HEADERS4 }
         );
       }
       const existed = await bucket.head(subpath) !== null;
-      if (existed) await bucket.delete(subpath);
+      if (existed) {
+        await bucket.delete(subpath);
+        await markQuotaDirty(bucket, auth.storage);
+      }
       return Response.json(
         { success: true, deleted: existed ? subpath : null, existed },
-        { headers: CORS_HEADERS3 }
+        { headers: CORS_HEADERS4 }
       );
     }
-    return Response.json({ error: "Method not allowed" }, { status: 405, headers: CORS_HEADERS3 });
+    return Response.json({ error: "Method not allowed" }, { status: 405, headers: CORS_HEADERS4 });
   };
 }
-async function handleUpload(request, url, bucket, prefix, auth, scope) {
+async function handleUpload(request, url, bucket, prefix, excludedPrefixes, auth, scope) {
   try {
-    const declared = overRequestBound(Number(request.headers.get("content-length")), 8 * 1024);
-    if (declared) return declared;
+    const declaredBytes = declaredLength(request, "File uploads");
+    if (declaredBytes instanceof Response) return declaredBytes;
+    const tooLargeRequest = overRequestBound(declaredBytes, 8 * 1024);
+    if (tooLargeRequest) return tooLargeRequest;
     const contentType = request.headers.get("content-type") || "";
     let fileData;
     let fileName;
@@ -6368,7 +6847,7 @@ async function handleUpload(request, url, bucket, prefix, auth, scope) {
     if (contentType.includes("multipart/form-data")) {
       const formData = await request.formData();
       const file = formData.get("file");
-      if (!file) return fail(400, "No file provided", "bad_request");
+      if (!file) return fail2(400, "No file provided", "bad_request");
       const tooBig = overRequestBound(file.size);
       if (tooBig) return tooBig;
       fileData = await file.arrayBuffer();
@@ -6376,7 +6855,7 @@ async function handleUpload(request, url, bucket, prefix, auth, scope) {
       rawMimeType = file.type || "application/octet-stream";
     } else {
       const body = await request.json();
-      if (!body.data || !body.name) return fail(400, "Missing data or name", "bad_request");
+      if (!body.data || !body.name) return fail2(400, "Missing data or name", "bad_request");
       const base64Data = body.data.replace(/^data:[^;]+;base64,/, "");
       const tooBig = overRequestBound(Math.floor(base64Data.length * 3 / 4));
       if (tooBig) return tooBig;
@@ -6384,43 +6863,75 @@ async function handleUpload(request, url, bucket, prefix, auth, scope) {
       fileName = body.name;
       rawMimeType = body.mimeType || "application/octet-stream";
     }
-    const mime = resolveMimeType(rawMimeType);
-    if (mime instanceof Response) return mime;
-    const located = locateUpload(url, prefix, fileName);
+    const mimeType = resolveMimeType(rawMimeType);
+    const located = locateUpload(url, prefix, excludedPrefixes, fileName);
     if (located instanceof Response) return located;
     const replacesKey = url.searchParams.get("key") === null ? null : located.key;
-    const overQuota = await admitStorage(bucket, auth.storage, fileData.byteLength, replacesKey);
-    if (overQuota) return overQuota;
-    await bucket.put(located.key, fileData, {
-      httpMetadata: { contentType: mime.mimeType },
-      customMetadata: fileMetadata(fileName, auth.userId)
-    });
-    return storedFileJson(located.key, fileName, url, scope);
+    const replaced = replacesKey === null ? null : await bucket.head(replacesKey);
+    const replacedBytes = replaced?.size ?? 0;
+    const admission = await admitStorage(bucket, auth.storage, fileData.byteLength, replacedBytes);
+    if (admission instanceof Response) return admission;
+    try {
+      const written = await bucket.put(located.key, fileData, {
+        // Replacement credit is valid only while the exact object that earned
+        // it still exists. A concurrent delete or overwrite loses this CAS and
+        // retries from a fresh head instead of landing uncounted bytes.
+        ...replaced ? { onlyIf: { etagMatches: replaced.etag } } : {},
+        httpMetadata: { contentType: mimeType },
+        customMetadata: fileMetadata(fileName, auth.userId)
+      });
+      if (!written) {
+        await releaseQuotaMarker(bucket, auth.storage, admission.markerKey, true);
+        return fail2(
+          409,
+          "The file changed while this upload was being admitted. Retry the upload.",
+          "write_conflict"
+        );
+      }
+    } catch (error) {
+      await releaseQuotaMarker(bucket, auth.storage, admission.markerKey, true);
+      throw error;
+    }
+    await releaseQuotaMarker(
+      bucket,
+      auth.storage,
+      admission.markerKey,
+      admission.markerKey !== null || fileData.byteLength < replacedBytes
+    );
+    return storedFileJson(located.key, prefix, fileName, url, scope);
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Upload failed";
     console.error("[handleUpload] Error:", msg, err instanceof Error ? err.stack : "");
-    return fail(500, msg, "upload_failed");
+    return fail2(500, msg, "upload_failed");
   }
 }
-function locateUpload(url, prefix, fileName) {
+function locateUpload(url, prefix, excludedPrefixes, fileName, generatedId) {
   const requested = url.searchParams.get("key");
-  const subkey = requested ?? `${Date.now()}-${Math.random().toString(36).slice(2, 11)}-${fileName}`;
-  const anchored = anchorKey(subkey, prefix);
+  const subkey = requested ?? (generatedId ? `${generatedId}-${fileName}` : `${Date.now()}-${Math.random().toString(36).slice(2, 11)}-${fileName}`);
+  const anchored = anchorKey(subkey, prefix, excludedPrefixes);
   return anchored instanceof Response ? anchored : { key: anchored.key, subkey };
 }
-function fileMetadata(fileName, userId) {
+function fileMetadata(fileName, userId, reservationId, declaredBytes) {
   return {
     originalName: fileName,
     ...userId ? { uploadedBy: userId } : {},
+    ...reservationId ? { reservationId } : {},
+    ...declaredBytes === void 0 ? {} : { declaredBytes: String(declaredBytes) },
     uploadedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-function storedFileJson(key, name, url, scope) {
+function storedFileJson(key, prefix, name, url, scope) {
   const fileUrl = new URL(`/api/files/${encodeKeyPath(key)}`, url.origin);
   fileUrl.searchParams.set("scope", scope);
   return Response.json(
-    { success: true, key, url: fileUrl.toString(), name },
-    { headers: CORS_HEADERS3 }
+    {
+      success: true,
+      key,
+      relativeKey: scopeRelativeKey(key, prefix),
+      url: fileUrl.toString(),
+      name
+    },
+    { headers: CORS_HEADERS4 }
   );
 }
 var MAX_CONTROL_BODY_BYTES = 64 * 1024;
@@ -6428,24 +6939,61 @@ async function readControlJson(request) {
   const declared = declaredLength(request, "This request");
   if (declared instanceof Response) return declared;
   if (declared > MAX_CONTROL_BODY_BYTES) {
-    return fail(413, `Request body exceeds ${MAX_CONTROL_BODY_BYTES} bytes`, "too_large");
+    return fail2(413, `Request body exceeds ${MAX_CONTROL_BODY_BYTES} bytes`, "too_large");
   }
   let parsed;
   try {
     parsed = await request.json();
   } catch {
-    return fail(400, "Body must be JSON", "bad_request");
+    return fail2(400, "Body must be JSON", "bad_request");
   }
-  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : fail(400, "Body must be a JSON object", "bad_request");
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : fail2(400, "Body must be a JSON object", "bad_request");
 }
-function resolveSession(url, prefix) {
+var REQUEST_ID_RE = /^[A-Za-z0-9_-]{16,80}$/;
+function resolveSession(url, prefix, excludedPrefixes) {
   const uploadKey = url.searchParams.get("uploadKey");
   const uploadId = url.searchParams.get("uploadId");
-  if (!uploadKey || !uploadId) {
-    return fail(400, "uploadKey and uploadId are required", "bad_request");
+  const reservationId = url.searchParams.get("reservationId");
+  if (!uploadKey || !uploadId || !reservationId) {
+    return fail2(400, "uploadKey, uploadId, and reservationId are required", "bad_request");
+  }
+  if (!REQUEST_ID_RE.test(reservationId)) {
+    return fail2(400, "reservationId is invalid", "bad_request");
   }
-  const anchored = anchorKey(uploadKey, prefix);
-  return anchored instanceof Response ? anchored : { key: anchored.key, uploadId };
+  const anchored = anchorKey(uploadKey, prefix, excludedPrefixes);
+  return anchored instanceof Response ? anchored : { key: anchored.key, uploadKey, uploadId, reservationId };
+}
+function reservationMatches(reservation, session) {
+  return reservation.admitted && reservation.uploadId === session.uploadId && reservation.objectKey === session.key && reservation.uploadKey === session.uploadKey;
+}
+function multipartSessionJson(uploadId, uploadKey, reservationId) {
+  return Response.json(
+    {
+      uploadId,
+      uploadKey,
+      reservationId,
+      partSize: UPLOAD_PART_BYTES,
+      maxParts: MAX_UPLOAD_PARTS,
+      maxBytes: MAX_APP_FILE_BYTES
+    },
+    { headers: CORS_HEADERS4 }
+  );
+}
+function multipartPartCount(declaredBytes) {
+  return Math.ceil(declaredBytes / UPLOAD_PART_BYTES);
+}
+function expectedMultipartPartBytes(declaredBytes, partNumber) {
+  const partCount = multipartPartCount(declaredBytes);
+  if (partNumber < 1 || partNumber > partCount) return null;
+  return partNumber === partCount ? declaredBytes - (partCount - 1) * UPLOAD_PART_BYTES : UPLOAD_PART_BYTES;
+}
+function multipartLayoutError(declaredBytes) {
+  return fail2(
+    400,
+    `This upload must use ${multipartPartCount(declaredBytes)} sequential part(s) at the advertised ${formatBytes(UPLOAD_PART_BYTES)} size, except for the final remainder.`,
+    "bad_part_layout",
+    { partSize: UPLOAD_PART_BYTES, partCount: multipartPartCount(declaredBytes) }
+  );
 }
 async function streamPart(upload, partNumber, body, expectedBytes) {
   let observedBytes = 0;
@@ -6468,57 +7016,121 @@ async function streamPart(upload, partNumber, body, expectedBytes) {
   }
   return { ok: true, part: uploaded.value };
 }
-async function handleMultipart(request, url, bucket, prefix, auth, scope, subpath) {
+async function handleMultipart(request, url, bucket, prefix, excludedPrefixes, auth, scope, subpath) {
   if (subpath === "multipart" && request.method === "POST") {
-    return multipartInit(request, url, bucket, prefix, auth);
+    return multipartInit(request, url, bucket, prefix, excludedPrefixes, auth);
+  }
+  if (subpath === "multipart/part") {
+    return multipartPart(request, url, bucket, prefix, excludedPrefixes, auth);
   }
-  if (subpath === "multipart/part") return multipartPart(request, url, bucket, prefix);
   if (subpath === "multipart/complete") {
-    return multipartComplete(request, url, bucket, prefix, auth, scope);
+    return multipartComplete(request, url, bucket, prefix, excludedPrefixes, auth, scope);
   }
-  return multipartAbort(url, bucket, prefix);
+  return multipartAbort(url, bucket, prefix, excludedPrefixes, auth);
 }
-async function multipartInit(request, url, bucket, prefix, auth) {
+async function multipartInit(request, url, bucket, prefix, excludedPrefixes, auth) {
   const body = await readControlJson(request);
   if (body instanceof Response) return body;
   const size = body.size;
-  if (!Number.isSafeInteger(size) || size < 0) {
-    return fail(400, "size must be a non-negative integer number of bytes", "bad_request");
+  if (!Number.isSafeInteger(size) || size <= 0) {
+    return fail2(400, "size must be a positive integer number of bytes", "bad_request");
   }
   const tooBig = overCeiling(size);
   if (tooBig) return tooBig;
   const name = typeof body.name === "string" ? body.name.trim() : "";
-  if (!name) return fail(400, "name is required", "bad_request");
-  const mime = resolveMimeType(typeof body.mimeType === "string" ? body.mimeType : "");
-  if (mime instanceof Response) return mime;
-  const located = locateUpload(url, prefix, name);
+  if (!name) return fail2(400, "name is required", "bad_request");
+  const requestId = typeof body.requestId === "string" ? body.requestId : "";
+  if (!REQUEST_ID_RE.test(requestId)) {
+    return fail2(
+      400,
+      "requestId must be 16\u201380 URL-safe characters and must be reused when retrying init.",
+      "bad_request"
+    );
+  }
+  const mimeType = resolveMimeType(typeof body.mimeType === "string" ? body.mimeType : "");
+  const located = locateUpload(url, prefix, excludedPrefixes, name, requestId);
   if (located instanceof Response) return located;
-  const replacesKey = url.searchParams.get("key") === null ? null : located.key;
-  const overQuota = await admitStorage(bucket, auth.storage, size, replacesKey);
-  if (overQuota) return overQuota;
+  const completed = await bucket.head(located.key);
+  if (completed?.customMetadata?.reservationId === requestId) {
+    return fail2(
+      409,
+      "requestId already completed an upload; start the new upload with a fresh requestId.",
+      "request_id_completed"
+    );
+  }
+  const existing = await readMultipartReservation(bucket, auth.storage, requestId);
+  if (existing === "invalid") {
+    return quotaUnavailable("This upload reservation could not be read. Retry shortly.");
+  }
+  if (existing) {
+    const sameRequest = existing.objectKey === located.key && existing.uploadKey === located.subkey && existing.declaredBytes === size;
+    return sameRequest && existing.admitted ? multipartSessionJson(existing.uploadId, existing.uploadKey, requestId) : sameRequest ? quotaUnavailable("This upload is still being initialized. Retry shortly.") : fail2(
+      409,
+      "requestId already belongs to a different multipart upload.",
+      "request_id_conflict"
+    );
+  }
   let upload;
   try {
     upload = await bucket.createMultipartUpload(located.key, {
-      httpMetadata: { contentType: mime.mimeType },
-      customMetadata: fileMetadata(name, auth.userId)
+      httpMetadata: { contentType: mimeType },
+      customMetadata: fileMetadata(name, auth.userId, requestId, size)
     });
   } catch (error) {
     return multipartFailure(error);
   }
-  return Response.json(
-    {
+  const marker = auth.storage ? {
+    key: multipartMarkerKey(auth.storage, requestId),
+    body: JSON.stringify({
+      version: 1,
+      reservationId: requestId,
       uploadId: upload.uploadId,
-      // Echoed back on every later call. Relative to the app, exactly like
-      // `?key=`, so the mount that anchors keys anchors this one too.
+      objectKey: located.key,
       uploadKey: located.subkey,
-      partSize: UPLOAD_PART_BYTES,
-      maxParts: MAX_UPLOAD_PARTS,
-      maxBytes: MAX_APP_FILE_BYTES
-    },
-    { headers: CORS_HEADERS3 }
-  );
+      admitted: false,
+      declaredBytes: size
+    }),
+    metadata: {
+      quotaKind: "multipart",
+      active: "false"
+    }
+  } : void 0;
+  const reservedBytes = Math.max(size, 5 * 1024 * 1024);
+  const admission = await admitStorage(bucket, auth.storage, reservedBytes, 0, marker);
+  if (admission instanceof Response) {
+    await upload.abort().catch(() => void 0);
+    if (admission.status === 409 && auth.storage) {
+      const winner = await readMultipartReservation(bucket, auth.storage, requestId);
+      if (winner && winner !== "invalid" && winner.objectKey === located.key && winner.uploadKey === located.subkey && winner.declaredBytes === size && winner.admitted) {
+        return multipartSessionJson(winner.uploadId, winner.uploadKey, requestId);
+      }
+    }
+    return admission;
+  }
+  if (auth.storage && !await activateMultipartReservation(bucket, auth.storage, requestId)) {
+    await upload.abort().catch(() => void 0);
+    await releaseQuotaMarker(bucket, auth.storage, admission.markerKey, true);
+    return quotaUnavailable("This upload reservation could not be finalized. Retry shortly.");
+  }
+  return multipartSessionJson(upload.uploadId, located.subkey, requestId);
+}
+async function abandonMultipart(bucket, session, auth, reservation) {
+  let result = "aborted";
+  try {
+    await bucket.resumeMultipartUpload(session.key, session.uploadId).abort();
+  } catch (error) {
+    if (r2ErrorCode(error) !== 10024) {
+      console.error("[files:multipart] abort:", error instanceof Error ? error.message : error);
+      return "failed";
+    }
+    result = "absent";
+  }
+  if (reservation) {
+    if (!await releaseQuotaMarker(bucket, auth.storage, reservation.key, true)) return "failed";
+  }
+  return result;
 }
-async function multipartPart(request, url, bucket, prefix) {
+async function multipartPart(request, url, bucket, prefix, excludedPrefixes, auth) {
   const refuse = async (response) => {
     await request.body?.cancel().catch(() => void 0);
     return response;
@@ -6530,16 +7142,60 @@ async function multipartPart(request, url, bucket, prefix) {
   const partNumber = Number(url.searchParams.get("partNumber"));
   if (!Number.isSafeInteger(partNumber) || partNumber < 1 || partNumber > MAX_UPLOAD_PARTS) {
     return refuse(
-      fail(400, `partNumber must be a whole number from 1 to ${MAX_UPLOAD_PARTS}`, "bad_request")
+      fail2(400, `partNumber must be a whole number from 1 to ${MAX_UPLOAD_PARTS}`, "bad_request")
     );
   }
-  const session = resolveSession(url, prefix);
+  const session = resolveSession(url, prefix, excludedPrefixes);
   if (session instanceof Response) return refuse(session);
-  if (!request.body) return fail(400, "A part body is required", "bad_request");
+  if (!request.body) return fail2(400, "A part body is required", "bad_request");
+  const reservation = await readMultipartReservation(bucket, auth.storage, session.reservationId);
+  if (reservation === "invalid") {
+    return refuse(quotaUnavailable("This upload reservation could not be read. Retry shortly."));
+  }
+  if (auth.storage && reservation && !reservationMatches(reservation, session)) {
+    return refuse(
+      fail2(
+        404,
+        "That upload does not exist \u2014 it was completed, abandoned, or expired. Start a new one.",
+        "unknown_upload"
+      )
+    );
+  }
+  if (auth.storage && !reservation) {
+    return refuse(
+      fail2(
+        404,
+        "That upload does not exist \u2014 it was completed, abandoned, or expired. Start a new one.",
+        "unknown_upload"
+      )
+    );
+  }
+  if (reservation) {
+    const expectedBytes = expectedMultipartPartBytes(reservation.declaredBytes, partNumber);
+    if (expectedBytes === null || declaredBytes !== expectedBytes) {
+      return refuse(multipartLayoutError(reservation.declaredBytes));
+    }
+  }
+  const refreshed = await refreshMultipartReservation(
+    bucket,
+    auth.storage,
+    session.reservationId,
+    session.uploadId,
+    session.key
+  );
+  if (auth.storage && (refreshed === null || refreshed === "invalid")) {
+    return refuse(quotaUnavailable("This upload reservation is missing or invalid."));
+  }
+  if (refreshed === "busy") {
+    return refuse(quotaUnavailable("This upload reservation is busy. Retry the part shortly."));
+  }
   const upload = bucket.resumeMultipartUpload(session.key, session.uploadId);
   const stored = await streamPart(upload, partNumber, request.body, declaredBytes);
   if (!stored.ok) {
-    return stored.lengthMismatch ? fail(
+    if (r2ErrorCode(stored.error) === 10024 && reservation) {
+      await releaseQuotaMarker(bucket, auth.storage, reservation.key, true);
+    }
+    return stored.lengthMismatch ? fail2(
       400,
       `Part ${partNumber} declared ${declaredBytes} bytes but its body did not carry them`,
       "bad_request"
@@ -6547,29 +7203,98 @@ async function multipartPart(request, url, bucket, prefix) {
   }
   return Response.json(
     { partNumber: stored.part.partNumber, etag: stored.part.etag },
-    { headers: CORS_HEADERS3 }
+    { headers: CORS_HEADERS4 }
   );
 }
-async function multipartComplete(request, url, bucket, prefix, auth, scope) {
+async function completedReservationObject(bucket, session) {
+  const object = await bucket.head(session.key);
+  return object?.customMetadata?.reservationId === session.reservationId ? object : null;
+}
+async function finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope, prefix) {
+  const declaredMetadata = Number(object.customMetadata?.declaredBytes);
+  const declaredBytes = reservation?.declaredBytes ?? (Number.isSafeInteger(declaredMetadata) && declaredMetadata >= 0 ? declaredMetadata : MAX_APP_FILE_BYTES);
+  const refusal = overCeiling(object.size) ?? (object.size > declaredBytes ? fail2(
+    400,
+    `The assembled upload exceeded its declared ${declaredBytes}-byte size and was not kept.`,
+    "declared_size_exceeded"
+  ) : null);
+  if (refusal) {
+    let remaining;
+    try {
+      const current = await bucket.head(session.key);
+      if (current?.etag === object.etag) await bucket.delete(session.key);
+      remaining = await bucket.head(session.key);
+    } catch (error) {
+      console.error("[files:multipart] invalid object cleanup:", error);
+      return quotaUnavailable("The invalid assembled file could not be removed. Retry completion.");
+    }
+    if (remaining?.etag === object.etag) {
+      return quotaUnavailable("The invalid assembled file could not be removed. Retry completion.");
+    }
+    if (reservation) {
+      const cleaned = await releaseQuotaMarker(bucket, auth.storage, reservation.key, true);
+      if (!cleaned) return quotaUnavailable("The upload was removed, but cleanup must be retried.");
+    }
+    return refusal;
+  }
+  if (reservation) {
+    const cleaned = await releaseQuotaMarker(bucket, auth.storage, reservation.key, true);
+    if (!cleaned) {
+      return quotaUnavailable("The file was stored, but its reservation cleanup must be retried.");
+    }
+  }
+  const name = object.customMetadata?.originalName ?? session.uploadKey.split("/").pop() ?? "file";
+  return storedFileJson(session.key, prefix, name, url, scope);
+}
+async function multipartComplete(request, url, bucket, prefix, excludedPrefixes, auth, scope) {
   const body = await readControlJson(request);
   if (body instanceof Response) return body;
-  const session = resolveSession(url, prefix);
+  const session = resolveSession(url, prefix, excludedPrefixes);
   if (session instanceof Response) return session;
+  const reservation = await readMultipartReservation(bucket, auth.storage, session.reservationId);
+  if (reservation === "invalid") {
+    return quotaUnavailable("This upload reservation could not be read. Retry shortly.");
+  }
+  if (auth.storage && reservation && !reservationMatches(reservation, session)) {
+    return fail2(
+      404,
+      "That upload does not exist \u2014 it was completed, abandoned, or expired. Start a new one.",
+      "unknown_upload"
+    );
+  }
+  if (auth.storage && !reservation) {
+    const completed = await completedReservationObject(bucket, session);
+    if (completed) {
+      return finishCompletedMultipart(bucket, session, null, completed, auth, url, scope, prefix);
+    }
+    await abandonMultipart(bucket, session, auth, null);
+    return quotaUnavailable("This upload reservation is missing or does not match.");
+  }
   const raw = body.parts;
   if (!Array.isArray(raw) || raw.length === 0) {
-    return fail(400, "parts must be a non-empty array", "bad_request");
+    return fail2(400, "parts must be a non-empty array", "bad_request");
   }
   if (raw.length > MAX_UPLOAD_PARTS) {
-    return fail(400, `An upload may have at most ${MAX_UPLOAD_PARTS} parts`, "bad_request");
+    return fail2(400, `An upload may have at most ${MAX_UPLOAD_PARTS} parts`, "bad_request");
+  }
+  if (reservation && raw.length !== multipartPartCount(reservation.declaredBytes)) {
+    return multipartLayoutError(reservation.declaredBytes);
   }
   const parts = [];
   for (let index = 0; index < raw.length; index++) {
     const { partNumber, etag } = raw[index] ?? {};
-    if (!Number.isSafeInteger(partNumber) || partNumber < 1) {
-      return fail(400, `parts[${index}].partNumber must be a positive integer`, "bad_request");
+    if (!Number.isSafeInteger(partNumber) || partNumber < 1 || partNumber > MAX_UPLOAD_PARTS) {
+      return fail2(
+        400,
+        `parts[${index}].partNumber must be a whole number from 1 to ${MAX_UPLOAD_PARTS}`,
+        "bad_request"
+      );
+    }
+    if (reservation && partNumber !== index + 1) {
+      return multipartLayoutError(reservation.declaredBytes);
     }
     if (typeof etag !== "string" || !etag) {
-      return fail(400, `parts[${index}].etag must be the string uploadPart returned`, "bad_request");
+      return fail2(400, `parts[${index}].etag must be the string uploadPart returned`, "bad_request");
     }
     parts.push({ partNumber, etag });
   }
@@ -6577,39 +7302,87 @@ async function multipartComplete(request, url, bucket, prefix, auth, scope) {
   try {
     object = await bucket.resumeMultipartUpload(session.key, session.uploadId).complete(parts);
   } catch (error) {
+    const completed = await completedReservationObject(bucket, session);
+    if (completed) {
+      return finishCompletedMultipart(
+        bucket,
+        session,
+        reservation,
+        completed,
+        auth,
+        url,
+        scope,
+        prefix
+      );
+    }
+    if (r2ErrorCode(error) === 10024 && reservation) {
+      await releaseQuotaMarker(bucket, auth.storage, reservation.key, true);
+    }
     return multipartFailure(error);
   }
-  const tooBig = overCeiling(object.size);
-  if (tooBig) {
-    await bucket.delete(session.key).catch(() => void 0);
-    return tooBig;
-  }
-  const overQuota = await admitAssembledObject(bucket, auth.storage, session.key, object.size);
-  if (overQuota) return overQuota;
-  const name = object.customMetadata?.originalName ?? session.key.split("/").pop() ?? "file";
-  return storedFileJson(session.key, name, url, scope);
+  return finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope, prefix);
 }
-async function multipartAbort(url, bucket, prefix) {
-  const session = resolveSession(url, prefix);
+async function multipartAbort(url, bucket, prefix, excludedPrefixes, auth) {
+  const session = resolveSession(url, prefix, excludedPrefixes);
   if (session instanceof Response) return session;
-  try {
-    await bucket.resumeMultipartUpload(session.key, session.uploadId).abort();
-  } catch (error) {
-    console.error("[files:multipart] abort:", error instanceof Error ? error.message : error);
-    return Response.json({ success: true, aborted: false }, { headers: CORS_HEADERS3 });
+  const reservation = await readMultipartReservation(bucket, auth.storage, session.reservationId);
+  if (reservation === "invalid") {
+    return Response.json({ success: true, aborted: false }, { headers: CORS_HEADERS4 });
+  }
+  if (auth.storage && reservation && !reservationMatches(reservation, session)) {
+    return Response.json({ success: true, aborted: false }, { headers: CORS_HEADERS4 });
   }
-  return Response.json({ success: true, aborted: true }, { headers: CORS_HEADERS3 });
+  const result = await abandonMultipart(bucket, session, auth, reservation || null);
+  return Response.json({ success: true, aborted: result === "aborted" }, { headers: CORS_HEADERS4 });
 }
-async function handleList(bucket, prefix, url, scope, auth) {
+async function handleList(bucket, prefix, excludedPrefixes, url, scope, auth) {
   const userPrefix = url.searchParams.get("prefix") || "";
   const listPrefix = `${prefix}${userPrefix}`;
-  const limit = parseInt(url.searchParams.get("limit") || "100", 10);
-  const listed = await bucket.list({ prefix: listPrefix, limit });
-  const files = listed.objects.map((obj) => {
+  const requestedLimit = Number(url.searchParams.get("limit") ?? 100);
+  const limit = Number.isSafeInteger(requestedLimit) ? Math.min(1e3, Math.max(1, requestedLimit)) : 100;
+  const requestCursor = url.searchParams.get("cursor");
+  if (excludedPrefixes.some((excluded) => listPrefix.startsWith(excluded))) {
+    return Response.json({ files: [], truncated: false }, { headers: CORS_HEADERS4 });
+  }
+  const withMetadata = (options) => ({ ...options, include: ["customMetadata"] });
+  const listed = await bucket.list(
+    withMetadata({
+      prefix: listPrefix,
+      limit,
+      ...requestCursor ? { cursor: requestCursor } : {}
+    })
+  );
+  const visible = listed.objects.filter(
+    (object) => isKeyWithinScope(object.key, prefix, excludedPrefixes)
+  );
+  const seen = new Set(visible.map((object) => object.key));
+  let frontier = listed;
+  let frontierKey = listed.objects.at(-1)?.key;
+  for (const excluded of excludedPrefixes.filter((candidate) => candidate.startsWith(listPrefix)).sort()) {
+    if (!frontier.truncated || visible.length >= limit) break;
+    const excludedEnd = `${excluded}\u{10FFFF}`;
+    const after = await bucket.list(
+      withMetadata({
+        prefix: listPrefix,
+        startAfter: frontierKey && frontierKey > excludedEnd ? frontierKey : excludedEnd,
+        limit: limit - visible.length
+      })
+    );
+    for (const object of after.objects) {
+      if (!seen.has(object.key) && isKeyWithinScope(object.key, prefix, excludedPrefixes)) {
+        seen.add(object.key);
+        visible.push(object);
+      }
+    }
+    frontierKey = after.objects.at(-1)?.key ?? frontierKey;
+    frontier = after;
+  }
+  const files = visible.slice(0, limit).map((obj) => {
     const fileUrl = new URL(`/api/files/${encodeKeyPath(obj.key)}`, url.origin);
     fileUrl.searchParams.set("scope", scope);
     return {
       key: obj.key,
+      relativeKey: scopeRelativeKey(obj.key, prefix),
       size: obj.size,
       uploaded: obj.uploaded.toISOString(),
       url: fileUrl.toString(),
@@ -6617,32 +7390,46 @@ async function handleList(bucket, prefix, url, scope, auth) {
     };
   });
   let storage;
-  if (auth.storage) {
-    const usedBytes = await allocationUsage(bucket, auth.storage);
+  if (auth.storage && auth.includeStorageUsage) {
+    const usedBytes = await storageUsage(bucket, auth.storage);
     if (usedBytes !== null) storage = { usedBytes };
     const limitBytes = await auth.storage.limitBytes();
     if (storage && limitBytes !== null) storage.limitBytes = limitBytes;
   }
   return Response.json(
-    { files, truncated: listed.truncated, ...storage ? { storage } : {} },
-    { headers: CORS_HEADERS3 }
+    {
+      files,
+      truncated: frontier.truncated,
+      ...frontier.truncated ? { cursor: frontier.cursor } : {},
+      ...storage ? { storage } : {}
+    },
+    { headers: CORS_HEADERS4 }
   );
 }
-async function handleDownload(bucket, key, scope) {
+async function handleDownload(request, bucket, key, scope) {
   const object = await bucket.get(key);
   if (!object) {
-    return Response.json({ error: "File not found" }, { status: 404, headers: CORS_HEADERS3 });
+    return Response.json({ error: "File not found" }, { status: 404, headers: CORS_HEADERS4 });
   }
   const headers = new Headers();
-  headers.set("Content-Type", object.httpMetadata?.contentType || "application/octet-stream");
+  const storedType = resolveMimeType(object.httpMetadata?.contentType ?? "");
+  const mustDownload = DANGEROUS_MIME_TYPES.has(storedType);
+  headers.set("Content-Type", mustDownload ? "application/octet-stream" : storedType);
   headers.set("X-Content-Type-Options", "nosniff");
+  headers.set("ETag", object.httpEtag);
   headers.set(
     "Cache-Control",
-    scope === "app" ? "public, max-age=31536000, immutable" : "private, no-store"
+    scope === "self" ? "private, no-store" : "public, max-age=0, must-revalidate"
   );
   headers.set("Access-Control-Allow-Origin", "*");
-  if (object.customMetadata?.originalName) {
-    headers.set("Content-Disposition", contentDisposition(object.customMetadata.originalName));
+  const originalName = object.customMetadata?.originalName ?? key.split("/").pop() ?? "download";
+  headers.set(
+    "Content-Disposition",
+    contentDisposition(originalName, mustDownload ? "attachment" : "inline")
+  );
+  if (mustDownload) headers.set("Content-Security-Policy", "sandbox; default-src 'none'");
+  if (scope === "app" && request.headers.get("if-none-match") === object.httpEtag) {
+    return new Response(null, { status: 304, headers });
   }
   return new Response(object.body, { headers });
 }
@@ -7915,7 +8702,8 @@ function searchDocumentationCorpus(corpus, query, limit = 6) {
       title: chunk.title,
       ...chunk.heading ? { heading: chunk.heading } : {},
       excerpt: excerpt(chunk.text, terms),
-      score
+      score,
+      termCoverage: matchedTerms / terms.length
     };
   }).filter((result) => result.score > 0).sort((left, right) => right.score - left.score || left.route.localeCompare(right.route)).slice(0, Math.max(1, Math.min(limit, 10)));
 }
@@ -8035,6 +8823,25 @@ function excerpt(text, terms) {
   return `${start > 0 ? "\u2026" : ""}${text.slice(start, end).trim()}${end < text.length ? "\u2026" : ""}`;
 }
 
+// src/documentation/text.ts
+function slugify(value) {
+  return value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function documentationSubject(name) {
+  const normalized = name.trim();
+  if (!normalized || /^documentation$/i.test(normalized)) return "documentation";
+  return /(?:\bdocs?|documentation)$/i.test(normalized) ? normalized : `${normalized} documentation`;
+}
+function createSlugger(fallback = "section") {
+  const seen = /* @__PURE__ */ new Map();
+  return (value) => {
+    const base = slugify(value) || fallback;
+    const count = seen.get(base) ?? 0;
+    seen.set(base, count + 1);
+    return count === 0 ? base : `${base}-${count + 1}`;
+  };
+}
+
 // src/documentation/worker/published-corpus.ts
 var cachedCorpus;
 async function loadDocumentationPublishedManifest(env, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
@@ -8092,7 +8899,7 @@ async function resolveDocumentationPublishedCorpus(env, sourceHash, requestUrl =
 }
 async function readDocumentationPublishedPage(env, corpus, requestedRoute, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
   const route = collapseRoute(requestedRoute.split("#", 1)[0] ?? "/");
-  const firstChunk = corpus.find((chunk) => chunk.route === route);
+  const firstChunk = corpus.find((chunk) => (chunk.route.split("#", 1)[0] ?? "") === route);
   if (!firstChunk) return null;
   const pathname = route === "/" ? `${assetBasePath}/index.md` : `${assetBasePath}${route}.md`;
   const response = await env.ASSETS.fetch(new Request(new URL(pathname, requestUrl)));
@@ -8101,6 +8908,36 @@ async function readDocumentationPublishedPage(env, corpus, requestedRoute, reque
   if (markdown.length > 5e5) throw new Error("Documentation page exceeds 500000 characters");
   return { route, title: firstChunk.title, markdown };
 }
+function documentationPageSection(markdown, fragment) {
+  const target = slugify(fragment);
+  if (!target) return null;
+  const slug = createSlugger();
+  const lines = markdown.split("\n");
+  let fence = null;
+  let start = -1;
+  let startDepth = 0;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? "";
+    const fenceMarker = line.match(/^ {0,3}(`{3,}|~{3,})/)?.[1];
+    if (fenceMarker && !fence) {
+      fence = fenceMarker;
+      continue;
+    }
+    if (fence) {
+      if (fenceMarker?.startsWith(fence)) fence = null;
+      continue;
+    }
+    const heading = line.match(/^ {0,3}(#{1,6})\s+(.+)$/);
+    if (!heading) continue;
+    const depth = (heading[1] ?? "").length;
+    if (start !== -1 && depth <= startDepth) return lines.slice(start, index).join("\n").trim();
+    if (start === -1 && slug(heading[2] ?? "") === target) {
+      start = index;
+      startDepth = depth;
+    }
+  }
+  return start === -1 ? null : lines.slice(start).join("\n").trim();
+}
 function parseAssistantPolicy(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const policy = value;
@@ -8350,6 +9187,17 @@ function registerDocumentationStaticRoutes(app, publicBasePath = "/docs", assetB
       status = 404;
     }
     if (status === 404) {
+      if (pathname.endsWith(".md")) {
+        return secureDocumentationResponse(
+          new Response(
+            `No documentation page at ${pathname}. See ${publicBasePath}/llms.txt for every published page.
+`,
+            { status: 404, headers: { "Content-Type": "text/plain; charset=utf-8" } }
+          ),
+          404,
+          pathname
+        );
+      }
       const url = new URL(c.req.url);
       url.pathname = `${assetBasePath}/404.html`;
       response = await fetchDocumentationAsset(c.env, c.req.raw, url, assetBasePath);
@@ -8407,13 +9255,6 @@ function secureDocumentationResponse(response, status, pathname) {
   return new Response(response.body, { status, headers });
 }
 
-// src/documentation/text.ts
-function documentationSubject(name) {
-  const normalized = name.trim();
-  if (!normalized || /^documentation$/i.test(normalized)) return "documentation";
-  return /(?:\bdocs?|documentation)$/i.test(normalized) ? normalized : `${normalized} documentation`;
-}
-
 // src/documentation/worker/mcp/protocol.ts
 var MCP_SERVER_VERSION = "1.0.0";
 var CURRENT_PROTOCOL_VERSION = "2025-11-25";
@@ -8525,7 +9366,7 @@ var DOCUMENTATION_TOOLS = [
     },
     outputSchema: {
       type: "object",
-      properties: { results: { type: "array" } },
+      properties: { notice: { type: "string" }, results: { type: "array" } },
       required: ["results"]
     },
     annotations: {
@@ -8538,11 +9379,11 @@ var DOCUMENTATION_TOOLS = [
   {
     name: "documentation_read",
     title: "Read documentation page",
-    description: "Read one complete published documentation page as Markdown.",
+    description: "Read one published documentation page as Markdown. The route may omit the leading slash, and a #fragment (as returned by documentation_search) narrows the result to that heading section; an unknown fragment returns the whole page with a notice.",
     inputSchema: {
       type: "object",
       properties: {
-        route: { type: "string", minLength: 1, maxLength: 500, pattern: "^/" }
+        route: { type: "string", minLength: 1, maxLength: 500 }
       },
       required: ["route"],
       additionalProperties: false
@@ -8550,6 +9391,7 @@ var DOCUMENTATION_TOOLS = [
     outputSchema: {
       type: "object",
       properties: {
+        notice: { type: "string" },
         route: { type: "string" },
         title: { type: "string" },
         url: { type: "string" },
@@ -8576,19 +9418,24 @@ async function callDocumentationTool(rawRequest, request, corpus, env, basePath
     if (query.length < 2 || query.length > 300 || !Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 10) {
       return mcpError(request.id, -32602, "Invalid documentation_search arguments");
     }
-    const value = {
-      results: searchDocumentationCorpus(corpus, query, Number(limit)).map((result) => ({
-        ...result,
-        url: new URL(documentationPublicPath(basePath, result.route), origin).toString()
-      }))
-    };
-    return toolResult(request.id, value);
+    const results = searchDocumentationCorpus(corpus, query, Number(limit)).map((result) => ({
+      ...result,
+      url: new URL(documentationPublicPath(basePath, result.route), origin).toString()
+    }));
+    return toolResult(request.id, {
+      ...results[0]?.termCoverage === 1 ? {} : {
+        notice: "No section matches every search term \u2014 the topic may be absent or spread across sections."
+      },
+      results
+    });
   }
   if (name === "documentation_read") {
     const route = typeof args.route === "string" ? args.route.trim() : "";
-    if (!route.startsWith("/") || route.length > 500) {
+    if (!route || route.length > 500) {
       return mcpError(request.id, -32602, "Invalid documentation_read arguments");
     }
+    const hash = route.indexOf("#");
+    const fragment = hash === -1 ? "" : route.slice(hash + 1);
     try {
       const page = await readDocumentationPublishedPage(
         env,
@@ -8598,8 +9445,11 @@ async function callDocumentationTool(rawRequest, request, corpus, env, basePath
         assetBasePath
       );
       if (!page) return toolError(request.id, `No published documentation page exists at ${route}`);
+      const section = fragment ? documentationPageSection(page.markdown, fragment) : null;
       return toolResult(request.id, {
+        ...fragment && section === null ? { notice: `The fragment #${fragment} was not found; returning the whole page.` } : {},
         ...page,
+        ...section === null ? {} : { markdown: section },
         url: new URL(documentationPublicPath(basePath, page.route), origin).toString()
       });
     } catch (error) {