@proteinjs/db-file 1.8.4 → 1.9.1

package/src/FileCopyForOthers.ts

@@ -0,0 +1,71 @@
+import { Loadable, SourceRepository } from '@proteinjs/reflection';
+import { File } from './tables/FileTable';
+
+/**
+ * What a file becomes when it is served to someone who is not its owner.
+ *
+ * A file's bytes are the owner's, kept exactly as they arrived. When a read resolves through the
+ * shared-content leg instead of the owner's own scope (`FileStorage.getFile`: a share recipient
+ * reading a file a shared row references), `FileStorage` serves a COPY made by the one registered
+ * maker — the package that knows the file's format decides what leaves in it (a picture's
+ * location, say, does not). The copy is made once per file, stored as its own `File` in the
+ * owner's scope and named on the original's row (`File.copyForOthers`), so every later read by
+ * anyone but the owner serves the same bytes without remaking them; it is dropped when the
+ * original's bytes change and deleted with the original.
+ *
+ * Dependency direction is the {@link FileReachabilityResolver} pattern: the seam lives here in
+ * db-file, the one implementation lives in the package that knows media, discovered through the
+ * SourceRepository. With no maker registered, everyone is served the original.
+ */
+export interface FileCopyForOthers extends Loadable {
+  /**
+   * Whether this file is served to others through a copy at all — decided from the row alone,
+   * never from its bytes (a plain document serves as itself and costs no read). True means
+   * {@link make} is called once, with the original's bytes, and its answer is what others get.
+   */
+  appliesTo(file: File): boolean;
+  /** The bytes served to anyone but the owner, made from the original's. Throws when no copy can be made — the read then fails rather than serving the original. */
+  make(file: File, bytes: Buffer): Promise<Buffer>;
+}
+
+export const getFileCopyForOthers = (): FileCopyForOthers | undefined =>
+  SourceRepository.get().object<FileCopyForOthers>('@proteinjs/db-file/FileCopyForOthers');
+
+/**
+ * What a non-owner's read becomes when the registered maker could not make a copy: the file is
+ * served to no one but its owner. The seam's own cause, thrown by `FileStorage` in place of
+ * whatever the maker threw (the maker's own one-line reason kept as `reason`) and answered by
+ * `FileStorage` itself, once for every door — the browser service, `GET /file/:id`, a server-side
+ * reader — as a 404 `ServiceRefusal` saying only `File not found`, so a door never meets it: a
+ * deliberate refusal every door tells from a failure the same way. Its message and `reason` stay
+ * on the server (`FileStorage` logs them at WARN); a caller reads the words a missing file gets.
+ * Read by shape ({@link FileCopyRefused.is}), so it holds across duplicate copies of this package.
+ */
+export class FileCopyRefused extends Error {
+  private static readonly NAME = 'FileCopyRefused';
+  /** Free text that reaches a message is one line and bounded. */
+  private static readonly MAX_REASON_CHARS = 300;
+  readonly fileId: string;
+  readonly reason: string;
+
+  constructor(fileId: string, cause: unknown) {
+    const reason = FileCopyRefused.plain(cause);
+    super(`File ${fileId} is not available to anyone but its owner${reason ? `: ${reason}` : ''}`);
+    this.name = FileCopyRefused.NAME;
+    Object.setPrototypeOf(this, FileCopyRefused.prototype);
+    this.fileId = fileId;
+    this.reason = reason;
+  }
+
+  static is(error: unknown): error is FileCopyRefused {
+    return (error as { name?: unknown } | null | undefined)?.name === FileCopyRefused.NAME;
+  }
+
+  private static plain(cause: unknown): string {
+    const message = cause instanceof Error ? cause.message : typeof cause === 'string' ? cause : '';
+    const line = message.replace(/\s+/g, ' ').trim();
+    return line.length > FileCopyRefused.MAX_REASON_CHARS
+      ? `${line.slice(0, FileCopyRefused.MAX_REASON_CHARS)}…`
+      : line;
+  }
+}

package/src/FileStorage.ts

@@ -1,11 +1,21 @@
-import { ScopedRecord, getScopedDb, getScopedDbAsSystem } from '@proteinjs/user';
-import { File } from './tables/FileTable';
+import { Reference, getDbAsSystem } from '@proteinjs/db';
+import { ScopedRecord, UserRepo, getScopedDb, getScopedDbAsSystem } from '@proteinjs/user';
+import { File, FileTable } from './tables/FileTable';
 import { tables } from './tables/tables';
 import { FileStorageService, getFileStorageService } from './services/FileStorageService';
 import { FileStorageDriver } from './FileStorageDriver';
 import { getFileReachabilityResolvers } from './FileReachabilityResolver';
+import { FileCopyRefused, getFileCopyForOthers } from './FileCopyForOthers';
+import {
+  FILE_VARIANT_KINDS,
+  FileVariant,
+  FileVariantKind,
+  FileVariantNotMade,
+  getFileVariantMaker,
+} from './FileVariantMaker';
 import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import { Logger } from '@proteinjs/logger';
+import { ServiceRefusal } from '@proteinjs/service';
 import { DbFileStorageDriver } from './DbFileStorageDriver';
 
 /**
@@ -29,12 +39,15 @@ export interface DefaultFileStorageDriverFactory extends Loadable {
  */
 export class FileStorage implements FileStorageService {
   private static driver: FileStorageDriver;
+  /** The read path's derivations running in this process, by file and kind — see {@link deriveOnce}. */
+  private static derivations = new Map<string, Promise<string | undefined>>();
 
   public serviceMetadata = {
     auth: {
       allUsers: true,
     },
   };
+  private logger = new Logger({ name: this.constructor.name });
 
   /**
    * The `FileStorageDriver` for this process — provided by the `DefaultFileStorageDriverFactory`
@@ -77,11 +90,16 @@ export class FileStorage implements FileStorageService {
    * Retrieves the metadata of a given file — THE file-read access decision every serving path
    * derives from (`/file/:id`, signed-URL minting, the browser service).
    *
-   * Two legs: the caller's own file resolves by the SCOPED read; when that misses, the
-   * shared-content leg asks the registered {@link FileReachabilityResolver}s whether the caller
-   * can read a row that REFERENCES the file (a shared thought's media node) — content access
-   * confers file access, through the content's own grant-filtered read, never by widening file
-   * scope. No resolver vouching means the miss stands. Reads only: writes/deletes stay scoped.
+   * Three legs, cheapest first: the caller's own file resolves by the SCOPED read. When that
+   * misses, the derived leg: a VARIANT the seam made (`File.variantOf`) is readable by whoever
+   * can read its original — this same decision, asked of the original — so a variant derived
+   * after the content was placed (no content row names it) is reachable by exactly the readers
+   * of the file it was made from; one system point read decides whether the row is a variant at
+   * all. Last, the shared-content leg asks the registered {@link FileReachabilityResolver}s
+   * whether the caller can read a row that REFERENCES the file (a shared thought's media node) —
+   * content access confers file access, through the content's own grant-filtered read, never by
+   * widening file scope. No leg vouching means the miss stands. Reads only: writes/deletes stay
+   * scoped.
    * @param fileId - The `id` of the file.
    * @returns The file metadata, or `undefined` when the caller can neither own nor reach it.
    */
@@ -92,15 +110,84 @@ export class FileStorage implements FileStorageService {
       return file;
     }
 
+    const row = await getScopedDbAsSystem().get(tables.File, { id: fileId });
+    if (!row) {
+      return undefined as unknown as File;
+    }
+    if (row.variantOf?._id) {
+      // A variant's reachability is its original's — the copy for others carries no `variantOf`,
+      // so its own id stays nobody's but the owner's.
+      return (await this.getFile(row.variantOf._id)) ? row : (undefined as unknown as File);
+    }
+
     for (const resolver of getFileReachabilityResolvers()) {
       if (await resolver.canReadViaReference(fileId)) {
         // Reachability established through the caller's grant-filtered content read — the row
         // itself lives in the owner's scope, so it is served via system read.
-        return await getScopedDbAsSystem().get(tables.File, { id: fileId });
+        return row;
       }
     }
 
-    return file;
+    return undefined as unknown as File;
+  }
+
+  /**
+   * The variant of this kind of a file — the derived File the row names, or one made now, ONCE,
+   * by the registered {@link FileVariantMaker} (the read path's door, behind
+   * `GET /file/:id/variant/:kind`: a file made before the seam existed, or by a producer that did
+   * not derive it, gets its variant on the first request from a surface that draws it; every
+   * later request is served the same row without the maker). Server-only, like `getSignedUrl` —
+   * the browser asks by URL, never by service call. Access is the original's ({@link getFile});
+   * the variant is stored as the owner's own File whoever's read made it, carrying the original's
+   * provenance ({@link FileTable.provenanceColumns}), and is served like any File afterwards —
+   * with the same non-owner copy rule.
+   * @returns The variant's File row, or `undefined` when the caller cannot read the original, no
+   *          maker is registered, the maker does not apply to this file for this kind, or the
+   *          maker could not make it of these bytes (the consumer then draws the original).
+   */
+  async getVariant(fileId: string, kind: FileVariantKind): Promise<File | undefined> {
+    const file = await this.getFile(fileId);
+    if (!file) {
+      return undefined;
+    }
+    const named = file[kind]?._id;
+    if (named) {
+      return await getScopedDbAsSystem().get(tables.File, { id: named });
+    }
+    const maker = getFileVariantMaker();
+    if (!maker || !maker.appliesTo(file, kind)) {
+      return undefined;
+    }
+    const variantId = await this.deriveOnce(file, kind);
+    return variantId ? await getScopedDbAsSystem().get(tables.File, { id: variantId }) : undefined;
+  }
+
+  /**
+   * Make and store every variant the registered maker applies to, with the original's bytes in
+   * hand (the ingest's door — one decode of bytes just stored, never a re-read). Each is named on
+   * the row and carries the original's provenance ({@link FileTable.provenanceColumns}); a kind
+   * the maker does not apply to is left unset (the read path may derive it later if the maker's
+   * rule changes). With no maker registered nothing is made.
+   * @returns The caller's file row with each variant made here named on it (the row as the caller
+   *          holds it, not a re-read — an unset column stays unset), and the variant Files made.
+   */
+  async deriveVariants(
+    file: File,
+    bytes: Buffer
+  ): Promise<{ file: File; variants: Partial<Record<FileVariantKind, File>> }> {
+    const maker = getFileVariantMaker();
+    const variants: Partial<Record<FileVariantKind, File>> = {};
+    const named: Partial<Pick<File, FileVariantKind>> = {};
+    if (maker) {
+      for (const kind of FILE_VARIANT_KINDS) {
+        if (!file[kind]?._id && maker.appliesTo(file, kind)) {
+          const variantId = await this.makeVariant(file, kind, bytes);
+          variants[kind] = await getScopedDbAsSystem().get(tables.File, { id: variantId });
+          named[kind] = new Reference<File>(tables.File.name, variantId);
+        }
+      }
+    }
+    return { file: { ...file, ...named }, variants };
   }
 
   /**
@@ -111,37 +198,65 @@ export class FileStorage implements FileStorageService {
    * exactly as reachable as the row that names them. The gate lives here because this is the
    * browser-facing service boundary (`FileStorageService` is `allUsers`) and the driver byte ops
    * below are deliberately unscoped. Server-side doors that make their OWN documented access
-   * decision (the avatar route, issue/ticket attachment doors) read bytes through
-   * `FileStorage.getDriver()` instead.
+   * decision (an attachment door keyed by a record's linkage, say) serve through
+   * {@link getAuthorizedFileData} — the same owner-or-copy bytes, without this gate.
+   *
+   * WHICH bytes: the owner's read serves the original; anyone else's — a read that reached the
+   * file through the shared-content leg — serves the {@link FileCopyForOthers} copy
+   * ({@link servedFileId}): the same substitution `getSignedUrl` makes, so the proxy route, the
+   * signed-URL route and every server-side reader of this door agree.
    * @param fileId - The `id` of the file.
    * @returns The file data as a single string.
-   * @throws When the file row does not exist or is not readable by the caller — the same named
-   *         miss either way, so existence is not leaked to unauthorized callers.
+   * @throws ServiceRefusal (404, `File not found`) when the file row does not exist or is not
+   *         readable by the caller, and when the caller is not the owner and no copy can be made
+   *         ({@link servedFileId}) — ONE answer for all three ({@link notFound}), so no door tells
+   *         a missing file from one this caller may not have.
    */
   async getFileData(fileId: string): Promise<string> {
     const file = await this.getFile(fileId);
     if (!file) {
-      throw new Error(`File not found: ${fileId}`);
+      throw FileStorage.notFound();
     }
 
-    return await FileStorage.getDriver().getFileData(fileId);
+    return await FileStorage.getDriver().getFileData(await this.servedFileId(file));
+  }
+
+  /**
+   * The bytes THIS caller is served for a file a server-side door has ALREADY decided the caller
+   * may read, by its own documented rule (an attachment door keyed by a record's linkage, say —
+   * a read neither the caller's scope nor a {@link FileReachabilityResolver} would open). The
+   * door vouches for access; this decides WHICH bytes, exactly as {@link getFileData} does: the
+   * original for the file's owner, the {@link FileCopyForOthers} copy for anyone else — the same
+   * copy, made once and named on the row, that every other door serves them. Server-only (not
+   * part of the browser-facing `FileStorageService`), so the rule that opens the file stays the
+   * door's.
+   * @param file - The file's row, as the door read it (its `scope` names the owner).
+   * @returns The file data as a single string.
+   * @throws ServiceRefusal (404) when the caller is not the owner and no copy can be made — the same
+   *         refusal every door gives ({@link servedFileId}).
+   */
+  async getAuthorizedFileData(file: File): Promise<string> {
+    return await FileStorage.getDriver().getFileData(await this.servedFileId(file));
   }
 
   /**
    * Mint a short-lived, read-only URL for the file's bytes (server-only; not part of the
    * browser-facing `FileStorageService`). A signed URL is a bearer capability, so minting
    * verifies the caller can read the file row (the two-legged {@link getFile} read — own scope
-   * or shared-content reachability) before signing.
+   * or shared-content reachability) before signing — and signs the bytes THAT caller is served:
+   * the original for the owner, the {@link FileCopyForOthers} copy for anyone else.
    * @param fileId - The `id` of the file.
    * @param options.ttlMs - How long the URL stays valid; the driver applies its default when omitted.
    * @returns The signed URL, or `undefined` when the driver has no external URL space
    *          (`DbFileStorageDriver`) — the caller then serves bytes through the proxy route.
-   * @throws When the file row does not exist or is not readable by the caller.
+   * @throws ServiceRefusal (404, `File not found`) when the file row does not exist or is not
+   *         readable by the caller, and when the caller is not the owner and no copy can be made —
+   *         the one answer {@link getFileData} gives ({@link notFound}).
    */
   async getSignedUrl(fileId: string, options?: { ttlMs?: number }): Promise<string | undefined> {
     const file = await this.getFile(fileId);
     if (!file) {
-      throw new Error(`File not found: ${fileId}`);
+      throw FileStorage.notFound();
     }
 
     const driver = FileStorage.getDriver();
@@ -149,7 +264,7 @@ export class FileStorage implements FileStorageService {
       return undefined;
     }
 
-    return await driver.getSignedUrl(fileId, options);
+    return await driver.getSignedUrl(await this.servedFileId(file), options);
   }
 
   /**
@@ -159,6 +274,10 @@ export class FileStorage implements FileStorageService {
    * (the same authorization a scoped row update enforces). Deliberately STRICTER than
    * {@link getFileData}: the {@link FileReachabilityResolver} leg widens READS only, so a
    * share recipient who can read the bytes still cannot write them.
+   *
+   * New bytes make every derived File stale — the copy others were served, the preview, the
+   * stage variant: each is dropped here — the row forgets it, then its row (and, through the
+   * delete watcher, its bytes) goes — and the next read that wants one makes a fresh one.
    * @param fileId - The `id` of the file.
    * @param data - The new data string to replace the existing data.
    * @throws When the file row does not exist or is not writable by the caller — the same named
@@ -172,6 +291,7 @@ export class FileStorage implements FileStorageService {
     }
 
     await FileStorage.getDriver().updateFileData(fileId, data);
+    await this.dropDerivedFiles(file);
   }
 
   /**
@@ -199,4 +319,242 @@ export class FileStorage implements FileStorageService {
     const db = getScopedDb();
     await db.delete(tables.File, { id: fileId });
   }
+
+  /**
+   * The id whose bytes this caller is served: the file's own for its owner, or for a file with
+   * no maker (or one the maker does not apply to); otherwise the {@link FileCopyForOthers} copy —
+   * the one already named on the row, or made now, once, and named for every later read.
+   *
+   * ONE REFUSAL, EVERY DOOR: when no copy can be made (the seam's {@link FileCopyRefused}), the file
+   * is served to no one but its owner, so to this caller it is not there — a
+   * `ServiceRefusal(404, 'File not found')`, thrown here so the browser service, `GET /file/:id` in
+   * both its shapes and the server-side door answer the same by construction: the service router
+   * answers 404 `{ error: 'File not found' }`, the executor logs one WARN (a refusal, never a
+   * failure), the route answers `404 File not found` — the same answer, at every door, as a row the
+   * caller cannot read ({@link notFound}). The refusal carries no reason, file id or owner: the
+   * maker's reason is the server's, logged here in one WARN, so nothing a caller reads tells a
+   * refused copy from a file that is not there.
+   */
+  private async servedFileId(file: File): Promise<string> {
+    if (this.ownedByCaller(file)) {
+      return file.id;
+    }
+    if (file.copyForOthers?._id) {
+      return file.copyForOthers._id;
+    }
+    const maker = getFileCopyForOthers();
+    if (!maker || !maker.appliesTo(file)) {
+      return file.id;
+    }
+    try {
+      return await this.makeCopyForOthers(file);
+    } catch (error) {
+      if (FileCopyRefused.is(error)) {
+        this.logger.warn({
+          message: 'No copy of a file can be made for anyone but its owner; refused as not found',
+          obj: { fileId: error.fileId, reason: error.reason },
+        });
+        throw FileStorage.notFound();
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Whether the caller is the file's owner — the row's `scope` is the owner (the scoped read
+   * {@link getFile} makes first is exactly `scope = the caller`), so a row {@link getFile} handed
+   * back whose scope is someone else's was reached through the shared-content leg. A row with no
+   * owner recorded serves as itself: there is no one to withhold it from.
+   */
+  private ownedByCaller(file: File): boolean {
+    return !file.scope || file.scope === new UserRepo().getUser().id;
+  }
+
+  /**
+   * Makes the copy (the maker's bytes, from the original's), stores it as a File in the owner's
+   * scope — the original's name, type, dimensions and provenance ({@link provenanceOf}) on it —
+   * and names it on the original's row. Two non-owners reading at once may both get here:
+   * the row's word wins — decided in ONE transaction (the read of the row and the write of its
+   * word together, so racing writers are serialized and the loser's transaction, retried, finds
+   * the winner named) — and a copy that lost is deleted after the commit, the first is served.
+   */
+  private async makeCopyForOthers(file: File): Promise<string> {
+    const maker = getFileCopyForOthers()!;
+    const driver = FileStorage.getDriver();
+    const original = Buffer.from(await driver.getFileData(file.id), 'base64');
+    let copyBytes: Buffer;
+    try {
+      copyBytes = await maker.make(file, original);
+    } catch (cause) {
+      // The maker's contract: a throw means no copy can be made — the file is the owner's alone.
+      throw new FileCopyRefused(file.id, cause);
+    }
+    // As system, in the OWNER's scope: the copy is the owner's file (their storage, their purge).
+    const system = getDbAsSystem();
+    const copy = await system.insert(tables.File, {
+      name: file.name,
+      type: file.type,
+      size: copyBytes.length,
+      ...(file.width !== undefined && file.width !== null ? { width: file.width } : {}),
+      ...(file.height !== undefined && file.height !== null ? { height: file.height } : {}),
+      ...(file.durationMs !== undefined && file.durationMs !== null ? { durationMs: file.durationMs } : {}),
+      ...this.provenanceOf(file),
+      scope: file.scope,
+    });
+    await driver.createFile(copy, copyBytes.toString('base64'));
+
+    const named = await system.runTransaction(async () => {
+      const current = await system.get(tables.File, { id: file.id });
+      if (current?.copyForOthers?._id) {
+        return current.copyForOthers._id;
+      }
+      await system.update(tables.File, { id: file.id, copyForOthers: new Reference<File>(tables.File.name, copy.id) });
+      return copy.id;
+    });
+    if (named !== copy.id) {
+      // Outside the transaction: the row's delete takes the bytes with it (the delete watcher), a
+      // side effect that must not ride a transaction the runner may retry.
+      await system.delete(tables.File, { id: copy.id });
+    }
+    return named;
+  }
+
+  /**
+   * The read path's derivation, ONCE per file and kind at a time in this process: the readers
+   * that ask for the same absent variant while one derives (a shared document opened by many on
+   * one tick — every face asks the same URL) wait for that derivation's answer instead of each
+   * reading the original, encoding it and storing an object the row's word would then discard.
+   * Across processes the row's word in one transaction ({@link makeVariant}) still decides: this
+   * bounds the cost, that bounds the outcome. A maker that cannot make the variant of these
+   * bytes (a picture its decoder cannot read) answers `undefined` — nothing is stored, the reader
+   * draws the file itself, the next reader asks again — said in the log, never as a failed read;
+   * any other failure (the store, the database) is the reader's as it would be for any File.
+   */
+  private deriveOnce(file: File, kind: FileVariantKind): Promise<string | undefined> {
+    const key = `${file.id}:${kind}`;
+    const running = FileStorage.derivations.get(key);
+    if (running) {
+      return running;
+    }
+    const derivation = (async () => {
+      const original = Buffer.from(await FileStorage.getDriver().getFileData(file.id), 'base64');
+      try {
+        return await this.makeVariant(file, kind, original);
+      } catch (error) {
+        if (!FileVariantNotMade.is(error)) {
+          throw error;
+        }
+        new Logger({ name: 'FileStorage' }).warn({
+          message: `No ${kind} variant could be made of file ${file.id}; the file itself is served`,
+          obj: { reason: error.reason },
+        });
+        return undefined;
+      }
+    })().finally(() => FileStorage.derivations.delete(key));
+    FileStorage.derivations.set(key, derivation);
+    return derivation;
+  }
+
+  /**
+   * Makes the variant (the maker's answer from the original's bytes), stores it as a File in the
+   * OWNER's scope naming its original and carrying the original's provenance ({@link provenanceOf}
+   * — the maker answers the bytes, their type and their dimensions, never where they came from),
+   * and names it on the original's row. Two readers may derive
+   * the same kind at once: the row's word wins — decided in ONE transaction, exactly as the copy
+   * for others is named — and the variant that lost is deleted after the commit. The maker's own
+   * failure (it could not make the variant of these bytes) is thrown as {@link FileVariantNotMade}
+   * with the maker's reason, so the doors can tell it from a failure of the store or the database;
+   * nothing is stored on it.
+   * @returns The id of the variant the row names.
+   */
+  private async makeVariant(file: File, kind: FileVariantKind, bytes: Buffer): Promise<string> {
+    const maker = getFileVariantMaker()!;
+    const driver = FileStorage.getDriver();
+    let made: FileVariant;
+    try {
+      made = await maker.make(file, bytes, kind);
+    } catch (cause) {
+      // The maker's contract: a throw means no variant can be made of these bytes.
+      throw new FileVariantNotMade(file.id, kind, cause);
+    }
+    // As system, in the OWNER's scope: the variant is the owner's file (their storage, their purge).
+    const system = getDbAsSystem();
+    const variant = await system.insert(tables.File, {
+      name: `(${kind}) ${file.name}`,
+      type: made.type,
+      size: made.bytes.length,
+      ...(made.width !== undefined ? { width: made.width } : {}),
+      ...(made.height !== undefined ? { height: made.height } : {}),
+      ...this.provenanceOf(file),
+      variantOf: new Reference<File>(tables.File.name, file.id),
+      scope: file.scope,
+    });
+    await driver.createFile(variant, made.bytes.toString('base64'));
+
+    const named = await system.runTransaction(async () => {
+      const current = await system.get(tables.File, { id: file.id });
+      if (current?.[kind]?._id) {
+        return current[kind]!._id!;
+      }
+      await system.update(tables.File, { id: file.id, [kind]: new Reference<File>(tables.File.name, variant.id) });
+      return variant.id;
+    });
+    if (named !== variant.id) {
+      // Outside the transaction: the row's delete takes the bytes with it (the delete watcher), a
+      // side effect that must not ride a transaction the runner may retry.
+      await system.delete(tables.File, { id: variant.id });
+    }
+    return named;
+  }
+
+  /**
+   * The row forgets each derived File first (nothing serves a copy or a variant the row no longer
+   * names), then their rows go — the bytes with them, through the delete watcher: the copy for
+   * others and every variant kind, one rule.
+   */
+  private async dropDerivedFiles(file: File): Promise<void> {
+    const seats: Array<'copyForOthers' | FileVariantKind> = ['copyForOthers', ...FILE_VARIANT_KINDS];
+    const stale = seats.filter((seat) => !!file[seat]?._id);
+    if (stale.length === 0) {
+      return;
+    }
+    const system = getDbAsSystem();
+    const forgotten: Partial<File> & { id: string } = { id: file.id };
+    for (const seat of stale) {
+      forgotten[seat] = null;
+    }
+    await system.update(tables.File, forgotten);
+    for (const seat of stale) {
+      await system.delete(tables.File, { id: file[seat]!._id! });
+    }
+  }
+
+  /**
+   * The provenance a derived File carries — its original's, column for column, as the table names
+   * them ({@link FileTable.provenanceColumns}): a rendition of the bytes came to exist the way the
+   * bytes did, from where they did, under the rights they carry. Only what the row holds is
+   * copied, so a row with no provenance derives rows with none — nothing is invented. A row that
+   * is itself derived already carries its original's, so a derivation of it carries the same.
+   */
+  private provenanceOf(file: File): Partial<File> {
+    const provenance: Partial<File> = {};
+    for (const column of FileTable.provenanceColumns) {
+      const value = file[column];
+      if (value !== undefined && value !== null) {
+        Object.assign(provenance, { [column]: value });
+      }
+    }
+    return provenance;
+  }
+
+  /**
+   * THE answer a byte door gives a caller who does not get the file's bytes — a row that is not
+   * there, one this caller cannot read, or a copy that cannot be made for them: a 404 refusal in
+   * the same words every time, never the id, so the answer reveals nothing about existence (the
+   * service router sends `{ error: 'File not found' }`, the executor logs it at WARN, the routes
+   * send `404 File not found`).
+   */
+  private static notFound(): ServiceRefusal {
+    return new ServiceRefusal(404, 'File not found');
+  }
 }

package/src/FileStorageDriver.ts

@@ -1,4 +1,5 @@
 import { File } from './tables/FileTable';
+import type { FileStorageError } from './FileStorageError';
 
 /**
  * Byte store behind `FileStorage`.
@@ -7,6 +8,17 @@ import { File } from './tables/FileTable';
  * file's true bytes — for text and binary files alike. Drivers own their at-rest representation,
  * with one hard requirement: a driver that serves blobs directly to clients (`getSignedUrl`)
  * MUST store the true bytes at rest, because clients read its objects without any decode step.
+ *
+ * Error contract: a failed byte operation throws a {@link FileStorageError} — a code, a plain
+ * message and the store's HTTP status where it has one — and NEVER the store client's own error
+ * object or anything hanging off one (a request config, a request, a response, headers, a signed
+ * URL): a client's error holds the request it made, and that request holds the driver's
+ * credentials, so an application logging what it caught would write a live credential. Bytes that
+ * are not there are reported as the `not-found` code on every read and overwrite, so callers
+ * branch on one thing whichever driver is behind them (`deleteFile` alone treats missing bytes as
+ * success — see its contract). A driver whose store IS the application's database
+ * (`DbFileStorageDriver`) lets the database layer's own errors through unchanged: they are
+ * already that layer's owned errors, and a transaction runner must see them to retry.
  */
 export interface FileStorageDriver {
   createFile(file: File, fileData: string): Promise<void>;