@proteinjs/db-file 1.8.4 → 1.9.1

package/dist/src/FileStorage.js

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -35,14 +46,28 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileStorage = exports.getFileStorage = void 0;
+var db_1 = require("@proteinjs/db");
 var user_1 = require("@proteinjs/user");
+var FileTable_1 = require("./tables/FileTable");
 var tables_1 = require("./tables/tables");
 var FileStorageService_1 = require("./services/FileStorageService");
 var FileReachabilityResolver_1 = require("./FileReachabilityResolver");
+var FileCopyForOthers_1 = require("./FileCopyForOthers");
+var FileVariantMaker_1 = require("./FileVariantMaker");
 var reflection_1 = require("@proteinjs/reflection");
 var logger_1 = require("@proteinjs/logger");
+var service_1 = require("@proteinjs/service");
 var DbFileStorageDriver_1 = require("./DbFileStorageDriver");
 /**
  * A convenience factory function so code using this is portable (can be used in server or browser).
@@ -64,6 +89,7 @@ var FileStorage = /** @class */ (function () {
                 allUsers: true,
             },
         };
+        this.logger = new logger_1.Logger({ name: this.constructor.name });
     }
     /**
      * The `FileStorageDriver` for this process — provided by the `DefaultFileStorageDriverFactory`
@@ -114,44 +140,158 @@ var FileStorage = /** @class */ (function () {
      * 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.
      */
     FileStorage.prototype.getFile = function (fileId) {
+        var _a;
         return __awaiter(this, void 0, void 0, function () {
-            var db, file, _i, _a, resolver;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
+            var db, file, row, _i, _b, resolver;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0:
                         db = (0, user_1.getScopedDb)();
                         return [4 /*yield*/, db.get(tables_1.tables.File, { id: fileId })];
                     case 1:
-                        file = _b.sent();
+                        file = _c.sent();
                         if (file) {
                             return [2 /*return*/, file];
                         }
-                        _i = 0, _a = (0, FileReachabilityResolver_1.getFileReachabilityResolvers)();
-                        _b.label = 2;
+                        return [4 /*yield*/, (0, user_1.getScopedDbAsSystem)().get(tables_1.tables.File, { id: fileId })];
                     case 2:
-                        if (!(_i < _a.length)) return [3 /*break*/, 6];
-                        resolver = _a[_i];
+                        row = _c.sent();
+                        if (!row) {
+                            return [2 /*return*/, undefined];
+                        }
+                        if (!((_a = row.variantOf) === null || _a === void 0 ? void 0 : _a._id)) return [3 /*break*/, 4];
+                        return [4 /*yield*/, this.getFile(row.variantOf._id)];
+                    case 3: 
+                    // 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 [2 /*return*/, (_c.sent()) ? row : undefined];
+                    case 4:
+                        _i = 0, _b = (0, FileReachabilityResolver_1.getFileReachabilityResolvers)();
+                        _c.label = 5;
+                    case 5:
+                        if (!(_i < _b.length)) return [3 /*break*/, 8];
+                        resolver = _b[_i];
                         return [4 /*yield*/, resolver.canReadViaReference(fileId)];
+                    case 6:
+                        if (_c.sent()) {
+                            // 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 [2 /*return*/, row];
+                        }
+                        _c.label = 7;
+                    case 7:
+                        _i++;
+                        return [3 /*break*/, 5];
+                    case 8: return [2 /*return*/, undefined];
+                }
+            });
+        });
+    };
+    /**
+     * 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).
+     */
+    FileStorage.prototype.getVariant = function (fileId, kind) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function () {
+            var file, named, maker, variantId, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0: return [4 /*yield*/, this.getFile(fileId)];
+                    case 1:
+                        file = _c.sent();
+                        if (!file) {
+                            return [2 /*return*/, undefined];
+                        }
+                        named = (_a = file[kind]) === null || _a === void 0 ? void 0 : _a._id;
+                        if (!named) return [3 /*break*/, 3];
+                        return [4 /*yield*/, (0, user_1.getScopedDbAsSystem)().get(tables_1.tables.File, { id: named })];
+                    case 2: return [2 /*return*/, _c.sent()];
                     case 3:
-                        if (!_b.sent()) return [3 /*break*/, 5];
-                        return [4 /*yield*/, (0, user_1.getScopedDbAsSystem)().get(tables_1.tables.File, { id: fileId })];
-                    case 4: 
-                    // 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 [2 /*return*/, _b.sent()];
+                        maker = (0, FileVariantMaker_1.getFileVariantMaker)();
+                        if (!maker || !maker.appliesTo(file, kind)) {
+                            return [2 /*return*/, undefined];
+                        }
+                        return [4 /*yield*/, this.deriveOnce(file, kind)];
+                    case 4:
+                        variantId = _c.sent();
+                        if (!variantId) return [3 /*break*/, 6];
+                        return [4 /*yield*/, (0, user_1.getScopedDbAsSystem)().get(tables_1.tables.File, { id: variantId })];
                     case 5:
+                        _b = _c.sent();
+                        return [3 /*break*/, 7];
+                    case 6:
+                        _b = undefined;
+                        _c.label = 7;
+                    case 7: return [2 /*return*/, _b];
+                }
+            });
+        });
+    };
+    /**
+     * 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.
+     */
+    FileStorage.prototype.deriveVariants = function (file, bytes) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function () {
+            var maker, variants, named, _i, FILE_VARIANT_KINDS_1, kind, variantId, _b, _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        maker = (0, FileVariantMaker_1.getFileVariantMaker)();
+                        variants = {};
+                        named = {};
+                        if (!maker) return [3 /*break*/, 5];
+                        _i = 0, FILE_VARIANT_KINDS_1 = FileVariantMaker_1.FILE_VARIANT_KINDS;
+                        _d.label = 1;
+                    case 1:
+                        if (!(_i < FILE_VARIANT_KINDS_1.length)) return [3 /*break*/, 5];
+                        kind = FILE_VARIANT_KINDS_1[_i];
+                        if (!(!((_a = file[kind]) === null || _a === void 0 ? void 0 : _a._id) && maker.appliesTo(file, kind))) return [3 /*break*/, 4];
+                        return [4 /*yield*/, this.makeVariant(file, kind, bytes)];
+                    case 2:
+                        variantId = _d.sent();
+                        _b = variants;
+                        _c = kind;
+                        return [4 /*yield*/, (0, user_1.getScopedDbAsSystem)().get(tables_1.tables.File, { id: variantId })];
+                    case 3:
+                        _b[_c] = _d.sent();
+                        named[kind] = new db_1.Reference(tables_1.tables.File.name, variantId);
+                        _d.label = 4;
+                    case 4:
                         _i++;
-                        return [3 /*break*/, 2];
-                    case 6: return [2 /*return*/, file];
+                        return [3 /*break*/, 1];
+                    case 5: return [2 /*return*/, { file: __assign(__assign({}, file), named), variants: variants }];
                 }
             });
         });
@@ -164,26 +304,63 @@ var FileStorage = /** @class */ (function () {
      * 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.
      */
     FileStorage.prototype.getFileData = function (fileId) {
         return __awaiter(this, void 0, void 0, function () {
-            var file;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
+            var file, _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0: return [4 /*yield*/, this.getFile(fileId)];
                     case 1:
-                        file = _a.sent();
+                        file = _c.sent();
                         if (!file) {
-                            throw new Error("File not found: ".concat(fileId));
+                            throw FileStorage.notFound();
                         }
-                        return [4 /*yield*/, FileStorage.getDriver().getFileData(fileId)];
-                    case 2: return [2 /*return*/, _a.sent()];
+                        _b = (_a = FileStorage.getDriver()).getFileData;
+                        return [4 /*yield*/, this.servedFileId(file)];
+                    case 2: return [4 /*yield*/, _b.apply(_a, [_c.sent()])];
+                    case 3: return [2 /*return*/, _c.sent()];
+                }
+            });
+        });
+    };
+    /**
+     * 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}).
+     */
+    FileStorage.prototype.getAuthorizedFileData = function (file) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        _b = (_a = FileStorage.getDriver()).getFileData;
+                        return [4 /*yield*/, this.servedFileId(file)];
+                    case 1: return [4 /*yield*/, _b.apply(_a, [_c.sent()])];
+                    case 2: return [2 /*return*/, _c.sent()];
                 }
             });
         });
@@ -192,30 +369,35 @@ var FileStorage = /** @class */ (function () {
      * 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}).
      */
     FileStorage.prototype.getSignedUrl = function (fileId, options) {
         return __awaiter(this, void 0, void 0, function () {
-            var file, driver;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
+            var file, driver, _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0: return [4 /*yield*/, this.getFile(fileId)];
                     case 1:
-                        file = _a.sent();
+                        file = _c.sent();
                         if (!file) {
-                            throw new Error("File not found: ".concat(fileId));
+                            throw FileStorage.notFound();
                         }
                         driver = FileStorage.getDriver();
                         if (!driver.getSignedUrl) {
                             return [2 /*return*/, undefined];
                         }
-                        return [4 /*yield*/, driver.getSignedUrl(fileId, options)];
-                    case 2: return [2 /*return*/, _a.sent()];
+                        _b = (_a = driver).getSignedUrl;
+                        return [4 /*yield*/, this.servedFileId(file)];
+                    case 2: return [4 /*yield*/, _b.apply(_a, [_c.sent(), options])];
+                    case 3: return [2 /*return*/, _c.sent()];
                 }
             });
         });
@@ -227,6 +409,10 @@ var FileStorage = /** @class */ (function () {
      * (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
@@ -247,6 +433,9 @@ var FileStorage = /** @class */ (function () {
                         }
                         return [4 /*yield*/, FileStorage.getDriver().updateFileData(fileId, data)];
                     case 2:
+                        _a.sent();
+                        return [4 /*yield*/, this.dropDerivedFiles(file)];
+                    case 3:
                         _a.sent();
                         return [2 /*return*/];
                 }
@@ -300,6 +489,338 @@ var FileStorage = /** @class */ (function () {
             });
         });
     };
+    /**
+     * 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.
+     */
+    FileStorage.prototype.servedFileId = function (file) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function () {
+            var maker, error_1;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        if (this.ownedByCaller(file)) {
+                            return [2 /*return*/, file.id];
+                        }
+                        if ((_a = file.copyForOthers) === null || _a === void 0 ? void 0 : _a._id) {
+                            return [2 /*return*/, file.copyForOthers._id];
+                        }
+                        maker = (0, FileCopyForOthers_1.getFileCopyForOthers)();
+                        if (!maker || !maker.appliesTo(file)) {
+                            return [2 /*return*/, file.id];
+                        }
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.makeCopyForOthers(file)];
+                    case 2: return [2 /*return*/, _b.sent()];
+                    case 3:
+                        error_1 = _b.sent();
+                        if (FileCopyForOthers_1.FileCopyRefused.is(error_1)) {
+                            this.logger.warn({
+                                message: 'No copy of a file can be made for anyone but its owner; refused as not found',
+                                obj: { fileId: error_1.fileId, reason: error_1.reason },
+                            });
+                            throw FileStorage.notFound();
+                        }
+                        throw error_1;
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * 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.
+     */
+    FileStorage.prototype.ownedByCaller = function (file) {
+        return !file.scope || file.scope === new user_1.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.
+     */
+    FileStorage.prototype.makeCopyForOthers = function (file) {
+        return __awaiter(this, void 0, void 0, function () {
+            var maker, driver, original, _a, _b, copyBytes, cause_1, system, copy, named;
+            var _this = this;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        maker = (0, FileCopyForOthers_1.getFileCopyForOthers)();
+                        driver = FileStorage.getDriver();
+                        _b = (_a = Buffer).from;
+                        return [4 /*yield*/, driver.getFileData(file.id)];
+                    case 1:
+                        original = _b.apply(_a, [_c.sent(), 'base64']);
+                        _c.label = 2;
+                    case 2:
+                        _c.trys.push([2, 4, , 5]);
+                        return [4 /*yield*/, maker.make(file, original)];
+                    case 3:
+                        copyBytes = _c.sent();
+                        return [3 /*break*/, 5];
+                    case 4:
+                        cause_1 = _c.sent();
+                        // The maker's contract: a throw means no copy can be made — the file is the owner's alone.
+                        throw new FileCopyForOthers_1.FileCopyRefused(file.id, cause_1);
+                    case 5:
+                        system = (0, db_1.getDbAsSystem)();
+                        return [4 /*yield*/, system.insert(tables_1.tables.File, __assign(__assign(__assign(__assign(__assign({ 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 }))];
+                    case 6:
+                        copy = _c.sent();
+                        return [4 /*yield*/, driver.createFile(copy, copyBytes.toString('base64'))];
+                    case 7:
+                        _c.sent();
+                        return [4 /*yield*/, system.runTransaction(function () { return __awaiter(_this, void 0, void 0, function () {
+                                var current;
+                                var _a;
+                                return __generator(this, function (_b) {
+                                    switch (_b.label) {
+                                        case 0: return [4 /*yield*/, system.get(tables_1.tables.File, { id: file.id })];
+                                        case 1:
+                                            current = _b.sent();
+                                            if ((_a = current === null || current === void 0 ? void 0 : current.copyForOthers) === null || _a === void 0 ? void 0 : _a._id) {
+                                                return [2 /*return*/, current.copyForOthers._id];
+                                            }
+                                            return [4 /*yield*/, system.update(tables_1.tables.File, { id: file.id, copyForOthers: new db_1.Reference(tables_1.tables.File.name, copy.id) })];
+                                        case 2:
+                                            _b.sent();
+                                            return [2 /*return*/, copy.id];
+                                    }
+                                });
+                            }); })];
+                    case 8:
+                        named = _c.sent();
+                        if (!(named !== copy.id)) return [3 /*break*/, 10];
+                        // 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.
+                        return [4 /*yield*/, system.delete(tables_1.tables.File, { id: copy.id })];
+                    case 9:
+                        // 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.
+                        _c.sent();
+                        _c.label = 10;
+                    case 10: return [2 /*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.
+     */
+    FileStorage.prototype.deriveOnce = function (file, kind) {
+        var _this = this;
+        var key = "".concat(file.id, ":").concat(kind);
+        var running = FileStorage.derivations.get(key);
+        if (running) {
+            return running;
+        }
+        var derivation = (function () { return __awaiter(_this, void 0, void 0, function () {
+            var original, _a, _b, error_2;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        _b = (_a = Buffer).from;
+                        return [4 /*yield*/, FileStorage.getDriver().getFileData(file.id)];
+                    case 1:
+                        original = _b.apply(_a, [_c.sent(), 'base64']);
+                        _c.label = 2;
+                    case 2:
+                        _c.trys.push([2, 4, , 5]);
+                        return [4 /*yield*/, this.makeVariant(file, kind, original)];
+                    case 3: return [2 /*return*/, _c.sent()];
+                    case 4:
+                        error_2 = _c.sent();
+                        if (!FileVariantMaker_1.FileVariantNotMade.is(error_2)) {
+                            throw error_2;
+                        }
+                        new logger_1.Logger({ name: 'FileStorage' }).warn({
+                            message: "No ".concat(kind, " variant could be made of file ").concat(file.id, "; the file itself is served"),
+                            obj: { reason: error_2.reason },
+                        });
+                        return [2 /*return*/, undefined];
+                    case 5: return [2 /*return*/];
+                }
+            });
+        }); })().finally(function () { return 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.
+     */
+    FileStorage.prototype.makeVariant = function (file, kind, bytes) {
+        return __awaiter(this, void 0, void 0, function () {
+            var maker, driver, made, cause_2, system, variant, named;
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        maker = (0, FileVariantMaker_1.getFileVariantMaker)();
+                        driver = FileStorage.getDriver();
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, maker.make(file, bytes, kind)];
+                    case 2:
+                        made = _a.sent();
+                        return [3 /*break*/, 4];
+                    case 3:
+                        cause_2 = _a.sent();
+                        // The maker's contract: a throw means no variant can be made of these bytes.
+                        throw new FileVariantMaker_1.FileVariantNotMade(file.id, kind, cause_2);
+                    case 4:
+                        system = (0, db_1.getDbAsSystem)();
+                        return [4 /*yield*/, system.insert(tables_1.tables.File, __assign(__assign(__assign(__assign({ name: "(".concat(kind, ") ").concat(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 db_1.Reference(tables_1.tables.File.name, file.id), scope: file.scope }))];
+                    case 5:
+                        variant = _a.sent();
+                        return [4 /*yield*/, driver.createFile(variant, made.bytes.toString('base64'))];
+                    case 6:
+                        _a.sent();
+                        return [4 /*yield*/, system.runTransaction(function () { return __awaiter(_this, void 0, void 0, function () {
+                                var current;
+                                var _a;
+                                var _b;
+                                return __generator(this, function (_c) {
+                                    switch (_c.label) {
+                                        case 0: return [4 /*yield*/, system.get(tables_1.tables.File, { id: file.id })];
+                                        case 1:
+                                            current = _c.sent();
+                                            if ((_b = current === null || current === void 0 ? void 0 : current[kind]) === null || _b === void 0 ? void 0 : _b._id) {
+                                                return [2 /*return*/, current[kind]._id];
+                                            }
+                                            return [4 /*yield*/, system.update(tables_1.tables.File, (_a = { id: file.id }, _a[kind] = new db_1.Reference(tables_1.tables.File.name, variant.id), _a))];
+                                        case 2:
+                                            _c.sent();
+                                            return [2 /*return*/, variant.id];
+                                    }
+                                });
+                            }); })];
+                    case 7:
+                        named = _a.sent();
+                        if (!(named !== variant.id)) return [3 /*break*/, 9];
+                        // 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.
+                        return [4 /*yield*/, system.delete(tables_1.tables.File, { id: variant.id })];
+                    case 8:
+                        // 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.
+                        _a.sent();
+                        _a.label = 9;
+                    case 9: return [2 /*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.
+     */
+    FileStorage.prototype.dropDerivedFiles = function (file) {
+        return __awaiter(this, void 0, void 0, function () {
+            var seats, stale, system, forgotten, _i, stale_1, seat, _a, stale_2, seat;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        seats = __spreadArray(['copyForOthers'], FileVariantMaker_1.FILE_VARIANT_KINDS, true);
+                        stale = seats.filter(function (seat) { var _a; return !!((_a = file[seat]) === null || _a === void 0 ? void 0 : _a._id); });
+                        if (stale.length === 0) {
+                            return [2 /*return*/];
+                        }
+                        system = (0, db_1.getDbAsSystem)();
+                        forgotten = { id: file.id };
+                        for (_i = 0, stale_1 = stale; _i < stale_1.length; _i++) {
+                            seat = stale_1[_i];
+                            forgotten[seat] = null;
+                        }
+                        return [4 /*yield*/, system.update(tables_1.tables.File, forgotten)];
+                    case 1:
+                        _b.sent();
+                        _a = 0, stale_2 = stale;
+                        _b.label = 2;
+                    case 2:
+                        if (!(_a < stale_2.length)) return [3 /*break*/, 5];
+                        seat = stale_2[_a];
+                        return [4 /*yield*/, system.delete(tables_1.tables.File, { id: file[seat]._id })];
+                    case 3:
+                        _b.sent();
+                        _b.label = 4;
+                    case 4:
+                        _a++;
+                        return [3 /*break*/, 2];
+                    case 5: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * 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.
+     */
+    FileStorage.prototype.provenanceOf = function (file) {
+        var _a;
+        var provenance = {};
+        for (var _i = 0, _b = FileTable_1.FileTable.provenanceColumns; _i < _b.length; _i++) {
+            var column = _b[_i];
+            var value = file[column];
+            if (value !== undefined && value !== null) {
+                Object.assign(provenance, (_a = {}, _a[column] = value, _a));
+            }
+        }
+        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`).
+     */
+    FileStorage.notFound = function () {
+        return new service_1.ServiceRefusal(404, 'File not found');
+    };
+    /** The read path's derivations running in this process, by file and kind — see {@link deriveOnce}. */
+    FileStorage.derivations = new Map();
     return FileStorage;
 }());
 exports.FileStorage = FileStorage;