graphile-presigned-url-plugin 1.14.0 → 1.15.0

package/custom-key.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validation for a caller-supplied ("custom") object key.
+ *
+ * A custom key is the one place a client names an S3 object directly, so what is
+ * enforced here is containment: the key must land inside the bucket's namespace
+ * and mean the same thing to S3 as it does to the gateway that later serves it.
+ */
+/**
+ * Returns an error string describing why `key` is unusable, or null if it is fine.
+ */
+export declare function validateCustomKey(key: string): string | null;

package/custom-key.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Validation for a caller-supplied ("custom") object key.
+ *
+ * A custom key is the one place a client names an S3 object directly, so what is
+ * enforced here is containment: the key must land inside the bucket's namespace
+ * and mean the same thing to S3 as it does to the gateway that later serves it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCustomKey = validateCustomKey;
+const MAX_CUSTOM_KEY_LENGTH = 1024;
+/**
+ * The key alphabet. A leading underscore is legal — a static export puts its
+ * hashed assets under `_next/static/**` — and containment is enforced by the
+ * `..`, leading-slash and NUL checks below rather than by the first character.
+ */
+const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9_][a-zA-Z0-9_.\-/]*$/;
+/**
+ * Returns an error string describing why `key` is unusable, or null if it is fine.
+ */
+function validateCustomKey(key) {
+    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
+        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
+    }
+    if (key.includes('..')) {
+        return 'INVALID_KEY: path traversal (..) not allowed';
+    }
+    if (key.startsWith('/')) {
+        return 'INVALID_KEY: leading slash not allowed';
+    }
+    if (key.includes('\0')) {
+        return 'INVALID_KEY: null bytes not allowed';
+    }
+    if (!CUSTOM_KEY_REGEX.test(key)) {
+        return 'INVALID_KEY: must start with alphanumeric or underscore and contain only alphanumeric, dots, hyphens, underscores, and slashes';
+    }
+    return null;
+}

package/download-url-field.js

@@ -24,6 +24,7 @@ exports.createDownloadUrlPlugin = createDownloadUrlPlugin;
 require("graphile-build");
 const logger_1 = require("@pgpmjs/logger");
 const grafast_1 = require("grafast");
+const graphile_storage_registry_1 = require("graphile-storage-registry");
 const request_pg_client_1 = require("./request-pg-client");
 const s3_signer_1 = require("./s3-signer");
 const storage_module_cache_1 = require("./storage-module-cache");
@@ -90,7 +91,7 @@ function createDownloadUrlPlugin(options) {
                     const { graphql: { GraphQLString }, } = build;
                     const capturedCodec = pgCodec;
                     return build.extend(fields, {
-                        downloadUrl: context.fieldWithHooks({ fieldName: 'downloadUrl' }, {
+                        [graphile_storage_registry_1.DOWNLOAD_URL_FIELD]: context.fieldWithHooks({ fieldName: graphile_storage_registry_1.DOWNLOAD_URL_FIELD }, {
                             description: 'URL to download this file. For public files, returns the public URL. ' +
                                 'For private files, returns a time-limited presigned URL.',
                             type: GraphQLString,

package/esm/custom-key.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validation for a caller-supplied ("custom") object key.
+ *
+ * A custom key is the one place a client names an S3 object directly, so what is
+ * enforced here is containment: the key must land inside the bucket's namespace
+ * and mean the same thing to S3 as it does to the gateway that later serves it.
+ */
+/**
+ * Returns an error string describing why `key` is unusable, or null if it is fine.
+ */
+export declare function validateCustomKey(key: string): string | null;

package/esm/custom-key.js

@@ -0,0 +1,35 @@
+/**
+ * Validation for a caller-supplied ("custom") object key.
+ *
+ * A custom key is the one place a client names an S3 object directly, so what is
+ * enforced here is containment: the key must land inside the bucket's namespace
+ * and mean the same thing to S3 as it does to the gateway that later serves it.
+ */
+const MAX_CUSTOM_KEY_LENGTH = 1024;
+/**
+ * The key alphabet. A leading underscore is legal — a static export puts its
+ * hashed assets under `_next/static/**` — and containment is enforced by the
+ * `..`, leading-slash and NUL checks below rather than by the first character.
+ */
+const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9_][a-zA-Z0-9_.\-/]*$/;
+/**
+ * Returns an error string describing why `key` is unusable, or null if it is fine.
+ */
+export function validateCustomKey(key) {
+    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
+        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
+    }
+    if (key.includes('..')) {
+        return 'INVALID_KEY: path traversal (..) not allowed';
+    }
+    if (key.startsWith('/')) {
+        return 'INVALID_KEY: leading slash not allowed';
+    }
+    if (key.includes('\0')) {
+        return 'INVALID_KEY: null bytes not allowed';
+    }
+    if (!CUSTOM_KEY_REGEX.test(key)) {
+        return 'INVALID_KEY: must start with alphanumeric or underscore and contain only alphanumeric, dots, hyphens, underscores, and slashes';
+    }
+    return null;
+}

package/esm/download-url-field.js

@@ -21,6 +21,7 @@
 import 'graphile-build';
 import { Logger } from '@pgpmjs/logger';
 import { context as grafastContext, lambda, object } from 'grafast';
+import { DOWNLOAD_URL_FIELD } from 'graphile-storage-registry';
 import { withRequestPgClient } from './request-pg-client';
 import { generatePresignedGetUrl } from './s3-signer';
 import { loadAllStorageModules, resolveStorageConfigFromCodec, storedPhysicalName } from './storage-module-cache';
@@ -87,7 +88,7 @@ export function createDownloadUrlPlugin(options) {
                     const { graphql: { GraphQLString }, } = build;
                     const capturedCodec = pgCodec;
                     return build.extend(fields, {
-                        downloadUrl: context.fieldWithHooks({ fieldName: 'downloadUrl' }, {
+                        [DOWNLOAD_URL_FIELD]: context.fieldWithHooks({ fieldName: DOWNLOAD_URL_FIELD }, {
                             description: 'URL to download this file. For public files, returns the public URL. ' +
                                 'For private files, returns a time-limited presigned URL.',
                             type: GraphQLString,

package/esm/file-lifecycle.d.ts

@@ -0,0 +1,20 @@
+import type { StorageModuleConfig } from './types';
+/**
+ * The statuses in which a files row stands for bytes a reader can actually GET.
+ * A `requested` row is a claim, not an object — its presigned PUT may never have
+ * run — and `rejected`/`expired` are settled failures.
+ */
+export declare const LIVE_FILE_STATUSES: string[];
+/**
+ * The `status` column, when the module has one, for splicing into a select list.
+ */
+export declare function statusSelectFragment(storageConfig: StorageModuleConfig): string;
+/**
+ * Whether an existing row may be handed back as a dedup hit.
+ *
+ * Modules without the confirm-upload lifecycle have no `status` column, so there
+ * is nothing to read and every row is presumed live, as before.
+ */
+export declare function isLiveFileRow(storageConfig: StorageModuleConfig, row: {
+    status?: string;
+}): boolean;

package/esm/file-lifecycle.js

@@ -0,0 +1,23 @@
+/**
+ * The statuses in which a files row stands for bytes a reader can actually GET.
+ * A `requested` row is a claim, not an object — its presigned PUT may never have
+ * run — and `rejected`/`expired` are settled failures.
+ */
+export const LIVE_FILE_STATUSES = ['uploaded', 'processed'];
+/**
+ * The `status` column, when the module has one, for splicing into a select list.
+ */
+export function statusSelectFragment(storageConfig) {
+    return storageConfig.hasConfirmUpload ? ', status' : '';
+}
+/**
+ * Whether an existing row may be handed back as a dedup hit.
+ *
+ * Modules without the confirm-upload lifecycle have no `status` column, so there
+ * is nothing to read and every row is presumed live, as before.
+ */
+export function isLiveFileRow(storageConfig, row) {
+    if (!storageConfig.hasConfirmUpload)
+        return true;
+    return LIVE_FILE_STATUSES.includes(row.status);
+}

package/esm/index.d.ts

@@ -27,6 +27,7 @@
  * ```
  */
 export { CONFIRM_PREFIX_BYTES, confirmUploadedBytes, type ConfirmUploadInput, type ConfirmUploadVerdict, } from './confirm-upload';
+export { validateCustomKey } from './custom-key';
 export type { ResolvedBucketCoordinate } from './default-bucket';
 export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
@@ -38,5 +39,5 @@ export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { type WithPgClient, withRequestPgClient } from './request-pg-client';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
-export { clearBucketCache, clearStorageModuleCache, getBucketConfig, getStorageModuleConfig, getStorageModuleConfigForOwner, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
+export { clearBucketCache, clearStorageModuleCache, getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
 export type { BucketConfig, BucketNameResolver, EnsureBucketProvisioned, PresignedUrlPluginOptions, RequestUploadUrlInput, RequestUploadUrlPayload, S3Config, S3ConfigOrGetter, StorageModuleConfig, } from './types';

package/esm/index.js

@@ -27,6 +27,7 @@
  * ```
  */
 export { CONFIRM_PREFIX_BYTES, confirmUploadedBytes, } from './confirm-upload';
+export { validateCustomKey } from './custom-key';
 export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
@@ -36,4 +37,4 @@ export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { withRequestPgClient } from './request-pg-client';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
-export { clearBucketCache, clearStorageModuleCache, getBucketConfig, getStorageModuleConfig, getStorageModuleConfigForOwner, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
+export { clearBucketCache, clearStorageModuleCache, getBucketConfig, isS3BucketProvisioned, loadAllStorageModules, markS3BucketProvisioned, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';

package/esm/managed-upload.js

@@ -19,6 +19,7 @@
  */
 import { Logger } from '@pgpmjs/logger';
 import { resolveDefaultBucket } from './default-bucket';
+import { isLiveFileRow, statusSelectFragment } from './file-lifecycle';
 import { getFileRefFieldBinding } from './file-ref-registry';
 import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
@@ -89,8 +90,8 @@ export async function resolveManagedUploadTarget(args) {
                 `unregistered upload column and database ${databaseId} has no app-scope storage module to ` +
                 'default to; there is no environment bucket to fall back to');
     }
-    if (storageConfig.scope !== 'app') {
-        // An entity-scoped module resolves its bucket per owning row, and a
+    if (storageConfig.entityTableId !== null) {
+        // An entity-keyed module resolves its bucket per owning row, and a
         // multipart column write does not carry one. Refuse rather than write a
         // tenant's file into whichever bucket happened to resolve.
         throw new Error(`STORAGE_SCOPE_UNSUPPORTED: ${field.schemaName}.${field.tableName}.${field.columnName} binds to ` +
@@ -192,7 +193,7 @@ export async function finalizeStagedUpload(args) {
     const finalKey = staged.contentHash;
     const existing = await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
         const result = await pgClient.query({
-            text: `SELECT id, key, mime_type, size, filename
+            text: `SELECT id, key, mime_type, size, filename${statusSelectFragment(storageConfig)}
              FROM ${storageConfig.filesQualifiedName}
              WHERE content_hash = $1 AND bucket_id = $2
              LIMIT 1`,
@@ -200,7 +201,22 @@ export async function finalizeStagedUpload(args) {
         });
         return result.rows[0];
     });
-    if (existing) {
+    // Only a row that already stands for stored bytes may absorb this upload. One
+    // that never received them is dropped, and the staged object is promoted as a
+    // fresh file below — which is also what keeps the insert possible, since the
+    // final key is the content hash and (bucket_id, key) is unique. The GC job the
+    // delete enqueues re-takes the reference count when it runs, by which point
+    // the replacement row exists, so it no-ops.
+    if (existing && !isLiveFileRow(storageConfig, existing)) {
+        log.info(`Restarting upload of hash ${staged.contentHash}: file ${existing.id} is ${existing.status}, so it carries no bytes`);
+        await withRequestPgClient(withPgClient, pgSettings, async (pgClient) => {
+            await pgClient.query({
+                text: `DELETE FROM ${storageConfig.filesQualifiedName} WHERE id = $1`,
+                values: [existing.id],
+            });
+        });
+    }
+    else if (existing) {
         log.info(`Dedup hit: file ${existing.id} already carries hash ${staged.contentHash}`);
         await deleteS3Object(s3, staged.stagingKey);
         return {

package/esm/plugin.d.ts

@@ -7,6 +7,8 @@
  *    on root Mutation for each @storageFiles/@storageBuckets pair. These combine
  *    bucket resolution + file INSERT + presigned URL generation in one step.
  *    E.g., `uploadAppFile(input: { bucketKey: "public", contentHash: "...", ... })`
+ *    Pairs are discovered from the registry's FK relations (see
+ *    graphile-storage-registry) — table naming carries no meaning here.
  *
  * 2. Delete middleware — wraps `delete*` mutations on `@storageFiles`-tagged tables
  *    with S3 object cleanup (sync + async GC fallback via AFTER DELETE trigger).

package/esm/plugin.js

@@ -7,6 +7,8 @@
  *    on root Mutation for each @storageFiles/@storageBuckets pair. These combine
  *    bucket resolution + file INSERT + presigned URL generation in one step.
  *    E.g., `uploadAppFile(input: { bucketKey: "public", contentHash: "...", ... })`
+ *    Pairs are discovered from the registry's FK relations (see
+ *    graphile-storage-registry) — table naming carries no meaning here.
  *
  * 2. Delete middleware — wraps `delete*` mutations on `@storageFiles`-tagged tables
  *    with S3 object cleanup (sync + async GC fallback via AFTER DELETE trigger).
@@ -19,8 +21,11 @@
 import 'graphile-build';
 import { Logger } from '@pgpmjs/logger';
 import { access, context as grafastContext, lambda, object } from 'grafast';
+import { discoverStoragePlanes, uploadSurfaceNames } from 'graphile-storage-registry';
 import { checkTypeAgreement } from 'mime-bytes';
+import { validateCustomKey } from './custom-key';
 import { resolveDefaultBucket } from './default-bucket';
+import { isLiveFileRow, statusSelectFragment } from './file-lifecycle';
 import { buildFileProjection } from './managed-upload';
 import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
@@ -30,9 +35,7 @@ const log = new Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
 const MAX_CONTENT_HASH_LENGTH = 128;
 const MAX_CONTENT_TYPE_LENGTH = 255;
-const MAX_CUSTOM_KEY_LENGTH = 1024;
 const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/;
-const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_.\-/]*$/;
 // --- Helpers ---
 function isValidSha256(hash) {
     return SHA256_HEX_REGEX.test(hash);
@@ -40,24 +43,6 @@ function isValidSha256(hash) {
 function buildS3Key(contentHash) {
     return contentHash;
 }
-function validateCustomKey(key) {
-    if (key.length === 0 || key.length > MAX_CUSTOM_KEY_LENGTH) {
-        return 'INVALID_KEY_LENGTH: must be 1-1024 characters';
-    }
-    if (key.includes('..')) {
-        return 'INVALID_KEY: path traversal (..) not allowed';
-    }
-    if (key.startsWith('/')) {
-        return 'INVALID_KEY: leading slash not allowed';
-    }
-    if (key.includes('\0')) {
-        return 'INVALID_KEY: null bytes not allowed';
-    }
-    if (!CUSTOM_KEY_REGEX.test(key)) {
-        return 'INVALID_KEY: must start with alphanumeric and contain only alphanumeric, dots, hyphens, underscores, and slashes';
-    }
-    return null;
-}
 function derivePathFromKey(key) {
     const lastSlash = key.lastIndexOf('/');
     if (lastSlash <= 0)
@@ -111,38 +96,25 @@ export function createPresignedUrlPlugin(options) {
                     if (!jsonType) {
                         log.warn('No JSON scalar in this schema; upload payloads will omit the `file` projection');
                     }
-                    const bucketCodecs = Object.values(build.input.pgRegistry.pgCodecs).filter((codec) => codec.attributes && codec.extensions?.tags?.storageBuckets);
-                    if (bucketCodecs.length === 0)
+                    // Each @storageFiles table is paired with its @storageBuckets table
+                    // through the registry's actual FK relation; a tagged table that cannot
+                    // be paired is a provisioning bug and throws at schema build.
+                    const planes = discoverStoragePlanes(build.input.pgRegistry);
+                    if (planes.length === 0)
                         return fields;
                     const newFields = {};
                     // --- File upload mutations (uploadAppFile, uploadDataRoomFile, etc.) ---
-                    const fileCodecs = Object.values(build.input.pgRegistry.pgCodecs).filter((codec) => codec.attributes && codec.extensions?.tags?.storageFiles);
-                    for (const filesCodec of fileCodecs) {
-                        const filesTypeName = build.inflection.tableType(filesCodec);
-                        // Find the matching bucket codec by table name prefix.
-                        // Schema-name matching is ambiguous when multiple storage modules share
-                        // the same PG schema (e.g. app_files + data_room_files both in storage_public).
-                        // Instead, derive the prefix from the raw SQL table name:
-                        //   "data_room_files" → prefix "data_room" → matches "data_room_buckets"
-                        //   "app_files"       → prefix "app"       → matches "app_buckets"
-                        const filesRawName = filesCodec.extensions?.pg?.name;
-                        const filesPrefix = filesRawName?.replace(/_files$/, '');
-                        const matchingBucketCodec = bucketCodecs.find((bc) => {
-                            const bucketRawName = bc.extensions?.pg?.name;
-                            const bucketPrefix = bucketRawName?.replace(/_buckets$/, '');
-                            return bucketPrefix === filesPrefix;
-                        });
-                        if (!matchingBucketCodec) {
-                            log.debug(`Skipping upload mutation for ${filesCodec.name}: no matching bucket codec with prefix "${filesPrefix}"`);
-                            continue;
-                        }
-                        const hasOwnerId = !!matchingBucketCodec.attributes.owner_id;
-                        const mutationName = `upload${filesTypeName}`;
+                    for (const plane of planes) {
+                        const filesCodec = plane.filesCodec;
+                        const matchingBucketCodec = plane.bucketsCodec;
+                        const names = uploadSurfaceNames(build.inflection, plane.filesCodec);
+                        const { filesTypeName, uploadMutation: mutationName } = names;
+                        const hasOwnerId = plane.hasOwnerId;
                         const ownerIdGqlType = hasOwnerId
                             ? build.getGraphQLTypeByPgCodec(matchingBucketCodec.attributes.owner_id.codec, 'input')
                             : null;
                         const InputType = new GraphQLInputObjectType({
-                            name: `Upload${filesTypeName}Input`,
+                            name: names.uploadInputType,
                             fields: {
                                 bucketKey: { type: GraphQLString, description: 'Bucket key (e.g., "public", "private"). Omit to use the database\'s default bucket for the requested access.' },
                                 isPublic: { type: GraphQLBoolean, description: 'Which default bucket to resolve when bucketKey is omitted: the public one (true) or the private one (default false). Ignored when bucketKey is given.' },
@@ -157,7 +129,7 @@ export function createPresignedUrlPlugin(options) {
                             },
                         });
                         const PayloadType = new GraphQLObjectType({
-                            name: `Upload${filesTypeName}Payload`,
+                            name: names.uploadPayloadType,
                             fields: {
                                 uploadUrl: { type: GraphQLString, description: 'Presigned PUT URL (null if deduplicated)' },
                                 fileId: { type: new GraphQLNonNull(GraphQLString), description: 'The file ID (UUID)' },
@@ -245,7 +217,7 @@ export function createPresignedUrlPlugin(options) {
                         });
                         // --- Bulk file upload mutation ---
                         const BulkFileInputType = new GraphQLInputObjectType({
-                            name: `Upload${filesTypeName}BulkFileInput`,
+                            name: names.bulkUploadFileInputType,
                             fields: {
                                 contentHash: { type: new GraphQLNonNull(GraphQLString), description: 'SHA-256 content hash (hex-encoded, 64 chars)' },
                                 contentType: { type: new GraphQLNonNull(GraphQLString), description: 'MIME type of the file' },
@@ -255,7 +227,7 @@ export function createPresignedUrlPlugin(options) {
                             },
                         });
                         const BulkFilePayloadType = new GraphQLObjectType({
-                            name: `Upload${filesTypeName}BulkFilePayload`,
+                            name: names.bulkUploadFilePayloadType,
                             fields: {
                                 uploadUrl: { type: GraphQLString },
                                 fileId: { type: new GraphQLNonNull(GraphQLString) },
@@ -267,7 +239,7 @@ export function createPresignedUrlPlugin(options) {
                             },
                         });
                         const BulkInputType = new GraphQLInputObjectType({
-                            name: `Upload${filesTypeName}BulkInput`,
+                            name: names.bulkUploadInputType,
                             fields: {
                                 bucketKey: { type: GraphQLString, description: 'Bucket key (e.g., "public", "private"). Omit to use the database\'s default bucket for the requested access.' },
                                 isPublic: { type: GraphQLBoolean, description: 'Which default bucket to resolve when bucketKey is omitted. Ignored when bucketKey is given.' },
@@ -278,12 +250,12 @@ export function createPresignedUrlPlugin(options) {
                             },
                         });
                         const BulkPayloadType = new GraphQLObjectType({
-                            name: `Upload${filesTypeName}BulkPayload`,
+                            name: names.bulkUploadPayloadType,
                             fields: {
                                 files: { type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(BulkFilePayloadType))) },
                             },
                         });
-                        const bulkMutationName = `upload${filesTypeName}s`;
+                        const bulkMutationName = names.bulkUploadMutation;
                         log.debug(`Adding bulk file upload mutation "${bulkMutationName}" for ${filesTypeName}`);
                         newFields[bulkMutationName] = context.fieldWithHooks({ fieldName: bulkMutationName }, {
                             description: `Upload multiple files: resolves the bucket by key, creates file rows, and returns presigned PUT URLs for each.`,
@@ -560,9 +532,20 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     }
     // Dedup / versioning check
     let previousVersionId = null;
+    // A row whose bytes never landed must not be reported as a dedup hit: the
+    // caller would store a reference to an object that is not in S3. Such a row is
+    // dropped instead, and the upload proceeds as a fresh one below — the insert is
+    // what enqueues the confirm-upload job, so restarting the lifecycle is the only
+    // way the retry can ever leave `requested`. Dropping it is also what keeps the
+    // retry insertable at all for a content-addressed key, where the key *is* the
+    // hash and a second row would collide on (bucket_id, key). The GC job the
+    // delete enqueues re-takes the reference count when it runs (≥5s later), by
+    // which point the replacement row exists, so it no-ops.
+    const statusColumn = statusSelectFragment(storageConfig);
+    let staleFileId = null;
     if (isCustomKey) {
         const existingResult = await txClient.query({
-            text: `SELECT id, content_hash
+            text: `SELECT id, content_hash${statusColumn}
        FROM ${storageConfig.filesQualifiedName}
        WHERE key = $1
          AND bucket_id = $2
@@ -573,24 +556,30 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         if (existingResult.rows.length > 0) {
             const existing = existingResult.rows[0];
             if (existing.content_hash === contentHash) {
-                log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
-                return {
-                    uploadUrl: null,
-                    fileId: existing.id,
-                    key: s3Key,
-                    deduplicated: true,
-                    expiresAt: null,
-                    previousVersionId: null,
-                    file: projectFile(existing.id, s3Key),
-                };
+                if (isLiveFileRow(storageConfig, existing)) {
+                    log.info(`Dedup hit (custom key): file ${existing.id} for key ${s3Key}`);
+                    return {
+                        uploadUrl: null,
+                        fileId: existing.id,
+                        key: s3Key,
+                        deduplicated: true,
+                        expiresAt: null,
+                        previousVersionId: null,
+                        file: projectFile(existing.id, s3Key),
+                    };
+                }
+                staleFileId = existing.id;
+                log.info(`Restarting upload of key ${s3Key}: file ${staleFileId} is ${existing.status}, so it carries no bytes`);
+            }
+            else {
+                previousVersionId = existing.id;
+                log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
             }
-            previousVersionId = existing.id;
-            log.info(`Versioning: new version of key ${s3Key}, previous=${previousVersionId}`);
         }
     }
     else {
         const dedupResult = await txClient.query({
-            text: `SELECT id
+            text: `SELECT id${statusColumn}
        FROM ${storageConfig.filesQualifiedName}
        WHERE content_hash = $1
          AND bucket_id = $2
@@ -599,22 +588,33 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         });
         if (dedupResult.rows.length > 0) {
             const existingFile = dedupResult.rows[0];
-            log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
-            return {
-                uploadUrl: null,
-                fileId: existingFile.id,
-                key: s3Key,
-                deduplicated: true,
-                expiresAt: null,
-                previousVersionId: null,
-                file: projectFile(existingFile.id, s3Key),
-            };
+            if (isLiveFileRow(storageConfig, existingFile)) {
+                log.info(`Dedup hit: file ${existingFile.id} for hash ${contentHash}`);
+                return {
+                    uploadUrl: null,
+                    fileId: existingFile.id,
+                    key: s3Key,
+                    deduplicated: true,
+                    expiresAt: null,
+                    previousVersionId: null,
+                    file: projectFile(existingFile.id, s3Key),
+                };
+            }
+            staleFileId = existingFile.id;
+            log.info(`Restarting upload of hash ${contentHash}: file ${staleFileId} is ${existingFile.status}, so it carries no bytes`);
         }
     }
+    if (staleFileId !== null) {
+        await txClient.query({
+            text: `DELETE FROM ${storageConfig.filesQualifiedName} WHERE id = $1`,
+            values: [staleFileId],
+        });
+    }
     // Auto-derive ltree path from custom key directory (only when has_path_shares)
     const derivedPath = isCustomKey && storageConfig.hasPathShares ? derivePathFromKey(s3Key) : null;
-    // Create file record
-    const hasOwnerColumn = storageConfig.scope !== 'app';
+    // Create file record. An entity-keyed plane (the module records an entity
+    // table) carries owner_id on its rows; app- and database-scope planes do not.
+    const hasOwnerColumn = storageConfig.entityTableId !== null;
     const columns = ['bucket_id', 'key', 'content_hash', 'mime_type', 'size', 'filename', 'is_public'];
     const values = [bucket.id, s3Key, contentHash, contentType, size, filename || null, bucket.is_public];
     if (hasOwnerColumn) {

package/esm/storage-module-cache.d.ts

@@ -1,45 +1,4 @@
 import type { BucketConfig, StorageModuleConfig } from './types';
-/**
- * Resolve the app-level storage module config for a database, using the LRU cache.
- *
- * This is the default path when no ownerId is provided. It returns the
- * storage module with scope = 'app' (app-level / database-wide).
- *
- * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
- * @param databaseId - The metaschema database UUID
- * @returns StorageModuleConfig or null if no storage module is provisioned
- */
-export declare function getStorageModuleConfig(pgClient: {
-    query: (opts: {
-        text: string;
-        values?: unknown[];
-    }) => Promise<{
-        rows: unknown[];
-    }>;
-}, databaseId: string): Promise<StorageModuleConfig | null>;
-/**
- * Resolve the storage module config for a specific owner entity.
- *
- * When ownerId is provided, this function:
- * 1. Loads ALL storage modules for the database (cached)
- * 2. Finds which entity-scoped module contains the ownerId in its entity table
- * 3. Returns that module's config
- *
- * This is the core of Option C — the ownerId tells us which scope to use.
- *
- * @param pgClient - A pg client from the Graphile context
- * @param databaseId - The metaschema database UUID
- * @param ownerId - The entity instance UUID (e.g., a data room ID, team ID)
- * @returns StorageModuleConfig or null if no matching module found
- */
-export declare function getStorageModuleConfigForOwner(pgClient: {
-    query: (opts: {
-        text: string;
-        values?: unknown[];
-    }) => Promise<{
-        rows: unknown[];
-    }>;
-}, databaseId: string, ownerId: string): Promise<StorageModuleConfig | null>;
 /**
  * Resolve the storage module that owns a specific file by probing all file tables.
  *