graphile-presigned-url-plugin 1.14.1 → 1.15.0

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/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/index.d.ts

@@ -39,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

@@ -37,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

@@ -90,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 ` +

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,6 +21,7 @@
 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';
@@ -93,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.' },
@@ -139,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)' },
@@ -227,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' },
@@ -237,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) },
@@ -249,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.' },
@@ -260,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.`,
@@ -622,8 +612,9 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     }
     // 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.
  *

package/esm/storage-module-cache.js

@@ -28,51 +28,9 @@ const storageModuleCache = new 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,
-    sm.has_confirm_upload,
-    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
@@ -139,95 +97,6 @@ function buildConfig(row) {
         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
- */
-export 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
- */
-export 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.
  *
@@ -273,11 +142,6 @@ export 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 };
@@ -354,9 +218,9 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
         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/index.d.ts

@@ -39,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/index.js

@@ -28,7 +28,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.markS3BucketProvisioned = exports.loadAllStorageModules = exports.isS3BucketProvisioned = exports.getStorageModuleConfigForOwner = exports.getStorageModuleConfig = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.resolveS3ForDatabase = exports.resolveS3 = exports.provisionAndRecordPhysicalBucket = exports.mintPhysicalBucketName = exports.resolveManagedUploadTarget = exports.finalizeStagedUpload = exports.buildFileProjection = exports.assertUploadAllowedByBucket = exports.getFileRefFieldBinding = exports.FileRefFieldNotRegisteredError = exports.clearFileRefFieldCache = exports.createDownloadUrlPlugin = exports.resolveDefaultBucket = exports.validateCustomKey = exports.confirmUploadedBytes = exports.CONFIRM_PREFIX_BYTES = void 0;
+exports.resolveStorageModuleByFileId = exports.resolveStorageConfigFromCodec = exports.markS3BucketProvisioned = exports.loadAllStorageModules = exports.isS3BucketProvisioned = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.resolveS3ForDatabase = exports.resolveS3 = exports.provisionAndRecordPhysicalBucket = exports.mintPhysicalBucketName = exports.resolveManagedUploadTarget = exports.finalizeStagedUpload = exports.buildFileProjection = exports.assertUploadAllowedByBucket = exports.getFileRefFieldBinding = exports.FileRefFieldNotRegisteredError = exports.clearFileRefFieldCache = exports.createDownloadUrlPlugin = exports.resolveDefaultBucket = exports.validateCustomKey = exports.confirmUploadedBytes = exports.CONFIRM_PREFIX_BYTES = void 0;
 var confirm_upload_1 = require("./confirm-upload");
 Object.defineProperty(exports, "CONFIRM_PREFIX_BYTES", { enumerable: true, get: function () { return confirm_upload_1.CONFIRM_PREFIX_BYTES; } });
 Object.defineProperty(exports, "confirmUploadedBytes", { enumerable: true, get: function () { return confirm_upload_1.confirmUploadedBytes; } });
@@ -70,8 +70,6 @@ var storage_module_cache_1 = require("./storage-module-cache");
 Object.defineProperty(exports, "clearBucketCache", { enumerable: true, get: function () { return storage_module_cache_1.clearBucketCache; } });
 Object.defineProperty(exports, "clearStorageModuleCache", { enumerable: true, get: function () { return storage_module_cache_1.clearStorageModuleCache; } });
 Object.defineProperty(exports, "getBucketConfig", { enumerable: true, get: function () { return storage_module_cache_1.getBucketConfig; } });
-Object.defineProperty(exports, "getStorageModuleConfig", { enumerable: true, get: function () { return storage_module_cache_1.getStorageModuleConfig; } });
-Object.defineProperty(exports, "getStorageModuleConfigForOwner", { enumerable: true, get: function () { return storage_module_cache_1.getStorageModuleConfigForOwner; } });
 Object.defineProperty(exports, "isS3BucketProvisioned", { enumerable: true, get: function () { return storage_module_cache_1.isS3BucketProvisioned; } });
 Object.defineProperty(exports, "loadAllStorageModules", { enumerable: true, get: function () { return storage_module_cache_1.loadAllStorageModules; } });
 Object.defineProperty(exports, "markS3BucketProvisioned", { enumerable: true, get: function () { return storage_module_cache_1.markS3BucketProvisioned; } });

package/managed-upload.js

@@ -96,8 +96,8 @@ 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 ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "1.14.1",
+  "version": "1.15.0",
   "description": "Presigned URL upload plugin for PostGraphile v5 — requestUploadUrl mutation and downloadUrl computed field",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -44,6 +44,7 @@
     "@aws-sdk/s3-request-presigner": "^3.1052.0",
     "@pgpmjs/logger": "^2.25.0",
     "@pgsql/quotes": "^18.2.4",
+    "graphile-storage-registry": "^0.1.0",
     "lru-cache": "^11.2.7",
     "mime-bytes": "^0.32.0"
   },
@@ -61,5 +62,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "8d77dfe57bb328cbdfe10732b10ca24865adf9c0"
+  "gitHead": "d10fe91ede80a4c2dfe2c1c6dcf6fe7193784eba"
 }

package/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/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,6 +25,7 @@ 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");
@@ -97,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.' },
@@ -143,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)' },
@@ -231,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' },
@@ -241,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) },
@@ -253,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.' },
@@ -264,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.`,
@@ -626,8 +616,9 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     }
     // 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,51 +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,
-    sm.has_confirm_upload,
-    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
@@ -152,95 +108,6 @@ function buildConfig(row) {
         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.
  *
@@ -286,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 };
@@ -367,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