graphile-presigned-url-plugin 1.14.0 → 1.15.0

package/plugin.js

@@ -8,6 +8,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).
@@ -23,8 +25,11 @@ exports.createPresignedUrlPlugin = createPresignedUrlPlugin;
 require("graphile-build");
 const logger_1 = require("@pgpmjs/logger");
 const grafast_1 = require("grafast");
+const graphile_storage_registry_1 = require("graphile-storage-registry");
 const mime_bytes_1 = require("mime-bytes");
+const custom_key_1 = require("./custom-key");
 const default_bucket_1 = require("./default-bucket");
+const file_lifecycle_1 = require("./file-lifecycle");
 const managed_upload_1 = require("./managed-upload");
 const physical_bucket_1 = require("./physical-bucket");
 const request_pg_client_1 = require("./request-pg-client");
@@ -34,9 +39,7 @@ const log = new logger_1.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);
@@ -44,24 +47,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)
@@ -115,38 +100,25 @@ 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 = (0, graphile_storage_registry_1.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 = (0, graphile_storage_registry_1.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.' },
@@ -161,7 +133,7 @@ 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)' },
@@ -249,7 +221,7 @@ 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' },
@@ -259,7 +231,7 @@ function createPresignedUrlPlugin(options) {
                             },
                         });
                         const BulkFilePayloadType = new GraphQLObjectType({
-                            name: `Upload${filesTypeName}BulkFilePayload`,
+                            name: names.bulkUploadFilePayloadType,
                             fields: {
                                 uploadUrl: { type: GraphQLString },
                                 fileId: { type: new GraphQLNonNull(GraphQLString) },
@@ -271,7 +243,7 @@ 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.' },
@@ -282,12 +254,12 @@ 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.`,
@@ -552,7 +524,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
         if (!bucket.allow_custom_keys) {
             throw new Error('CUSTOM_KEY_NOT_ALLOWED: bucket does not allow custom keys');
         }
-        const keyError = validateCustomKey(customKey);
+        const keyError = (0, custom_key_1.validateCustomKey)(customKey);
         if (keyError) {
             throw new Error(keyError);
         }
@@ -564,9 +536,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 = (0, file_lifecycle_1.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
@@ -577,24 +560,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 ((0, file_lifecycle_1.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
@@ -603,22 +592,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 ((0, file_lifecycle_1.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/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.
  *

package/storage-module-cache.js

@@ -1,7 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getStorageModuleConfig = getStorageModuleConfig;
-exports.getStorageModuleConfigForOwner = getStorageModuleConfigForOwner;
 exports.resolveStorageModuleByFileId = resolveStorageModuleByFileId;
 exports.loadAllStorageModules = loadAllStorageModules;
 exports.resolveStorageConfigFromCodec = resolveStorageConfigFromCodec;
@@ -41,50 +39,9 @@ const storageModuleCache = new lru_cache_1.LRUCache({
     updateAgeOnGet: true,
 });
 /**
- * SQL query to resolve the app-level storage module config for a database.
- *
- * Joins storage_module → table → schema to get fully-qualified table names.
- * Filters to app-level (scope = 'app') by default.
- *
- * Requires the multi-scope schema (scope column on storage_module).
- */
-const APP_STORAGE_MODULE_QUERY = `
-  SELECT
-    sm.id,
-    sm.scope,
-    sm.entity_table_id,
-    bs.schema_name AS buckets_schema,
-    bt.name AS buckets_table,
-    fs.schema_name AS files_schema,
-    ft.name AS files_table,
-    sm.endpoint,
-    sm.public_url_prefix,
-    sm.provider,
-    sm.allowed_origins,
-    sm.upload_url_expiry_seconds,
-    sm.download_url_expiry_seconds,
-    sm.default_max_file_size,
-    sm.max_filename_length,
-    sm.cache_ttl_seconds,
-    sm.max_bulk_files,
-    sm.max_bulk_total_size,
-    sm.has_path_shares,
-    NULL AS entity_schema,
-    NULL AS entity_table
-  FROM metaschema_modules_public.storage_module sm
-  JOIN metaschema_public.table bt ON bt.id = sm.buckets_table_id
-  JOIN metaschema_public.schema bs ON bs.id = bt.schema_id
-  JOIN metaschema_public.table ft ON ft.id = sm.files_table_id
-  JOIN metaschema_public.schema fs ON fs.id = ft.schema_id
-  WHERE sm.database_id = $1
-    AND sm.scope = 'app'
-  LIMIT 1
-`;
-/**
- * SQL query to resolve ALL storage modules for a database (app-level + entity-scoped).
- *
- * Returns all storage modules with their entity table names for ownerId resolution.
- * Requires the multi-scope schema.
+ * SQL query to resolve ALL storage modules for a database, whatever their
+ * scope. Returns each module with its entity table names so callers can
+ * classify entity-keyed planes and resolve owners.
  */
 const ALL_STORAGE_MODULES_QUERY = `
   SELECT
@@ -107,6 +64,7 @@ const ALL_STORAGE_MODULES_QUERY = `
     sm.max_bulk_files,
     sm.max_bulk_total_size,
     sm.has_path_shares,
+    sm.has_confirm_upload,
     es.schema_name AS entity_schema,
     et.name AS entity_table
   FROM metaschema_modules_public.storage_module sm
@@ -145,99 +103,11 @@ function buildConfig(row) {
         maxFilenameLength: row.max_filename_length ?? DEFAULT_MAX_FILENAME_LENGTH,
         cacheTtlSeconds,
         hasPathShares: row.has_path_shares ?? false,
+        hasConfirmUpload: row.has_confirm_upload ?? false,
         maxBulkFiles: row.max_bulk_files ?? DEFAULT_MAX_BULK_FILES,
         maxBulkTotalSize: row.max_bulk_total_size ?? DEFAULT_MAX_BULK_TOTAL_SIZE,
     };
 }
-/**
- * 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
- */
-async function getStorageModuleConfig(pgClient, databaseId) {
-    const cacheKey = `storage:${databaseId}:app`;
-    const cached = storageModuleCache.get(cacheKey);
-    if (cached) {
-        return cached;
-    }
-    log.debug(`Cache miss for app-level storage in database ${databaseId}, querying metaschema...`);
-    const result = await pgClient.query({ text: APP_STORAGE_MODULE_QUERY, values: [databaseId] });
-    if (result.rows.length === 0) {
-        log.warn(`No app-level storage module found for database ${databaseId}`);
-        return null;
-    }
-    const config = buildConfig(result.rows[0]);
-    storageModuleCache.set(cacheKey, config);
-    log.debug(`Cached app-level storage config for database ${databaseId}: ${config.bucketsQualifiedName}`);
-    return config;
-}
-/**
- * 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
- */
-async function getStorageModuleConfigForOwner(pgClient, databaseId, ownerId) {
-    // Check if we already have a cached mapping for this ownerId
-    const ownerCacheKey = `storage:${databaseId}:owner:${ownerId}`;
-    const cachedOwner = storageModuleCache.get(ownerCacheKey);
-    if (cachedOwner) {
-        return cachedOwner;
-    }
-    // Load all storage modules for this database
-    const allModulesCacheKey = `storage:${databaseId}:all`;
-    let allConfigs;
-    const cachedAll = storageModuleCache.get(allModulesCacheKey);
-    if (cachedAll) {
-        // We stored a sentinel; re-derive from individual caches
-        // Actually, let's just query fresh — this is the cache-miss path
-        allConfigs = [];
-    }
-    else {
-        allConfigs = [];
-    }
-    if (allConfigs.length === 0) {
-        log.debug(`Loading all storage modules for database ${databaseId} to resolve ownerId ${ownerId}`);
-        const result = await pgClient.query({ text: ALL_STORAGE_MODULES_QUERY, values: [databaseId] });
-        allConfigs = result.rows.map(buildConfig);
-        // Cache each individual config by its scope
-        for (const config of allConfigs) {
-            const key = `storage:${databaseId}:scope:${config.scope}`;
-            storageModuleCache.set(key, config);
-        }
-    }
-    // Find entity-scoped modules and probe their entity tables for the ownerId
-    const entityModules = allConfigs.filter((c) => c.entityQualifiedName !== null);
-    for (const mod of entityModules) {
-        const probeResult = await pgClient.query({
-            text: `SELECT 1 FROM ${mod.entityQualifiedName} WHERE id = $1 LIMIT 1`,
-            values: [ownerId],
-        });
-        if (probeResult.rows.length > 0) {
-            // Found the matching module — cache the ownerId→module mapping
-            storageModuleCache.set(ownerCacheKey, mod);
-            log.debug(`Resolved ownerId ${ownerId} to storage module ${mod.id} ` +
-                `(scope=${mod.scope}, table=${mod.bucketsQualifiedName})`);
-            return mod;
-        }
-    }
-    log.warn(`No entity-scoped storage module found for ownerId ${ownerId} in database ${databaseId}`);
-    return null;
-}
 /**
  * Resolve the storage module that owns a specific file by probing all file tables.
  *
@@ -283,11 +153,6 @@ async function loadAllStorageModules(pgClient, databaseId) {
     log.debug(`Loading all storage modules for database ${databaseId}`);
     const result = await pgClient.query({ text: ALL_STORAGE_MODULES_QUERY, values: [databaseId] });
     const configs = result.rows.map(buildConfig);
-    // Cache each individual config by its scope
-    for (const config of configs) {
-        const key = `storage:${databaseId}:scope:${config.scope}`;
-        storageModuleCache.set(key, config);
-    }
     // Store the full list under a sentinel key (only if non-empty to avoid caching failed lookups)
     if (configs.length > 0) {
         const sentinel = { ...configs[0], _allConfigs: configs };
@@ -364,9 +229,9 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
         return cached;
     }
     log.debug(`Bucket cache miss for ${databaseId}:${bucketKey}${ownerId ? ` (owner=${ownerId})` : ''}, querying DB...`);
-    // Entity-scoped buckets use (owner_id, key) composite lookup;
-    // app-level buckets just use key.
-    const isEntityScoped = storageConfig.scope !== 'app';
+    // Entity-keyed planes (the module records an entity table) use the
+    // (owner_id, key) composite lookup; app- and database-scope planes just use key.
+    const isEntityScoped = storageConfig.entityTableId !== null;
     const hasOwner = ownerId && isEntityScoped;
     const result = await pgClient.query({
         text: hasOwner

package/types.d.ts

@@ -61,6 +61,12 @@ export interface StorageModuleConfig {
     cacheTtlSeconds: number;
     /** Whether this storage module uses ltree path + path shares (determines if path column exists on files) */
     hasPathShares: boolean;
+    /**
+     * Whether the files table carries the confirm-upload lifecycle (`status`,
+     * `promoted_at`). Only then can a row be told apart from the bytes it claims:
+     * without it every row is treated as live, because there is nothing to read.
+     */
+    hasConfirmUpload: boolean;
     /** Max files per requestBulkUploadUrls batch (default: 100) */
     maxBulkFiles: number;
     /** Max total size per bulk upload batch in bytes (default: 1GB) */