@12-apps/storage 1.0.0

package/src/server/pipeline/sharp-renditions.ts

@@ -0,0 +1,238 @@
+import { EXTENSION_BY_CONTENT_TYPE } from '../../content-types';
+import type { RenditionOutput, RenditionSpec } from '../../renditions';
+import type { Rgba, SharpImage, SharpMetadata, SharpModule } from './sharp-module';
+
+/**
+ * Cutting the derived crops — the half of the sharp pipeline that decides what a
+ * card actually looks like.
+ *
+ * ## Why the crop PADS instead of cutting
+ *
+ * `fit: 'cover'` is the obvious way to fill a 4:3 box and it is the wrong one. A
+ * catalog shot is usually TALLER than 4:3 (bottles, cans, cups), so cover throws
+ * away the top and bottom of the product — the exact pixels the photo is of.
+ *
+ * What was wasting the box was not the aspect ratio but the MARGIN: these are
+ * product shots on a flat backdrop, and most of the frame is backdrop. So each
+ * rendition is `trim`med to the product's own bounding box first, then
+ * `contain`-fitted onto the exact canvas with that same backdrop colour behind
+ * it. The product grows until it touches the edges of the box, nothing is cut
+ * off, and the padding that remains is the colour the photo already had — so it
+ * reads as the photo rather than as a letterbox. A cut-out PNG pads with
+ * transparency for the same reason.
+ *
+ * Content is UPSCALED when the trimmed product is smaller than the canvas
+ * (deliberately no `withoutEnlargement`). The alternative pads a 200px product
+ * into a 1280px canvas, which the browser then scales DOWN to the card — drawing
+ * the product at a quarter of the size it should be.
+ *
+ * ## Animated sources are not part of this
+ *
+ * sharp models an animation as a vertical filmstrip, so trimming and padding
+ * would operate on the strip rather than on each frame. An animated source
+ * therefore yields NO renditions, which is what routes it to the flat key shape
+ * and keeps its frames.
+ */
+
+/** WebP quality for a rendition. */
+const WEBP_QUALITY = 82;
+
+/**
+ * How far a pixel may differ from the corner colour and still count as backdrop.
+ * sharp's default (10) is tuned for exactly this: it absorbs JPEG ringing and a
+ * studio backdrop's gradient without eating a pale product.
+ */
+const TRIM_THRESHOLD = 10;
+
+/**
+ * Below this, a trim has eaten the picture rather than its margin — a photo that
+ * is one flat colour, or one whose subject matches its backdrop closely enough
+ * that nothing survives the threshold. The untrimmed image is used instead:
+ * worse framing beats no product.
+ */
+const MIN_TRIMMED_EDGE = 16;
+
+/** sharp's format name for a catalog MIME type (`jpg` is spelled `jpeg`). */
+export function sharpFormatFor(contentType: string): string {
+  const extension = EXTENSION_BY_CONTENT_TYPE[contentType];
+  return extension === 'jpg' ? 'jpeg' : (extension ?? 'webp');
+}
+
+/**
+ * The animated read's header — one probe, reused for the two questions that have
+ * to be answered before anything is decoded.
+ *
+ * The ANIMATED read specifically: `sharp(bytes)` without `{ animated: true }`
+ * decodes frame one and hands back a perfectly good still, so a still read would
+ * report `pages: 1` for a GIF that has twenty and an animation would silently
+ * become five motionless WebPs.
+ */
+async function animatedMetadata(
+  sharp: SharpModule,
+  bytes: Uint8Array,
+): Promise<SharpMetadata> {
+  return sharp(bytes, { animated: true }).metadata();
+}
+
+/** Does the source carry more than one frame? */
+export async function isAnimatedSource(
+  sharp: SharpModule,
+  bytes: Uint8Array,
+): Promise<boolean> {
+  return ((await animatedMetadata(sharp, bytes)).pages ?? 1) > 1;
+}
+
+/**
+ * Would decoding this source cost more than `maxPixels`?
+ *
+ * The cut path needs its OWN answer to this, which is the whole point of the
+ * function existing here. `process` enforces the ceiling and refuses a
+ * decompression bomb — but the writer runs the two halves under one
+ * `Promise.all`, so the refusal used to arrive AFTER this path had already read
+ * the corner pixel, trimmed the full image and encoded five crops. An adversarial
+ * probe on a 30000×30000 declared source reached `extract`, `trim` and five
+ * `webp` encodes before the 413. The ceiling therefore bounded the status code
+ * and not the memory, which is the one thing it exists to bound.
+ *
+ * Answered from the header alone, before a single pixel is allocated.
+ *
+ * ## Why there is no `× pages` here, unlike in `process`
+ *
+ * This reads the ANIMATED metadata, and libvips models an animation as a vertical
+ * filmstrip: under `{ animated: true }` the reported `height` is **every frame
+ * stacked**, not one frame. Measured against real libvips 8.17.3 with a two-frame
+ * 64×64 GIF — the still read answers `height: 64, pages: 2`, the animated read
+ * answers `height: 128, pages: 2`. So `width × height` here ALREADY covers all
+ * frames, and multiplying by `pages` on top of it would over-count the cost by a
+ * factor of `pages` — refusing a modest animation as a decompression bomb.
+ *
+ * `rejectUnprocessable` in `sharp.ts` does multiply, and is right to: it reads the
+ * STILL metadata, where `height` is one frame and `pages` is the count.
+ *
+ * In practice this function only ever sees a still, because `cutRenditions`
+ * returns on `pages > 1` before calling it. The arithmetic is written to be correct
+ * either way rather than to depend on that ordering.
+ */
+function exceedsPixelBudget(metadata: SharpMetadata, maxPixels: number): boolean {
+  const width = metadata.width ?? 0;
+  const height = metadata.height ?? 0;
+  if (width <= 0 || height <= 0) return true;
+  return width * height > maxPixels;
+}
+
+/**
+ * The photo's backdrop colour, read from its top-left pixel — the same pixel
+ * sharp's `trim` measures against, so the padding put back is by construction
+ * the colour that was taken away.
+ *
+ * Alpha is carried through: a PNG cut out on transparency trims to nothing and
+ * must be padded with nothing, not with white.
+ */
+async function backdropColor(sharp: SharpModule, bytes: Uint8Array): Promise<Rgba> {
+  const raw = await sharp(bytes)
+    .extract({ left: 0, top: 0, width: 1, height: 1 })
+    .ensureAlpha()
+    .raw()
+    .toBuffer();
+  return {
+    r: raw[0] ?? 255,
+    g: raw[1] ?? 255,
+    b: raw[2] ?? 255,
+    alpha: (raw[3] ?? 255) / 255,
+  };
+}
+
+/**
+ * The product's own bounding box, as PNG bytes — lossless on purpose, because
+ * this buffer is re-encoded once per rendition and a lossy intermediate would
+ * compound its artifacts five times over.
+ *
+ * Returns the input unchanged whenever trimming cannot be trusted: sharp raises
+ * on an image it cannot trim at all, and a result that came back essentially
+ * empty means the subject matched the backdrop rather than that there was none.
+ */
+async function trimToSubject(
+  sharp: SharpModule,
+  bytes: Uint8Array,
+  backdrop: Rgba,
+): Promise<Uint8Array> {
+  try {
+    const trimmed = await sharp(bytes)
+      .trim({ background: backdrop, threshold: TRIM_THRESHOLD })
+      .png()
+      .toBuffer();
+    const { width = 0, height = 0 } = await sharp(trimmed).metadata();
+    if (width < MIN_TRIMMED_EDGE || height < MIN_TRIMMED_EDGE) return bytes;
+    return trimmed;
+  } catch {
+    return bytes;
+  }
+}
+
+/** Resize the trimmed subject onto one rendition's canvas, or `null` on failure. */
+async function renderOne(
+  sharp: SharpModule,
+  source: Uint8Array,
+  spec: RenditionSpec,
+  backdrop: Rgba,
+): Promise<Uint8Array | null> {
+  try {
+    return await (sharp(source) as SharpImage)
+      .resize({
+        width: spec.width,
+        height: spec.height,
+        // `contain`, so a tall bottle keeps its top and bottom; the canvas stays
+        // exactly spec.width × spec.height, which is what lets the srcset width
+        // descriptors be derived from the spec list alone.
+        fit: 'contain',
+        background: backdrop,
+      })
+      .webp({ quality: WEBP_QUALITY })
+      .toBuffer();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Cut every requested size from `bytes`.
+ *
+ * `bytes` is the ORIGINAL upload rather than the already-downscaled object: a
+ * 1280px intermediate would be resampled a second time on the way to a 320px
+ * card, and the source is decoded here regardless.
+ *
+ * Never throws. A source sharp cannot process yields an empty list and the
+ * writer then stores the uncropped object alone.
+ */
+export async function cutRenditions(
+  sharp: SharpModule,
+  bytes: Uint8Array,
+  specs: readonly RenditionSpec[],
+  maxPixels: number,
+): Promise<RenditionOutput[]> {
+  let source: Uint8Array;
+  let backdrop: Rgba;
+  try {
+    const metadata = await animatedMetadata(sharp, bytes);
+    if ((metadata.pages ?? 1) > 1) return [];
+    // Refused from the header, before `extract` or `trim` allocates anything. An
+    // empty list is the documented answer for "this source yields no crops", and
+    // `process` refuses the same source with the status the caller sees.
+    if (exceedsPixelBudget(metadata, maxPixels)) return [];
+    backdrop = await backdropColor(sharp, bytes);
+    source = await trimToSubject(sharp, bytes, backdrop);
+  } catch {
+    return [];
+  }
+
+  const outputs: RenditionOutput[] = [];
+  for (const spec of specs) {
+    const cut = await renderOne(sharp, source, spec, backdrop);
+    // One size failing is not a reason to keep the ones that worked: the srcset
+    // builder reads the same spec list either way, so a browser would be handed
+    // a key with no object behind it. A partial set is refused wholesale.
+    if (!cut) return [];
+    outputs.push({ spec, bytes: cut });
+  }
+  return outputs;
+}

package/src/server/pipeline/sharp.ts

@@ -0,0 +1,142 @@
+import type { StorageProblem } from '../../problems';
+import type { ImagePipeline, ProcessResult } from './port';
+import type { SharpMetadata, SharpModule } from './sharp-module';
+import { cutRenditions, isAnimatedSource, sharpFormatFor } from './sharp-renditions';
+
+/**
+ * The real pipeline: downscale, re-encode, and cut the crops — with `sharp`
+ * handed IN rather than imported (see `sharp-module.ts` for why).
+ *
+ * WHY THE SERVER RESIZES AT ALL, when a browser can do it for free. It can, and
+ * a browser-side resize is still worth having — the bytes never travel at full
+ * size. But it only covers callers that ARE browsers. An agent hands over
+ * whatever bytes it was given, with no device and no canvas, and until something
+ * resizes them a 2000px 1–2 MB PNG is served whole into a card ~165px wide. The
+ * choice is a dependency or unbounded bytes in the bucket, and the dependency is
+ * the host's to declare.
+ *
+ * WHAT IT WILL NOT DO, mirroring the browser profile's pass-throughs:
+ *
+ *   - **Enlarge.** A 300px photo is stored at 300px.
+ *   - **Return something bigger.** An already-optimized WebP can round-trip
+ *     larger; the size comparison keeps the original when it does.
+ *   - **Flatten an animation.** Animated sources are resized WITH their frames
+ *     and re-encoded in their own container rather than becoming a still WebP.
+ *
+ * It deliberately does NOT crop the uncropped object. Aspect ratio is preserved
+ * on every path (`fit: 'inside'`), because that object is the one a ZOOM shows:
+ * the whole photograph, margins and all. The crops are a separate set.
+ */
+
+export interface SharpPipelineConfig {
+  /** The `sharp` module itself. */
+  sharp: SharpModule;
+  /** Longest edge, in pixels, of the stored uncropped object. Default 1280. */
+  maxEdge?: number;
+  /** WebP quality, 0–100. Default 82. */
+  quality?: number;
+  /**
+   * Ceiling on the DECODED pixel count. A decode costs width × height × channels
+   * bytes, so a "decompression bomb" — a small file declaring enormous dimensions
+   * — is a way to exhaust the server's memory through an endpoint that otherwise
+   * looks like an 8 MB upload. The honest bound is on pixels, since that is what
+   * gets allocated. Default 50 megapixels.
+   */
+  maxPixels?: number;
+}
+
+/**
+ * 1280 is measured against the largest box the object is ever drawn into — a 4:3
+ * hero on a desktop viewport, with 2× headroom — not against the card, because a
+ * lightbox is exactly where somebody looks closely.
+ */
+const DEFAULTS = { maxEdge: 1280, quality: 82, maxPixels: 50_000_000 } as const;
+
+/** The refusals decided from the header alone. */
+function rejectUnprocessable(
+  metadata: SharpMetadata,
+  maxPixels: number,
+): StorageProblem | null {
+  const width = metadata.width ?? 0;
+  const height = metadata.height ?? 0;
+  if (width <= 0 || height <= 0) return 'image_unreadable';
+  // `pages` multiplies the cost of an animation: a 1000×1000 GIF with 200 frames
+  // allocates as much as a 200-megapixel still.
+  if (width * height * (metadata.pages ?? 1) > maxPixels) {
+    return 'image_dimensions_too_large';
+  }
+  return null;
+}
+
+export function createSharpImagePipeline(config: SharpPipelineConfig): ImagePipeline {
+  const { sharp } = config;
+  const maxEdge = config.maxEdge ?? DEFAULTS.maxEdge;
+  const quality = config.quality ?? DEFAULTS.quality;
+  const maxPixels = config.maxPixels ?? DEFAULTS.maxPixels;
+
+  /** Probe the header, or `null` when the bytes are not a decodable image. */
+  async function readMetadata(bytes: Uint8Array): Promise<SharpMetadata | null> {
+    try {
+      return await sharp(bytes).metadata();
+    } catch {
+      return null;
+    }
+  }
+
+  /** Resize and re-encode, or `null` if the codec refused partway through. */
+  async function encode(
+    bytes: Uint8Array,
+    animated: boolean,
+    declaredContentType: string,
+  ): Promise<Uint8Array | null> {
+    try {
+      const pipeline = sharp(bytes, animated ? { animated: true } : {}).resize({
+        width: maxEdge,
+        height: maxEdge,
+        fit: 'inside',
+        withoutEnlargement: true,
+      });
+      return animated
+        ? await pipeline.toFormat(sharpFormatFor(declaredContentType)).toBuffer()
+        : await pipeline.webp({ quality }).toBuffer();
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    name: 'sharp',
+    cutsRenditions: true,
+    process: async (bytes, declaredContentType): Promise<ProcessResult> => {
+      const metadata = await readMetadata(bytes);
+      if (!metadata) return { ok: false, problem: 'image_unreadable' };
+      const problem = rejectUnprocessable(metadata, maxPixels);
+      if (problem) return { ok: false, problem };
+
+      // Asked of the ANIMATED read: a still decode reports pages = 1 for a GIF
+      // that has twenty, and flattening one is the failure this guards.
+      const animated = await isAnimatedSource(sharp, bytes);
+      const encoded = await encode(bytes, animated, declaredContentType);
+      if (!encoded) return { ok: false, problem: 'image_unreadable' };
+
+      // A re-encode that gained bytes is not an optimization. `>=` and not `>` so
+      // a tie keeps the known-good original.
+      if (encoded.byteLength >= bytes.byteLength) {
+        return { ok: true, image: { bytes, contentType: declaredContentType } };
+      }
+      // An animation keeps its own container; everything else becomes WebP, which
+      // is both the smallest of the accepted formats and what a browser-side
+      // resize already produces, so the two uploaders converge.
+      return {
+        ok: true,
+        image: {
+          bytes: encoded,
+          contentType: animated ? declaredContentType : 'image/webp',
+        },
+      };
+    },
+    // The ceiling goes to BOTH halves: the writer runs them together, so a bound
+    // only `process` knew about bounded nothing (see sharp-renditions.ts).
+    cut: (bytes, specs) => cutRenditions(sharp, bytes, specs, maxPixels),
+  };
+}

package/src/server/read-body.ts

@@ -0,0 +1,42 @@
+/**
+ * Reading an upload body without ever trusting its declared size.
+ *
+ * Rejects up front when `content-length` already exceeds the cap, then
+ * accumulates the stream chunk by chunk and CANCELS it the moment the running
+ * total crosses — so an oversize upload can never force the process to allocate
+ * the whole payload before the 413. A chunked request sends no length at all,
+ * which is why the incremental half is not redundant.
+ *
+ * `null` means "too large". A missing body reads as empty (0 bytes), which the
+ * caller refuses the same way it refuses any empty file.
+ */
+export async function readBodyCapped(
+  request: Request,
+  maxBytes: number,
+): Promise<Uint8Array | null> {
+  const declaredLength = Number(request.headers.get('content-length'));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) return null;
+  if (!request.body) return new Uint8Array(0);
+
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(value);
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}

package/src/server/reclaim.ts

@@ -0,0 +1,240 @@
+import { hasRenditions, keyInScope, parseObjectKey, renditionKey } from '../keys';
+import type { RenditionSpec } from '../renditions';
+import type { StorageDriver } from './driver';
+
+/**
+ * Reclaiming the bytes behind a REPLACED object.
+ *
+ * When a photo is swapped, the superseded object used to stay in the bucket
+ * forever — nothing referenced it, nothing served it, nothing removed it. Every
+ * re-upload leaked one.
+ *
+ * WHY THIS IS NOT JUST `driver.delete(oldKey)`. A key can outlive the row that
+ * pointed at it, and some of those states are ones a person is ABOUT TO ACT ON:
+ * a duplicated row sharing one object, a soft-deleted row whose "restore" is
+ * expected to bring the photo back, a draft or a pending approval holding a key
+ * waiting to be published. Deleting the object would break the very next thing
+ * they do.
+ *
+ * Which states those are is the HOST'S question, not this package's — they are
+ * its tables. So they arrive as {@link StorageReferenceProbe}s: named predicates
+ * the reclaim consults before deleting anything. The package supplies the two
+ * things a host cannot get right by itself, and the reason this is not just a
+ * `delete` call:
+ *
+ *   - the whole SET goes, not just the object the row named. Deleting one key
+ *     would leak five crops per replaced photo — the same leak, one level down;
+ *   - a key outside the caller's SCOPE is never touched, whatever the probes say.
+ *     A probe answers "does anything of MINE reference this?", and that is true of
+ *     every other tenant's objects too — which is exactly how a scope-blind
+ *     reclaim deletes a neighbour's photo.
+ *
+ * Cleanup is best-effort BY CONSTRUCTION: it runs after the write it follows, and
+ * a failure is logged rather than raised. A store owner who successfully changed a
+ * photo must not see an error because a bucket delete timed out.
+ *
+ * ## The probe→purge window, stated plainly
+ *
+ * {@link deleteIfOrphaned} is read-validate-write: it consults every probe, then
+ * deletes. There is no claim-once and no transaction, so a concurrent request that
+ * ATTACHES the key between the last probe and the delete loses its object:
+ *
+ *   1. user B replaces product P's photo; the reclaim probes key `K` and finds
+ *      nothing referencing it;
+ *   2. concurrently user A, whose tab still shows `K`, duplicates P — the duplicate
+ *      row is written with `imageKey: K`;
+ *   3. the purge runs. `K` and its five crops are gone, and A's brand-new row points
+ *      at six objects that do not exist.
+ *
+ * This is inherent to ANY probe-based orphan reclaim; closing it needs refcounting,
+ * which is a different design and a host-side one (the count would live in the
+ * host's tables, beside the keys). What the package can do is two things, and it
+ * does both:
+ *
+ *   - the probes are read OUTSIDE the host's transaction, so the host has to order
+ *     the call correctly — after commit, and after any copy-on-write path has
+ *     landed. That rule is `ADOPTING.md` rule 3, and it is the actual fix;
+ *   - the window is made DISCOVERABLE rather than silent (see `confirmStillOrphaned`).
+ *     "The reclaim deleted the image I just attached" is otherwise a bug with no
+ *     log line anywhere, which is the worst shape a data-loss bug can have.
+ */
+
+/**
+ * One reason an object might still be needed, as a predicate over the host's own
+ * tables.
+ *
+ * `name` is not decoration: it is what the log line says when a reclaim is
+ * declined, which is the difference between "the bucket is growing" and "drafts
+ * are pinning objects".
+ */
+export interface StorageReferenceProbe {
+  name: string;
+  /** Does anything in this store still reference `key`, within `scope`? */
+  referenced(scope: string, key: string): Promise<boolean>;
+}
+
+/** Where a reclaim's own failures go. */
+export interface StorageLogger {
+  error(message: string): void;
+}
+
+export interface ReclaimDeps {
+  driver: StorageDriver;
+  probes: readonly StorageReferenceProbe[];
+  logger: StorageLogger;
+  unscopedKeys: 'accept' | 'reject';
+  specs: readonly RenditionSpec[];
+  keyPrefix: string;
+}
+
+/**
+ * Every object key a stored photo occupies: the key on the row plus the crops
+ * beside it — just the key itself for a photo stored alone.
+ *
+ * Read off the KEY, the same way the writer wrote it, so a reclaim cannot need a
+ * second record of what exists.
+ */
+export function objectKeysFor(
+  key: string,
+  specs: readonly RenditionSpec[],
+  keyPrefix: string,
+): string[] {
+  if (!hasRenditions(key, keyPrefix)) return [key];
+  return [
+    key,
+    ...specs
+      .map((spec) => renditionKey(key, spec.name, keyPrefix))
+      .filter((sibling): sibling is string => sibling !== null),
+  ];
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Delete the object behind `key` if — and only if — nothing references it any
+ * more. Safe to call with a key still in use, one that never existed, and `null`.
+ *
+ * Never throws: callers invoke it after a successful write and must not have
+ * their response changed by its outcome.
+ */
+export async function deleteIfOrphaned(
+  deps: ReclaimDeps,
+  scope: string,
+  key: string | null | undefined,
+): Promise<void> {
+  // A key this scheme did not mint is not ours to delete, and a malformed value
+  // must never reach a probe's query at all.
+  if (!key || !parseObjectKey(key, deps.keyPrefix)) return;
+  if (!keyInScope(key, scope, deps.unscopedKeys, deps.keyPrefix)) {
+    deps.logger.error(
+      `[storage] refused to reclaim ${key}: it does not belong to scope ${scope}`,
+    );
+    return;
+  }
+  try {
+    for (const probe of deps.probes) {
+      if (await probe.referenced(scope, key)) return;
+    }
+    await purge(deps, key);
+    await confirmStillOrphaned(deps, scope, key);
+  } catch (error) {
+    // The write this followed already succeeded. Logged through the host's own
+    // logger so a bucket that starts refusing deletes is discoverable rather than
+    // silently accumulating objects.
+    deps.logger.error(`[storage] could not reclaim ${key}: ${errorText(error)}`);
+  }
+}
+
+/**
+ * Re-ask the probes AFTER the purge, and log if the answer changed.
+ *
+ * This does NOT close the probe→purge window — nothing here can undelete an
+ * object, and pretending otherwise would be worse than the window itself. What it
+ * does is convert the failure from silent to reported: a row now points at six
+ * objects that no longer exist, and without this line the only trace anywhere is a
+ * store owner eventually noticing a broken image.
+ *
+ * That is the same bargain the rest of this file makes — a reclaim can only report
+ * — applied to the one hazard the design cannot remove.
+ *
+ * Cheap by construction, and deliberately so: it runs only when a purge ACTUALLY
+ * happened (the branch where the key was orphaned AND deleted, not the common one
+ * where a probe claimed it or the key was null), and not at all for a host that
+ * passes `references: []`, which has no window to detect.
+ */
+async function confirmStillOrphaned(
+  deps: ReclaimDeps,
+  scope: string,
+  key: string,
+): Promise<void> {
+  for (const probe of deps.probes) {
+    if (await probe.referenced(scope, key)) {
+      deps.logger.error(
+        `[storage] reclaimed ${key} but ${probe.name} references it now: ` +
+          'it was attached between the probe and the delete, so that row points at ' +
+          'objects that no longer exist',
+      );
+      return;
+    }
+  }
+}
+
+/** Delete every member of `key`'s set, unconditionally. */
+async function purge(deps: ReclaimDeps, key: string): Promise<void> {
+  await Promise.all(
+    objectKeysFor(key, deps.specs, deps.keyPrefix).map((object) =>
+      deps.driver.delete(object),
+    ),
+  );
+}
+
+/**
+ * Reclaim every key a write SUPERSEDED: those present before and absent after.
+ *
+ * Order is irrelevant and each is independent, so they run together. A key that
+ * appeared twice before the write is reclaimed once.
+ */
+export async function deleteReplaced(
+  deps: ReclaimDeps,
+  scope: string,
+  before: readonly (string | null | undefined)[],
+  after: readonly (string | null | undefined)[],
+): Promise<void> {
+  const kept = new Set(after.filter((key): key is string => typeof key === 'string'));
+  const superseded = [
+    ...new Set(
+      before.filter((key): key is string => typeof key === 'string' && !kept.has(key)),
+    ),
+  ];
+  await Promise.all(superseded.map((key) => deleteIfOrphaned(deps, scope, key)));
+}
+
+/**
+ * Discard objects this request itself just minted — no probes consulted.
+ *
+ * For a write that fails AFTER storing its bytes (a spent quota, a duplicate
+ * name): nothing can reference a key nobody has been told about yet, so asking
+ * the host's tables about it would be a round trip whose answer is known. Still
+ * scope-checked, and still silent about its own failures.
+ */
+export async function discardMinted(
+  deps: ReclaimDeps,
+  scope: string,
+  keys: readonly (string | null | undefined)[],
+): Promise<void> {
+  const own = keys.filter(
+    (key): key is string =>
+      typeof key === 'string' && keyInScope(key, scope, deps.unscopedKeys, deps.keyPrefix),
+  );
+  await Promise.all(
+    own.map(async (key) => {
+      try {
+        await purge(deps, key);
+      } catch (error) {
+        deps.logger.error(`[storage] could not discard ${key}: ${errorText(error)}`);
+      }
+    }),
+  );
+}