graphile-presigned-url-plugin 1.16.1 → 1.18.0

package/esm/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/esm/index.js

@@ -32,10 +32,10 @@ export { resolveDefaultBucket } from './default-bucket';
 export { createDownloadUrlPlugin } from './download-url-field';
 export { clearFileRefFieldCache, FileRefFieldNotRegisteredError, getFileRefFieldBinding } from './file-ref-registry';
 export { assertUploadAllowedByBucket, buildFileProjection, finalizeStagedUpload, 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 { 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 { clearBucketCache, clearStorageModuleCache, getBucketConfig, loadAllStorageModules, resolveStorageConfigFromCodec, resolveStorageModuleByFileId } from './storage-module-cache';

package/esm/managed-upload.js

@@ -21,9 +21,10 @@ import { Logger } from '@pgpmjs/logger';
 import { resolveDefaultBucket } from './default-bucket';
 import { isLiveFileRow, statusSelectFragment } from './file-lifecycle';
 import { getFileRefFieldBinding } from './file-ref-registry';
-import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
+import { assertBucketReconciled, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
 import { copyS3Object, deleteS3Object } from './s3-signer';
+import { recordManagedFile } from './storage-file-recorder';
 import { getBucketConfig, loadAllStorageModules } from './storage-module-cache';
 const log = new Logger('graphile-presigned-url:managed-upload');
 /**
@@ -133,9 +134,7 @@ export 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 provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, storageConfig.allowedOrigins)
-        : bucket.physical_name;
+    const physicalName = assertBucketReconciled(bucket, databaseId);
     return {
         databaseId,
         storageConfig,
@@ -252,22 +251,14 @@ export async function finalizeStagedUpload(args) {
     let fileId;
     try {
         fileId = await 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 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/esm/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/esm/physical-bucket.js

@@ -1,19 +1,25 @@
 /**
- * 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 { Logger } from '@pgpmjs/logger';
-import { recordPhysicalName } from 'graphile-storage-registry';
-import { withRequestPgClient } from './request-pg-client';
-import { s3FailureError } from './s3-failure';
-import { isS3BucketProvisioned, markS3BucketProvisioned } from './storage-module-cache';
-const log = new Logger('graphile-presigned-url:physical-bucket');
+export 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';
+    }
+}
 /**
  * Resolve the plugin's S3 connection (credentials, endpoint, region), memoizing
  * a lazy getter on first use.
@@ -30,31 +36,10 @@ export 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.
- */
-export 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.
  */
 export function resolveS3ForDatabase(options, storageConfig, physicalName) {
     const globalS3 = resolveS3(options);
@@ -71,46 +56,11 @@ export 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.
  */
-export async function provisionAndRecordPhysicalBucket(options, withPgClient, storageConfig, databaseId, bucket, allowedOrigins) {
-    const s3BucketName = mintPhysicalBucketName(options, databaseId, bucket.key);
-    if (options.ensureBucketProvisioned && !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 s3FailureError('BUCKET_PROVISION_FAILED', { endpoint: resolveS3(options).endpoint, bucket: s3BucketName, databaseId }, err);
-        }
-        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 withRequestPgClient(withPgClient, { 'jwt.claims.database_id': databaseId }, (client) => 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;
+export function assertBucketReconciled(bucket, databaseId) {
+    if (bucket.physical_name !== null)
+        return bucket.physical_name;
+    throw new StorageBucketNotReconciledError(bucket, databaseId);
 }

package/esm/plugin.js

@@ -27,9 +27,10 @@ import { validateCustomKey } from './custom-key';
 import { resolveDefaultBucket } from './default-bucket';
 import { isLiveFileRow, statusSelectFragment } from './file-lifecycle';
 import { buildFileProjection } from './managed-upload';
-import { provisionAndRecordPhysicalBucket, resolveS3ForDatabase } from './physical-bucket';
+import { assertBucketReconciled, resolveS3ForDatabase } from './physical-bucket';
 import { withRequestPgClient } from './request-pg-client';
 import { deleteS3Object, generatePresignedPutUrl } from './s3-signer';
+import { recordManagedFile } from './storage-file-recorder';
 import { getBucketConfig, loadAllStorageModules, resolveStorageConfigFromCodec, storedPhysicalName } from './storage-module-cache';
 const log = new Logger('graphile-presigned-url:plugin');
 // --- Protocol-level constants (not configurable) ---
@@ -198,11 +199,9 @@ export function createPresignedUrlPlugin(options) {
                                     const bucket = await 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 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 = assertBucketReconciled(bucket, databaseId);
                                     const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
                                     // File row INSERT under the request role (RLS enforced).
                                     return withRequestPgClient(vals.withPgClient, vals.pgSettings, (txClient) => processSingleFile(options, txClient, storageConfig, databaseId, bucket, s3ForDb, {
@@ -305,11 +304,9 @@ export 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 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 = assertBucketReconciled(bucket, databaseId);
                                     const s3ForDb = resolveS3ForDatabase(options, storageConfig, physicalName);
                                     // File row INSERTs under the request role (RLS enforced).
                                     return withRequestPgClient(vals.withPgClient, vals.pgSettings, async (txClient) => {
@@ -612,32 +609,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 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 generatePresignedPutUrl(s3ForDb, s3Key, contentType, size, storageConfig.uploadUrlExpirySeconds);
     const expiresAt = new Date(Date.now() + storageConfig.uploadUrlExpirySeconds * 1000).toISOString();

package/esm/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/esm/storage-file-recorder.js

@@ -0,0 +1,52 @@
+/**
+ * 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 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/esm/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/esm/storage-module-cache.js

@@ -41,6 +41,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,
@@ -53,6 +54,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
@@ -61,6 +63,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
@@ -74,6 +77,9 @@ function buildConfig(row) {
         id: row.id,
         bucketsQualifiedName: QuoteUtils.quoteQualifiedIdentifier(row.buckets_schema, row.buckets_table),
         filesQualifiedName: QuoteUtils.quoteQualifiedIdentifier(row.files_schema, row.files_table),
+        recorderQualifiedName: row.private_schema
+            ? QuoteUtils.quoteQualifiedIdentifier(row.private_schema, `${row.files_table}_record_file`)
+            : null,
         schemaName: row.buckets_schema,
         bucketsTableName: row.buckets_table,
         filesTableName: row.files_table,
@@ -92,6 +98,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,
@@ -253,34 +260,6 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
     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).
- */
-export function isS3BucketProvisioned(s3BucketName) {
-    return provisionedBuckets.has(s3BucketName);
-}
-/**
- * Mark an S3 bucket as provisioned in the in-memory cache.
- */
-export 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.
@@ -288,7 +267,6 @@ export function markS3BucketProvisioned(s3BucketName) {
 export function clearStorageModuleCache() {
     storageModuleCache.clear();
     bucketCache.clear();
-    provisionedBuckets.clear();
 }
 /**
  * Clear cached bucket entries for a specific database.

package/esm/types.d.ts

@@ -12,10 +12,9 @@ export interface BucketConfig {
     max_file_size: number | null;
     allow_custom_keys: boolean;
     /**
-     * The physical S3/MinIO bucket name recorded when the physical bucket was
-     * first provisioned. NULL until the first upload provisions it. Once set,
-     * it is the source of truth for the physical bucket — reads never
-     * reconstruct the name from a prefix convention.
+     * The physical S3/MinIO bucket name recorded by reconciliation. NULL until
+     * reconciliation completes. Once set, it is the source of truth for the
+     * physical bucket — reads never reconstruct the name.
      */
     physical_name: string | null;
 }
@@ -35,6 +34,8 @@ export interface StorageModuleConfig {
     bucketsTableName: string;
     /** Files table name */
     filesTableName: string;
+    /** Qualified generated managed-file recorder, or null when unavailable */
+    recorderQualifiedName: string | null;
     /** Scope name (e.g., 'app', 'org', 'team') */
     scope: string;
     /** Entity table ID for entity-scoped storage (NULL for app-level) */
@@ -67,6 +68,8 @@ export interface StorageModuleConfig {
      * without it every row is treated as live, because there is nothing to read.
      */
     hasConfirmUpload: boolean;
+    /** Whether the files table carries the versioning chain. */
+    hasVersioning: boolean;
     /** Max files per requestBulkUploadUrls batch (default: 100) */
     maxBulkFiles: number;
     /** Max total size per bulk upload batch in bytes (default: 1GB) */
@@ -174,51 +177,10 @@ export interface S3Config {
  * env-var reads and S3Client creation at module import time.
  */
 export type S3ConfigOrGetter = S3Config | (() => S3Config);
-/**
- * Function to derive the actual S3 bucket name for a given database and bucket key.
- *
- * When provided, the presigned URL plugin calls this on every request
- * to determine which S3 bucket to use — enabling per-(database, bucketKey)
- * isolation. If not provided, falls back to `s3Config.bucket` (global).
- *
- * @param databaseId - The metaschema database UUID
- * @param bucketKey - The logical bucket key (e.g., "public", "private")
- * @returns The S3 bucket name for this database + bucket key
- */
-export type BucketNameResolver = (databaseId: string, bucketKey: string) => string;
-/**
- * Callback to lazily provision an S3 bucket on first use.
- *
- * Called by the presigned URL plugin before generating a presigned PUT URL
- * when the bucket has not been seen before (tracked in an in-memory cache).
- * The implementation should create and fully configure the S3 bucket
- * (privacy policies, CORS, lifecycle rules, etc.) — or no-op if the
- * bucket already exists.
- *
- * @param bucketName - The S3 bucket name to provision
- * @param accessType - The logical bucket type ('public', 'private', 'temp')
- * @param databaseId - The metaschema database UUID
- * @param allowedOrigins - Per-database CORS origins (from storage_module), or null to use global fallback
- */
-export type EnsureBucketProvisioned = (bucketName: string, accessType: 'public' | 'private' | 'temp', databaseId: string, allowedOrigins: string[] | null) => Promise<void>;
 /**
  * Plugin options for the presigned URL plugin.
  */
 export interface PresignedUrlPluginOptions {
     /** S3 configuration (concrete or lazy getter) */
     s3: S3ConfigOrGetter;
-    /**
-     * Optional function to resolve S3 bucket name per-database.
-     * When set, each database gets its own S3 bucket instead of sharing
-     * the global `s3Config.bucket`. The S3 credentials (client) remain shared.
-     */
-    resolveBucketName?: BucketNameResolver;
-    /**
-     * Optional callback to lazily provision an S3 bucket on first upload.
-     * When set, the plugin calls this before generating a presigned PUT URL
-     * for any S3 bucket it hasn't seen yet (tracked in an in-memory cache).
-     * This enables graceful bucket creation without requiring buckets to
-     * exist at database provisioning time.
-     */
-    ensureBucketProvisioned?: EnsureBucketProvisioned;
 }