graphile-presigned-url-plugin 1.16.1 → 1.18.0

package/index.d.ts

@@ -34,11 +34,11 @@ export { createDownloadUrlPlugin } from './download-url-field';
 export type { FileRefFieldBinding } from './file-ref-registry';
 export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
 export { assertUploadAllowedByBucket, buildFileProjection, type FileProjection, finalizeStagedUpload, type ManagedUploadTarget, resolveManagedUploadTarget, } from './managed-upload';
-export { mintPhysicalBucketName, provisionAndRecordPhysicalBucket, resolveS3, resolveS3ForDatabase } from './physical-bucket';
+export { assertBucketReconciled, resolveS3, resolveS3ForDatabase, StorageBucketNotReconciledError, } from './physical-bucket';
 export { createPresignedUrlPlugin, PresignedUrlPlugin } from './plugin';
 export { PresignedUrlPreset } from './preset';
 export { type WithPgClient, withRequestPgClient } from './request-pg-client';
 export { describeS3Failure, s3FailureError } from './s3-failure';
 export { copyS3Object, deleteS3Object, generatePresignedGetUrl, generatePresignedPutUrl, headObject, readObjectPrefix } from './s3-signer';
-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';
+export { clearBucketCache, clearStorageModuleCache, getBucketConfig, loadAllStorageModules, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';
+export type { BucketConfig, 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.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.s3FailureError = exports.describeS3Failure = 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.loadAllStorageModules = exports.getBucketConfig = exports.clearStorageModuleCache = exports.clearBucketCache = exports.readObjectPrefix = exports.headObject = exports.generatePresignedPutUrl = exports.generatePresignedGetUrl = exports.deleteS3Object = exports.copyS3Object = exports.s3FailureError = exports.describeS3Failure = exports.withRequestPgClient = exports.PresignedUrlPreset = exports.PresignedUrlPlugin = exports.createPresignedUrlPlugin = exports.StorageBucketNotReconciledError = exports.resolveS3ForDatabase = exports.resolveS3 = exports.assertBucketReconciled = 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; } });
@@ -48,10 +48,10 @@ Object.defineProperty(exports, "buildFileProjection", { enumerable: true, get: f
 Object.defineProperty(exports, "finalizeStagedUpload", { enumerable: true, get: function () { return managed_upload_1.finalizeStagedUpload; } });
 Object.defineProperty(exports, "resolveManagedUploadTarget", { enumerable: true, get: function () { return managed_upload_1.resolveManagedUploadTarget; } });
 var physical_bucket_1 = require("./physical-bucket");
-Object.defineProperty(exports, "mintPhysicalBucketName", { enumerable: true, get: function () { return physical_bucket_1.mintPhysicalBucketName; } });
-Object.defineProperty(exports, "provisionAndRecordPhysicalBucket", { enumerable: true, get: function () { return physical_bucket_1.provisionAndRecordPhysicalBucket; } });
+Object.defineProperty(exports, "assertBucketReconciled", { enumerable: true, get: function () { return physical_bucket_1.assertBucketReconciled; } });
 Object.defineProperty(exports, "resolveS3", { enumerable: true, get: function () { return physical_bucket_1.resolveS3; } });
 Object.defineProperty(exports, "resolveS3ForDatabase", { enumerable: true, get: function () { return physical_bucket_1.resolveS3ForDatabase; } });
+Object.defineProperty(exports, "StorageBucketNotReconciledError", { enumerable: true, get: function () { return physical_bucket_1.StorageBucketNotReconciledError; } });
 var plugin_1 = require("./plugin");
 Object.defineProperty(exports, "createPresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.createPresignedUrlPlugin; } });
 Object.defineProperty(exports, "PresignedUrlPlugin", { enumerable: true, get: function () { return plugin_1.PresignedUrlPlugin; } });
@@ -73,8 +73,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, "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; } });
 Object.defineProperty(exports, "resolveStorageConfigFromCodec", { enumerable: true, get: function () { return storage_module_cache_1.resolveStorageConfigFromCodec; } });
 Object.defineProperty(exports, "resolveStorageModuleByFileId", { enumerable: true, get: function () { return storage_module_cache_1.resolveStorageModuleByFileId; } });

package/managed-upload.js

@@ -30,6 +30,7 @@ const file_ref_registry_1 = require("./file-ref-registry");
 const physical_bucket_1 = require("./physical-bucket");
 const request_pg_client_1 = require("./request-pg-client");
 const s3_signer_1 = require("./s3-signer");
+const storage_file_recorder_1 = require("./storage-file-recorder");
 const storage_module_cache_1 = require("./storage-module-cache");
 const log = new logger_1.Logger('graphile-presigned-url:managed-upload');
 /**
@@ -139,9 +140,7 @@ async function resolveManagedUploadTarget(args) {
             'the multipart upload lane only writes content-addressed keys. Use the presigned upload ' +
             'mutation with an explicit key.');
     }
-    const physicalName = bucket.physical_name === null
-        ? await (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
-        : bucket.physical_name;
+    const physicalName = (0, physical_bucket_1.assertBucketReconciled)(bucket, databaseId);
     return {
         databaseId,
         storageConfig,
@@ -258,22 +257,14 @@ async function finalizeStagedUpload(args) {
     let fileId;
     try {
         fileId = await (0, request_pg_client_1.withRequestPgClient)(withPgClient, pgSettings, async (pgClient) => {
-            const result = await pgClient.query({
-                text: `INSERT INTO ${storageConfig.filesQualifiedName}
-             (bucket_id, key, content_hash, mime_type, size, filename, is_public)
-             VALUES ($1, $2, $3, $4, $5, $6, $7)
-             RETURNING id`,
-                values: [
-                    bucket.id,
-                    finalKey,
-                    staged.contentHash,
-                    staged.contentType,
-                    staged.size,
-                    staged.filename ?? null,
-                    bucket.is_public,
-                ],
+            return (0, storage_file_recorder_1.recordManagedFile)(pgClient, storageConfig, {
+                bucketId: bucket.id,
+                key: finalKey,
+                contentHash: staged.contentHash,
+                mimeType: staged.contentType,
+                size: staged.size,
+                filename: staged.filename,
             });
-            return result.rows[0].id;
         });
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "1.16.1",
+  "version": "1.18.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",
@@ -62,5 +62,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "7e6cc68f5659d12ec852835a7d8fcca6b05a8f50"
+  "gitHead": "77d58bb93796be91d4e00156bb6847392584d3bc"
 }

package/physical-bucket.d.ts

@@ -1,15 +1,21 @@
 /**
- * Physical bucket coordinates: minting a name once, recording it, and building
- * an S3 config against a *known* name.
+ * Physical bucket coordinates: reading the reconciler's recorded name and
+ * building an S3 config against that known name.
  *
  * A logical bucket belongs to a tenant; a physical bucket is an S3 name. The
- * mapping is recorded on the bucket row the first time it is provisioned, and
- * from then on the recorded value is the only coordinate anything reads — no
- * name is ever recomputed from a prefix convention, and there is no
- * environment-level bucket standing in for a tenant's.
+ * mapping is recorded on the bucket row by the storage reconciler, and that
+ * value is the only coordinate anything reads — no name is ever recomputed.
  */
-import { type WithPgClient } from './request-pg-client';
 import type { BucketConfig, PresignedUrlPluginOptions, S3Config, StorageModuleConfig } from './types';
+export declare class StorageBucketNotReconciledError extends Error {
+    readonly code = "STORAGE_BUCKET_NOT_RECONCILED";
+    readonly retryable = true;
+    readonly extensions: {
+        code: string;
+        retryable: boolean;
+    };
+    constructor(bucket: BucketConfig, databaseId: string);
+}
 /**
  * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
  * a lazy getter on first use.
@@ -19,42 +25,14 @@ import type { BucketConfig, PresignedUrlPluginOptions, S3Config, StorageModuleCo
  * resolves its physical bucket from the tenant's bucket row.
  */
 export declare function resolveS3(options: PresignedUrlPluginOptions): S3Config;
-/**
- * Mint the physical S3 bucket name for a logical bucket's first provision.
- *
- * This is a naming *policy*, consulted exactly once per bucket — before the
- * physical bucket exists. Once provisioned, the recorded `physical_name` on the
- * row is authoritative and this function must not be consulted again.
- *
- * There is no fallback to the configured `s3.bucket`: a deployment-wide bucket
- * name is not a tenant's storage, and silently minting one is how objects ended
- * up in a bucket no database owned. A deployment that wants per-tenant buckets
- * must supply the policy.
- */
-export declare function mintPhysicalBucketName(options: PresignedUrlPluginOptions, databaseId: string, bucketKey: string): string;
 /**
  * Build the S3 config for a *known* physical bucket. `physicalName` is
- * required — callers must resolve the coordinate (stored row value, or a
- * freshly provisioned name) before getting here. No name is ever recomputed.
+ * required — callers must resolve the coordinate from the stored row value
+ * before getting here. No name is ever recomputed.
  */
 export declare function resolveS3ForDatabase(options: PresignedUrlPluginOptions, storageConfig: StorageModuleConfig, physicalName: string): S3Config;
 /**
- * First provision of a logical bucket: mint a name, create the physical S3
- * bucket, and record the exact name on the source row. Returns the recorded
- * physical name.
- *
- * Only called when the row has no `physical_name` yet. Afterwards the stored
- * value is the durable coordinate: route resolution and every later read use
- * it verbatim; nothing is recomputed.
- *
- * The record write runs in the system lane (privileged role, so it bypasses the
- * RLS that stops request roles from UPDATE-ing bucket rows) — it is server
- * bookkeeping, not request data. It still carries the tenant `database_id`
- * claim, because the buckets table's catalog-sync trigger calls
- * `jwt_private.current_database_id()` and would otherwise raise
- * DATABASE_CLAIM_REQUIRED; `withRequestPgClient` applies that claim inside the
- * write's transaction without switching off the privileged role.
- * `bucket` (the cached config) is mutated in place so subsequent reads observe
- * the recorded name without a DB round-trip.
+ * Return the reconciler's recorded physical name, or fail with a typed,
+ * retryable error while reconciliation is still pending.
  */
-export declare function provisionAndRecordPhysicalBucket(options: PresignedUrlPluginOptions, withPgClient: WithPgClient, storageConfig: StorageModuleConfig, databaseId: string, bucket: BucketConfig, allowedOrigins: string[] | null): Promise<string>;
+export declare function assertBucketReconciled(bucket: BucketConfig, databaseId: string): string;

package/physical-bucket.js

@@ -1,25 +1,32 @@
 "use strict";
 /**
- * Physical bucket coordinates: minting a name once, recording it, and building
- * an S3 config against a *known* name.
+ * Physical bucket coordinates: reading the reconciler's recorded name and
+ * building an S3 config against that known name.
  *
  * A logical bucket belongs to a tenant; a physical bucket is an S3 name. The
- * mapping is recorded on the bucket row the first time it is provisioned, and
- * from then on the recorded value is the only coordinate anything reads — no
- * name is ever recomputed from a prefix convention, and there is no
- * environment-level bucket standing in for a tenant's.
+ * mapping is recorded on the bucket row by the storage reconciler, and that
+ * value is the only coordinate anything reads — no name is ever recomputed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageBucketNotReconciledError = void 0;
 exports.resolveS3 = resolveS3;
-exports.mintPhysicalBucketName = mintPhysicalBucketName;
 exports.resolveS3ForDatabase = resolveS3ForDatabase;
-exports.provisionAndRecordPhysicalBucket = provisionAndRecordPhysicalBucket;
-const logger_1 = require("@pgpmjs/logger");
-const graphile_storage_registry_1 = require("graphile-storage-registry");
-const request_pg_client_1 = require("./request-pg-client");
-const s3_failure_1 = require("./s3-failure");
-const storage_module_cache_1 = require("./storage-module-cache");
-const log = new logger_1.Logger('graphile-presigned-url:physical-bucket');
+exports.assertBucketReconciled = assertBucketReconciled;
+class StorageBucketNotReconciledError extends Error {
+    code = 'STORAGE_BUCKET_NOT_RECONCILED';
+    retryable = true;
+    extensions = {
+        code: 'STORAGE_BUCKET_NOT_RECONCILED',
+        retryable: true,
+    };
+    constructor(bucket, databaseId) {
+        super(`STORAGE_BUCKET_NOT_RECONCILED: bucket "${bucket.key}" (id=${bucket.id}) ` +
+            `for database ${databaseId} has not yet been reconciled; the reconciler has ` +
+            'not yet recorded a physical name');
+        this.name = 'StorageBucketNotReconciledError';
+    }
+}
+exports.StorageBucketNotReconciledError = StorageBucketNotReconciledError;
 /**
  * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
  * a lazy getter on first use.
@@ -36,31 +43,10 @@ function resolveS3(options) {
     }
     return options.s3;
 }
-/**
- * Mint the physical S3 bucket name for a logical bucket's first provision.
- *
- * This is a naming *policy*, consulted exactly once per bucket — before the
- * physical bucket exists. Once provisioned, the recorded `physical_name` on the
- * row is authoritative and this function must not be consulted again.
- *
- * There is no fallback to the configured `s3.bucket`: a deployment-wide bucket
- * name is not a tenant's storage, and silently minting one is how objects ended
- * up in a bucket no database owned. A deployment that wants per-tenant buckets
- * must supply the policy.
- */
-function mintPhysicalBucketName(options, databaseId, bucketKey) {
-    if (!options.resolveBucketName) {
-        throw new Error('STORAGE_BUCKET_NAME_POLICY_MISSING: no resolveBucketName was configured, so there is ' +
-            `no name to provision for bucket "${bucketKey}" of database ${databaseId}. ` +
-            'Physical bucket naming is a deployment policy; the configured s3.bucket is a ' +
-            'connection default and is never a tenant bucket.');
-    }
-    return options.resolveBucketName(databaseId, bucketKey);
-}
 /**
  * Build the S3 config for a *known* physical bucket. `physicalName` is
- * required — callers must resolve the coordinate (stored row value, or a
- * freshly provisioned name) before getting here. No name is ever recomputed.
+ * required — callers must resolve the coordinate from the stored row value
+ * before getting here. No name is ever recomputed.
  */
 function resolveS3ForDatabase(options, storageConfig, physicalName) {
     const globalS3 = resolveS3(options);
@@ -77,46 +63,11 @@ function resolveS3ForDatabase(options, storageConfig, physicalName) {
     };
 }
 /**
- * First provision of a logical bucket: mint a name, create the physical S3
- * bucket, and record the exact name on the source row. Returns the recorded
- * physical name.
- *
- * Only called when the row has no `physical_name` yet. Afterwards the stored
- * value is the durable coordinate: route resolution and every later read use
- * it verbatim; nothing is recomputed.
- *
- * The record write runs in the system lane (privileged role, so it bypasses the
- * RLS that stops request roles from UPDATE-ing bucket rows) — it is server
- * bookkeeping, not request data. It still carries the tenant `database_id`
- * claim, because the buckets table's catalog-sync trigger calls
- * `jwt_private.current_database_id()` and would otherwise raise
- * DATABASE_CLAIM_REQUIRED; `withRequestPgClient` applies that claim inside the
- * write's transaction without switching off the privileged role.
- * `bucket` (the cached config) is mutated in place so subsequent reads observe
- * the recorded name without a DB round-trip.
+ * Return the reconciler's recorded physical name, or fail with a typed,
+ * retryable error while reconciliation is still pending.
  */
-async function provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, allowedOrigins) {
-    const s3BucketName = mintPhysicalBucketName(options, databaseId, bucket.key);
-    if (options.ensureBucketProvisioned && !(0, storage_module_cache_1.isS3BucketProvisioned)(s3BucketName)) {
-        log.info(`Lazy-provisioning S3 bucket "${s3BucketName}" for database ${databaseId}`);
-        try {
-            await options.ensureBucketProvisioned(s3BucketName, bucket.type, databaseId, allowedOrigins);
-        }
-        catch (err) {
-            // The first upload to a bucket is where an unreachable object store is
-            // discovered, and the transport's own message is routinely empty: name the
-            // endpoint it could not reach so the response says what is misconfigured.
-            throw (0, s3_failure_1.s3FailureError)('BUCKET_PROVISION_FAILED', { endpoint: resolveS3(options).endpoint, bucket: s3BucketName, databaseId }, err);
-        }
-        (0, storage_module_cache_1.markS3BucketProvisioned)(s3BucketName);
-        log.info(`Lazy-provisioned S3 bucket "${s3BucketName}" successfully`);
-    }
-    // Record the physical coordinate on the source row. The `physical_name IS NULL`
-    // guard keeps this idempotent and race-safe across concurrent first uploads.
-    // The catalog-sync trigger on this UPDATE needs `jwt.claims.database_id`, so the
-    // write runs under the resolved database claim (privileged role preserved).
-    await (0, request_pg_client_1.withRequestPgClient)(withPgClient, { 'jwt.claims.database_id': databaseId }, (client) => (0, graphile_storage_registry_1.recordPhysicalName)((query) => client.query(query), storageConfig.bucketsQualifiedName, bucket.id, s3BucketName));
-    bucket.physical_name = s3BucketName;
-    log.info(`Recorded physical_name="${s3BucketName}" on bucket ${bucket.id}`);
-    return s3BucketName;
+function assertBucketReconciled(bucket, databaseId) {
+    if (bucket.physical_name !== null)
+        return bucket.physical_name;
+    throw new StorageBucketNotReconciledError(bucket, databaseId);
 }

package/plugin.js

@@ -34,6 +34,7 @@ const managed_upload_1 = require("./managed-upload");
 const physical_bucket_1 = require("./physical-bucket");
 const request_pg_client_1 = require("./request-pg-client");
 const s3_signer_1 = require("./s3-signer");
+const storage_file_recorder_1 = require("./storage-file-recorder");
 const storage_module_cache_1 = require("./storage-module-cache");
 const log = new logger_1.Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
@@ -202,11 +203,9 @@ function createPresignedUrlPlugin(options) {
                                     const bucket = await (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (pgClient) => resolveUploadBucket(pgClient, storageConfig, databaseId, vals.bucketKey ?? null, vals.ownerId ?? null, vals.isPublic === true));
                                     if (!bucket)
                                         throw new Error('BUCKET_NOT_FOUND');
-                                    // First provision mints + records the coordinate; afterwards the
-                                    // stored physical_name is authoritative and nothing is recomputed.
-                                    const physicalName = bucket.physical_name === null
-                                        ? await (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
-                                        : bucket.physical_name;
+                                    // The reconciler records the coordinate; consumers never
+                                    // recompute it from the logical bucket row.
+                                    const physicalName = (0, physical_bucket_1.assertBucketReconciled)(bucket, databaseId);
                                     const s3ForDb = (0, physical_bucket_1.resolveS3ForDatabase)(options, storageConfig, physicalName);
                                     // File row INSERT under the request role (RLS enforced).
                                     return (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, (txClient) => processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
@@ -309,11 +308,9 @@ function createPresignedUrlPlugin(options) {
                                     if (totalSize > storageConfig.maxBulkTotalSize) {
                                         throw new Error(`BULK_UPLOAD_SIZE_EXCEEDED: ${totalSize} bytes exceeds maximum of ${storageConfig.maxBulkTotalSize} bytes per batch`);
                                     }
-                                    // First provision mints + records the coordinate; afterwards the
-                                    // stored physical_name is authoritative and nothing is recomputed.
-                                    const physicalName = bucket.physical_name === null
-                                        ? await (0, physical_bucket_1.provisionAndRecordPhysicalBucket)(options, vals.withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
-                                        : bucket.physical_name;
+                                    // The reconciler records the coordinate; consumers never
+                                    // recompute it from the logical bucket row.
+                                    const physicalName = (0, physical_bucket_1.assertBucketReconciled)(bucket, databaseId);
                                     const s3ForDb = (0, physical_bucket_1.resolveS3ForDatabase)(options, storageConfig, physicalName);
                                     // File row INSERTs under the request role (RLS enforced).
                                     return (0, request_pg_client_1.withRequestPgClient)(vals.withPgClient, vals.pgSettings, async (txClient) => {
@@ -616,32 +613,16 @@ 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. 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) {
-        columns.push('owner_id');
-        values.push(bucket.owner_id);
-    }
-    if (previousVersionId) {
-        columns.push('previous_version_id');
-        values.push(previousVersionId);
-    }
-    if (derivedPath) {
-        columns.push('path');
-        values.push(derivedPath);
-    }
-    const placeholders = values.map((_, i) => `$${i + 1}`).join(', ');
-    const fileResult = await txClient.query({
-        text: `INSERT INTO ${storageConfig.filesQualifiedName}
-           (${columns.join(', ')})
-           VALUES (${placeholders})
-           RETURNING id`,
-        values,
+    const fileId = await (0, storage_file_recorder_1.recordManagedFile)(txClient, storageConfig, {
+        bucketId: bucket.id,
+        key: s3Key,
+        contentHash,
+        mimeType: contentType,
+        size,
+        filename: filename || null,
+        previousVersionId,
+        path: derivedPath,
     });
-    const fileId = fileResult.rows[0].id;
     // Generate presigned PUT URL
     const uploadUrl = await (0, s3_signer_1.generatePresignedPutUrl)(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
     const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();

package/storage-file-recorder.d.ts

@@ -0,0 +1,27 @@
+import type { StorageModuleConfig } from './types';
+interface RecordManagedFileInput {
+    bucketId: string;
+    key: string;
+    contentHash: string;
+    mimeType: string;
+    size: number;
+    filename: string | null | undefined;
+    previousVersionId?: string | null;
+    path?: string | null;
+}
+/**
+ * Record a managed file through the storage plane's generated recorder.
+ *
+ * The recorder owns the files-table insert so bucket inheritance and claims
+ * attribution run at the database boundary. Optional arguments are only named
+ * when the generated function supports them and the caller has a value.
+ */
+export declare function recordManagedFile(pgClient: {
+    query: (opts: {
+        text: string;
+        values: unknown[];
+    }) => Promise<{
+        rows: unknown[];
+    }>;
+}, storageConfig: StorageModuleConfig, input: RecordManagedFileInput): Promise<string>;
+export {};

package/storage-file-recorder.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordManagedFile = recordManagedFile;
+/**
+ * Record a managed file through the storage plane's generated recorder.
+ *
+ * The recorder owns the files-table insert so bucket inheritance and claims
+ * attribution run at the database boundary. Optional arguments are only named
+ * when the generated function supports them and the caller has a value.
+ */
+async function recordManagedFile(pgClient, storageConfig, input) {
+    if (!storageConfig.recorderQualifiedName) {
+        throw new Error(`STORAGE_RECORDER_MISSING: storage module ${storageConfig.id} (${storageConfig.filesTableName}) ` +
+            `must expose ${storageConfig.filesTableName}_record_file in its private schema`);
+    }
+    if (input.previousVersionId != null && !storageConfig.hasVersioning) {
+        throw new Error(`STORAGE_VERSIONING_UNSUPPORTED: storage module ${storageConfig.id} (${storageConfig.filesTableName}) ` +
+            'does not support previous_version_id');
+    }
+    if (input.path != null && !storageConfig.hasPathShares) {
+        throw new Error(`STORAGE_PATH_SHARES_UNSUPPORTED: storage module ${storageConfig.id} (${storageConfig.filesTableName}) ` +
+            'does not support path');
+    }
+    const args = [
+        'bucket_id := $1::uuid',
+        'key := $2::text',
+        'content_hash := $3::text',
+        'mime_type := $4::text',
+        'size := $5::bigint',
+        'filename := $6::text',
+        'upload := $7::jsonb',
+    ];
+    const values = [
+        input.bucketId,
+        input.key,
+        input.contentHash,
+        input.mimeType,
+        input.size,
+        input.filename ?? null,
+        null,
+    ];
+    if (storageConfig.hasVersioning && input.previousVersionId != null) {
+        args.push(`previous_version_id := $${values.length + 1}::uuid`);
+        values.push(input.previousVersionId);
+    }
+    if (storageConfig.hasPathShares && input.path != null) {
+        args.push(`path := $${values.length + 1}::text`);
+        values.push(input.path);
+    }
+    const result = await pgClient.query({
+        text: `SELECT id FROM ${storageConfig.recorderQualifiedName}(${args.join(', ')})`,
+        values,
+    });
+    return result.rows[0].id;
+}

package/storage-module-cache.d.ts

@@ -91,14 +91,6 @@ export declare function getBucketConfig(pgClient: {
         rows: unknown[];
     }>;
 }, storageConfig: StorageModuleConfig, databaseId: string, bucketKey: string, ownerId?: string): Promise<BucketConfig | null>;
-/**
- * Check whether an S3 bucket has already been provisioned (cached).
- */
-export declare function isS3BucketProvisioned(s3BucketName: string): boolean;
-/**
- * Mark an S3 bucket as provisioned in the in-memory cache.
- */
-export declare function markS3BucketProvisioned(s3BucketName: string): void;
 /**
  * Clear the storage module cache AND bucket cache.
  * Useful for testing or schema changes.

package/storage-module-cache.js

@@ -5,8 +5,6 @@ exports.loadAllStorageModules = loadAllStorageModules;
 exports.resolveStorageConfigFromCodec = resolveStorageConfigFromCodec;
 exports.storedPhysicalName = storedPhysicalName;
 exports.getBucketConfig = getBucketConfig;
-exports.isS3BucketProvisioned = isS3BucketProvisioned;
-exports.markS3BucketProvisioned = markS3BucketProvisioned;
 exports.clearStorageModuleCache = clearStorageModuleCache;
 exports.clearBucketCache = clearBucketCache;
 const logger_1 = require("@pgpmjs/logger");
@@ -52,6 +50,7 @@ const ALL_STORAGE_MODULES_QUERY = `
     bt.name AS buckets_table,
     fs.schema_name AS files_schema,
     ft.name AS files_table,
+    ps.schema_name AS private_schema,
     sm.endpoint,
     sm.public_url_prefix,
     sm.provider,
@@ -64,6 +63,7 @@ const ALL_STORAGE_MODULES_QUERY = `
     sm.max_bulk_files,
     sm.max_bulk_total_size,
     sm.has_path_shares,
+    sm.has_versioning,
     sm.has_confirm_upload,
     es.schema_name AS entity_schema,
     et.name AS entity_table
@@ -72,6 +72,7 @@ const ALL_STORAGE_MODULES_QUERY = `
   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
+  LEFT JOIN metaschema_public.schema ps ON ps.id = sm.private_schema_id
   LEFT JOIN metaschema_public.table et ON et.id = sm.entity_table_id
   LEFT JOIN metaschema_public.schema es ON es.id = et.schema_id
   WHERE sm.database_id = $1
@@ -85,6 +86,9 @@ function buildConfig(row) {
         id: row.id,
         bucketsQualifiedName: quotes_1.QuoteUtils.quoteQualifiedIdentifier(row.buckets_schema, row.buckets_table),
         filesQualifiedName: quotes_1.QuoteUtils.quoteQualifiedIdentifier(row.files_schema, row.files_table),
+        recorderQualifiedName: row.private_schema
+            ? quotes_1.QuoteUtils.quoteQualifiedIdentifier(row.private_schema, `${row.files_table}_record_file`)
+            : null,
         schemaName: row.buckets_schema,
         bucketsTableName: row.buckets_table,
         filesTableName: row.files_table,
@@ -103,6 +107,7 @@ function buildConfig(row) {
         maxFilenameLength: row.max_filename_length ?? DEFAULT_MAX_FILENAME_LENGTH,
         cacheTtlSeconds,
         hasPathShares: row.has_path_shares ?? false,
+        hasVersioning: row.has_versioning ?? 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,
@@ -264,34 +269,6 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
     log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.scope})`);
     return config;
 }
-// --- S3 bucket existence cache ---
-/**
- * In-memory set of S3 bucket names that are known to exist.
- *
- * Used by the lazy provisioning logic in the presigned URL plugin:
- * before generating a presigned PUT URL, the plugin checks this set.
- * If the bucket name is absent, it calls `ensureBucketProvisioned`
- * to create the S3 bucket, then adds the name here. Subsequent
- * requests for the same bucket skip the provisioning entirely.
- *
- * No TTL needed — S3 buckets are never deleted during normal operation.
- * The set resets on server restart, which is fine because the
- * provisioner's createBucket is idempotent (handles "already exists").
- */
-const provisionedBuckets = new Set();
-/**
- * Check whether an S3 bucket has already been provisioned (cached).
- */
-function isS3BucketProvisioned(s3BucketName) {
-    return provisionedBuckets.has(s3BucketName);
-}
-/**
- * Mark an S3 bucket as provisioned in the in-memory cache.
- */
-function markS3BucketProvisioned(s3BucketName) {
-    provisionedBuckets.add(s3BucketName);
-    log.debug(`Marked S3 bucket "${s3BucketName}" as provisioned`);
-}
 /**
  * Clear the storage module cache AND bucket cache.
  * Useful for testing or schema changes.
@@ -299,7 +276,6 @@ function markS3BucketProvisioned(s3BucketName) {
 function clearStorageModuleCache() {
     storageModuleCache.clear();
     bucketCache.clear();
-    provisionedBuckets.clear();
 }
 /**
  * Clear cached bucket entries for a specific database.