graphile-bucket-provisioner-plugin 1.18.0 → 1.19.0

package/README.md

@@ -5,7 +5,7 @@ queueing storage reconciliation.
 
 The constructive-db `storage:provision_bucket` job is the only component that
 mints physical S3 bucket names, provisions S3, and records `physical_name`.
-This plugin resolves the logical bucket under RLS and enqueues that job; it
+This plugin resolves the logical bucket under RLS and requests that job; it
 does not call S3 or derive a physical name.
 
 ## Installation
@@ -32,16 +32,18 @@ mutation {
     bucketId
     bucketKey
     physicalName
-    jobId
+    provisionRequestedAt
   }
 }
 ```
 
-`provisionBucket` resolves the bucket row under RLS and enqueues the same
-`storage:provision_bucket` job used by the database INSERT trigger. Database
-scope jobs include `database_id`, use the `bucket:<uuid>` queue, and have
-25 attempts. Platform scope jobs use the platform trigger payload. Enqueue
-failures are returned as GraphQL errors.
+`provisionBucket` resolves the bucket row under RLS and calls the storage
+module's `<buckets>_provision(bucket_id)`, which stamps the row's
+`provision_requested_at` as the caller and returns the row. The bucket's UPDATE
+job trigger then enqueues the same `storage:provision_bucket` job used on
+INSERT, keyed `storage:provision_bucket:<uuid>` on the `bucket:<uuid>` queue, so
+repeated requests while a job is waiting collapse into it. Failures are
+returned as GraphQL errors.
 
 The payload fields are:
 
@@ -50,7 +52,7 @@ The payload fields are:
 | `bucketId` | Logical bucket row ID |
 | `bucketKey` | Logical bucket key |
 | `physicalName` | Recorded physical name, or `null` while reconciliation is pending |
-| `jobId` | ID of the queued reconciler job |
+| `provisionRequestedAt` | When reconciliation was last requested |
 
 There are no plugin options: S3 connection details, naming, CORS, versioning,
 and physical-name recording belong to the reconciler.

package/esm/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * Provides an explicit `provisionBucket` reconciliation request mutation for
  * PostGraphile v5.
  */
 export { BucketProvisionerPlugin, createBucketProvisionerPlugin } from './plugin';

package/esm/index.js

@@ -1,7 +1,7 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * Provides an explicit `provisionBucket` reconciliation request mutation for
  * PostGraphile v5.
  */
 export { BucketProvisionerPlugin, createBucketProvisionerPlugin } from './plugin';

package/esm/plugin.d.ts

@@ -3,9 +3,10 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
- *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then queues the same storage reconciler job used by the INSERT trigger.
+ * 1. `provisionBucket` mutation — explicitly request reconciliation for a
+ *    logical bucket row in the database. Stamps the bucket's
+ *    `provision_requested_at` via RLS; the bucket's own job trigger then
+ *    queues the same storage reconciler job used on INSERT.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -19,7 +20,7 @@ import type { GraphileConfig } from 'graphile-config';
  * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket key to request reconciliation (or re-reconciliation) for the
  *    bucket. Protected by RLS on the buckets table.
  *
  */

package/esm/plugin.js

@@ -3,9 +3,10 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
- *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then queues the same storage reconciler job used by the INSERT trigger.
+ * 1. `provisionBucket` mutation — explicitly request reconciliation for a
+ *    logical bucket row in the database. Stamps the bucket's
+ *    `provision_requested_at` via RLS; the bucket's own job trigger then
+ *    queues the same storage reconciler job used on INSERT.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -21,24 +22,7 @@ import { extendSchema, gql } from 'graphile-utils';
  * resolution in the explicit provisionBucket mutation).
  */
 const ALL_STORAGE_MODULES_QUERY = `
-  SELECT
-    sm.id,
-    sm.database_id,
-    sm.buckets_table_id,
-    sm.scope,
-    sm.entity_field,
-    sm.entity_table_id,
-    bs.schema_name AS buckets_schema,
-    bt.name AS buckets_table,
-    sm.allowed_origins,
-    es.schema_name AS entity_schema,
-    et.name 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
-  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
+  SELECT * FROM function_resolution.storage_modules()
 `;
 /**
  * Run a query against a grafast `withPgClient` client.
@@ -73,7 +57,7 @@ function scopeKeyColumn(storageModule) {
  * silently picking.
  */
 async function resolveBucketByKey(pgClient, databaseId, bucketKey, ownerId) {
-    const result = await runQuery(pgClient, ALL_STORAGE_MODULES_QUERY, [databaseId]);
+    const result = await runQuery(pgClient, ALL_STORAGE_MODULES_QUERY);
     const modules = result.rows;
     if (modules.length === 0) {
         throw new Error(`STORAGE_MODULE_NOT_PROVISIONED: database ${databaseId} has no storage modules`);
@@ -124,86 +108,22 @@ async function resolveDatabaseId(pgClient) {
     const result = await runQuery(pgClient, `SELECT jwt_private.current_database_id() AS id`);
     return result.rows[0]?.id ?? null;
 }
-async function resolveEntityContext(pgClient, storageModule) {
-    const result = await runQuery(pgClient, `SELECT r.entity_type, r.get_org_fn_schema, r.get_org_fn
-     FROM metaschema.resolve_entity_context_by_field($1::uuid, $2::uuid, $3::text) r`, [storageModule.database_id, storageModule.buckets_table_id, storageModule.entity_field]);
-    return result.rows[0] ?? {
-        entity_type: null,
-        get_org_fn_schema: null,
-        get_org_fn: null,
-    };
-}
 /**
- * Mirror the storage module generator's data_job_trigger shape from
- * `packages/metaschema-generators/deploy/schemas/metaschema_generators/procedures/storage_module.sql`
- * and the add_job argument assembly in
- * `packages/ast-plpgsql/deploy/schemas/ast_plpgsql_helpers/procedures/triggers/job_trigger.sql`.
- * A callable enqueue function beside the trigger would be the durable fix for
- * this deliberate mirroring, but is out of scope here.
- *
- * The three scope shapes differ only in the payload entries and the identity
- * arguments, so those are the only parts a caller supplies — the identifier,
- * queue, retry, and priority policy exist exactly once.
+ * Request reconciliation through the storage module's generated
+ * `<private>.<buckets>_provision(bucket_id)`. It runs as the request role and
+ * stamps the bucket's `provision_requested_at` under the buckets table's own
+ * RLS; the bucket's UPDATE job trigger then enqueues the reconciler (keyed and
+ * queued on the bucket, so repeated requests collapse into one pending job).
+ * It returns the updated bucket row.
  */
-function addJobStatement(payloadEntries, identityArgs) {
-    return `SELECT (app_jobs.add_job(
-      identifier => 'storage:provision_bucket',
-      payload => json_build_object(${payloadEntries}),
-      queue_name => 'bucket:' || $1::text,
-      max_attempts => 25,
-      priority => 0${identityArgs}
-    )).id AS id`;
-}
-async function enqueueReconciliationJob(pgClient, storageModule, bucket) {
-    const scope = storageModule.scope;
-    const entityField = storageModule.entity_field;
-    let text;
-    let values;
-    if (entityField === null) {
-        text = addJobStatement(`'id', $1::uuid,
-        'scope', $2::text`, '');
-        values = [bucket.id, scope];
-    }
-    else if (entityField === 'database_id') {
-        const databaseId = bucket.scope_key;
-        if (!databaseId) {
-            throw new Error(`STORAGE_BUCKET_SCOPE_KEY_MISSING: bucket ${bucket.id} has no database_id`);
-        }
-        text = addJobStatement(`'database_id', $2::uuid,
-        'id', $1::uuid,
-        'scope', $3::text`, `,
-      db_id => $2,
-      entity_id => $2,
-      organization_id => NULL,
-      entity_type => $3`);
-        values = [bucket.id, databaseId, scope];
-    }
-    else if (entityField === 'owner_id') {
-        const ownerId = bucket.scope_key;
-        if (!ownerId) {
-            throw new Error(`STORAGE_BUCKET_SCOPE_KEY_MISSING: bucket ${bucket.id} has no owner_id`);
-        }
-        const context = await resolveEntityContext(pgClient, storageModule);
-        const orgFunction = context.get_org_fn_schema && context.get_org_fn
-            ? `${QuoteUtils.quoteQualifiedIdentifier(context.get_org_fn_schema, context.get_org_fn)}($3::text, $2::uuid)`
-            : 'NULL';
-        text = addJobStatement(`'id', $1::uuid,
-        'owner_id', $2::uuid,
-        'scope', $3::text`, `,
-      entity_id => $2,
-      organization_id => ${orgFunction},
-      entity_type => $3`);
-        values = [bucket.id, ownerId, scope];
-    }
-    else {
-        throw new Error(`STORAGE_BUCKET_ENTITY_FIELD_UNSUPPORTED: ${entityField}`);
-    }
-    const result = await runQuery(pgClient, text, values);
-    const jobId = result.rows[0]?.id;
-    if (!jobId) {
-        throw new Error(`STORAGE_BUCKET_JOB_ID_MISSING: bucket ${bucket.id}`);
+async function requestReconciliation(pgClient, storageModule, bucket) {
+    const provisionFunction = QuoteUtils.quoteQualifiedIdentifier(storageModule.private_schema, `${storageModule.buckets_table}_provision`);
+    const result = await runQuery(pgClient, `SELECT id, key, physical_name, to_json(provision_requested_at) #>> '{}' AS provision_requested_at FROM ${provisionFunction}($1::uuid)`, [bucket.id]);
+    const row = result.rows[0];
+    if (!row?.id) {
+        throw new Error(`STORAGE_BUCKET_PROVISION_EMPTY: bucket ${bucket.id}`);
     }
-    return jobId;
+    return row;
 }
 // --- Plugin factory ---
 /**
@@ -212,7 +132,7 @@ async function enqueueReconciliationJob(pgClient, storageModule, bucket) {
  * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket key to request reconciliation (or re-reconciliation) for the
  *    bucket. Protected by RLS on the buckets table.
  *
  */
@@ -231,22 +151,23 @@ export function createBucketProvisionerPlugin() {
       }
 
       type ProvisionBucketPayload {
-        """The logical bucket row that was queued for reconciliation."""
+        """The logical bucket row whose reconciliation was requested."""
         bucketId: UUID!
         bucketKey: String!
         """The physical bucket name already recorded, or null when reconciliation has not completed."""
         physicalName: String
-        """The reconciler job enqueued to provision this bucket."""
-        jobId: UUID!
+        """When reconciliation was last requested for this bucket."""
+        provisionRequestedAt: Datetime!
       }
 
       extend type Mutation {
         """
         Reconcile an S3 bucket for a logical bucket in the database.
-        Reads the bucket config via RLS, then enqueues the same
-        storage:provision_bucket job used by the INSERT trigger. This is
-        idempotent for an already-reconciled bucket; enqueue failures become
-        GraphQL errors.
+        Records the request on the bucket row via RLS; the bucket's job
+        trigger then enqueues the same storage:provision_bucket job used on
+        INSERT, and repeated requests collapse into one pending job. This is
+        idempotent for an already-reconciled bucket; failures become GraphQL
+        errors.
         """
         provisionBucket(
           input: ProvisionBucketInput!
@@ -282,12 +203,12 @@ export function createBucketProvisionerPlugin() {
                                 throw new Error('BUCKET_NOT_FOUND');
                             }
                             const { storageModule, bucket } = resolution;
-                            const jobId = await enqueueReconciliationJob(pgClient, storageModule, bucket);
+                            const provisioned = await requestReconciliation(pgClient, storageModule, bucket);
                             return {
-                                bucketId: bucket.id,
-                                bucketKey: bucket.key,
-                                physicalName: bucket.physical_name,
-                                jobId,
+                                bucketId: provisioned.id,
+                                bucketKey: provisioned.key,
+                                physicalName: provisioned.physical_name,
+                                provisionRequestedAt: provisioned.provision_requested_at,
                             };
                         });
                     });

package/esm/types.d.ts

@@ -14,15 +14,15 @@ export interface ProvisionBucketInput {
     ownerId?: string;
 }
 /**
- * Result of the provisionBucket reconciliation enqueue mutation.
+ * Result of the provisionBucket mutation: the bucket row it stamped.
  */
 export interface ProvisionBucketPayload {
-    /** The logical bucket row queued for reconciliation */
+    /** The logical bucket row whose reconciliation was requested */
     bucketId: string;
     /** The logical bucket key */
     bucketKey: string;
     /** The physical name already recorded, or null while reconciliation is pending */
     physicalName: string | null;
-    /** The queued reconciler job */
-    jobId: string;
+    /** When reconciliation was last requested */
+    provisionRequestedAt: string;
 }

package/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * Provides an explicit `provisionBucket` reconciliation request mutation for
  * PostGraphile v5.
  */
 export { BucketProvisionerPlugin, createBucketProvisionerPlugin } from './plugin';

package/index.js

@@ -2,7 +2,7 @@
 /**
  * Bucket Provisioner Plugin for PostGraphile v5
  *
- * Provides an explicit `provisionBucket` reconciliation enqueue mutation for
+ * Provides an explicit `provisionBucket` reconciliation request mutation for
  * PostGraphile v5.
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-bucket-provisioner-plugin",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Bucket provisioning plugin for PostGraphile v5 — explicitly provisions S3 buckets via a GraphQL mutation",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -58,5 +58,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.8.0"
   },
-  "gitHead": "487c4ec9ee997d7da80584a3d41d7120d4354c54"
+  "gitHead": "b6c80da2ba0532a4aaf0d0154901efa7911974d8"
 }

package/plugin.d.ts

@@ -3,9 +3,10 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
- *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then queues the same storage reconciler job used by the INSERT trigger.
+ * 1. `provisionBucket` mutation — explicitly request reconciliation for a
+ *    logical bucket row in the database. Stamps the bucket's
+ *    `provision_requested_at` via RLS; the bucket's own job trigger then
+ *    queues the same storage reconciler job used on INSERT.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -19,7 +20,7 @@ import type { GraphileConfig } from 'graphile-config';
  * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket key to request reconciliation (or re-reconciliation) for the
  *    bucket. Protected by RLS on the buckets table.
  *
  */

package/plugin.js

@@ -4,9 +4,10 @@
  *
  * Adds S3 bucket provisioning support to PostGraphile v5:
  *
- * 1. `provisionBucket` mutation — explicitly enqueue reconciliation for a
- *    logical bucket row in the database. Reads the bucket config via RLS,
- *    then queues the same storage reconciler job used by the INSERT trigger.
+ * 1. `provisionBucket` mutation — explicitly request reconciliation for a
+ *    logical bucket row in the database. Stamps the bucket's
+ *    `provision_requested_at` via RLS; the bucket's own job trigger then
+ *    queues the same storage reconciler job used on INSERT.
  *
  * Detection: Uses the `@storageBuckets` smart tag on the codec (table).
  * The storage module generator in constructive-db sets this tag on the
@@ -25,24 +26,7 @@ const graphile_utils_1 = require("graphile-utils");
  * resolution in the explicit provisionBucket mutation).
  */
 const ALL_STORAGE_MODULES_QUERY = `
-  SELECT
-    sm.id,
-    sm.database_id,
-    sm.buckets_table_id,
-    sm.scope,
-    sm.entity_field,
-    sm.entity_table_id,
-    bs.schema_name AS buckets_schema,
-    bt.name AS buckets_table,
-    sm.allowed_origins,
-    es.schema_name AS entity_schema,
-    et.name 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
-  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
+  SELECT * FROM function_resolution.storage_modules()
 `;
 /**
  * Run a query against a grafast `withPgClient` client.
@@ -77,7 +61,7 @@ function scopeKeyColumn(storageModule) {
  * silently picking.
  */
 async function resolveBucketByKey(pgClient, databaseId, bucketKey, ownerId) {
-    const result = await runQuery(pgClient, ALL_STORAGE_MODULES_QUERY, [databaseId]);
+    const result = await runQuery(pgClient, ALL_STORAGE_MODULES_QUERY);
     const modules = result.rows;
     if (modules.length === 0) {
         throw new Error(`STORAGE_MODULE_NOT_PROVISIONED: database ${databaseId} has no storage modules`);
@@ -128,86 +112,22 @@ async function resolveDatabaseId(pgClient) {
     const result = await runQuery(pgClient, `SELECT jwt_private.current_database_id() AS id`);
     return result.rows[0]?.id ?? null;
 }
-async function resolveEntityContext(pgClient, storageModule) {
-    const result = await runQuery(pgClient, `SELECT r.entity_type, r.get_org_fn_schema, r.get_org_fn
-     FROM metaschema.resolve_entity_context_by_field($1::uuid, $2::uuid, $3::text) r`, [storageModule.database_id, storageModule.buckets_table_id, storageModule.entity_field]);
-    return result.rows[0] ?? {
-        entity_type: null,
-        get_org_fn_schema: null,
-        get_org_fn: null,
-    };
-}
 /**
- * Mirror the storage module generator's data_job_trigger shape from
- * `packages/metaschema-generators/deploy/schemas/metaschema_generators/procedures/storage_module.sql`
- * and the add_job argument assembly in
- * `packages/ast-plpgsql/deploy/schemas/ast_plpgsql_helpers/procedures/triggers/job_trigger.sql`.
- * A callable enqueue function beside the trigger would be the durable fix for
- * this deliberate mirroring, but is out of scope here.
- *
- * The three scope shapes differ only in the payload entries and the identity
- * arguments, so those are the only parts a caller supplies — the identifier,
- * queue, retry, and priority policy exist exactly once.
+ * Request reconciliation through the storage module's generated
+ * `<private>.<buckets>_provision(bucket_id)`. It runs as the request role and
+ * stamps the bucket's `provision_requested_at` under the buckets table's own
+ * RLS; the bucket's UPDATE job trigger then enqueues the reconciler (keyed and
+ * queued on the bucket, so repeated requests collapse into one pending job).
+ * It returns the updated bucket row.
  */
-function addJobStatement(payloadEntries, identityArgs) {
-    return `SELECT (app_jobs.add_job(
-      identifier => 'storage:provision_bucket',
-      payload => json_build_object(${payloadEntries}),
-      queue_name => 'bucket:' || $1::text,
-      max_attempts => 25,
-      priority => 0${identityArgs}
-    )).id AS id`;
-}
-async function enqueueReconciliationJob(pgClient, storageModule, bucket) {
-    const scope = storageModule.scope;
-    const entityField = storageModule.entity_field;
-    let text;
-    let values;
-    if (entityField === null) {
-        text = addJobStatement(`'id', $1::uuid,
-        'scope', $2::text`, '');
-        values = [bucket.id, scope];
-    }
-    else if (entityField === 'database_id') {
-        const databaseId = bucket.scope_key;
-        if (!databaseId) {
-            throw new Error(`STORAGE_BUCKET_SCOPE_KEY_MISSING: bucket ${bucket.id} has no database_id`);
-        }
-        text = addJobStatement(`'database_id', $2::uuid,
-        'id', $1::uuid,
-        'scope', $3::text`, `,
-      db_id => $2,
-      entity_id => $2,
-      organization_id => NULL,
-      entity_type => $3`);
-        values = [bucket.id, databaseId, scope];
-    }
-    else if (entityField === 'owner_id') {
-        const ownerId = bucket.scope_key;
-        if (!ownerId) {
-            throw new Error(`STORAGE_BUCKET_SCOPE_KEY_MISSING: bucket ${bucket.id} has no owner_id`);
-        }
-        const context = await resolveEntityContext(pgClient, storageModule);
-        const orgFunction = context.get_org_fn_schema && context.get_org_fn
-            ? `${quotes_1.QuoteUtils.quoteQualifiedIdentifier(context.get_org_fn_schema, context.get_org_fn)}($3::text, $2::uuid)`
-            : 'NULL';
-        text = addJobStatement(`'id', $1::uuid,
-        'owner_id', $2::uuid,
-        'scope', $3::text`, `,
-      entity_id => $2,
-      organization_id => ${orgFunction},
-      entity_type => $3`);
-        values = [bucket.id, ownerId, scope];
-    }
-    else {
-        throw new Error(`STORAGE_BUCKET_ENTITY_FIELD_UNSUPPORTED: ${entityField}`);
-    }
-    const result = await runQuery(pgClient, text, values);
-    const jobId = result.rows[0]?.id;
-    if (!jobId) {
-        throw new Error(`STORAGE_BUCKET_JOB_ID_MISSING: bucket ${bucket.id}`);
+async function requestReconciliation(pgClient, storageModule, bucket) {
+    const provisionFunction = quotes_1.QuoteUtils.quoteQualifiedIdentifier(storageModule.private_schema, `${storageModule.buckets_table}_provision`);
+    const result = await runQuery(pgClient, `SELECT id, key, physical_name, to_json(provision_requested_at) #>> '{}' AS provision_requested_at FROM ${provisionFunction}($1::uuid)`, [bucket.id]);
+    const row = result.rows[0];
+    if (!row?.id) {
+        throw new Error(`STORAGE_BUCKET_PROVISION_EMPTY: bucket ${bucket.id}`);
     }
-    return jobId;
+    return row;
 }
 // --- Plugin factory ---
 /**
@@ -216,7 +136,7 @@ async function enqueueReconciliationJob(pgClient, storageModule, bucket) {
  * This plugin provides one reconciliation pathway:
  *
  * 1. **Explicit `provisionBucket` mutation** — Call this mutation with a
- *    bucket key to enqueue reconciliation (or re-reconciliation) for the
+ *    bucket key to request reconciliation (or re-reconciliation) for the
  *    bucket. Protected by RLS on the buckets table.
  *
  */
@@ -235,22 +155,23 @@ function createBucketProvisionerPlugin() {
       }
 
       type ProvisionBucketPayload {
-        """The logical bucket row that was queued for reconciliation."""
+        """The logical bucket row whose reconciliation was requested."""
         bucketId: UUID!
         bucketKey: String!
         """The physical bucket name already recorded, or null when reconciliation has not completed."""
         physicalName: String
-        """The reconciler job enqueued to provision this bucket."""
-        jobId: UUID!
+        """When reconciliation was last requested for this bucket."""
+        provisionRequestedAt: Datetime!
       }
 
       extend type Mutation {
         """
         Reconcile an S3 bucket for a logical bucket in the database.
-        Reads the bucket config via RLS, then enqueues the same
-        storage:provision_bucket job used by the INSERT trigger. This is
-        idempotent for an already-reconciled bucket; enqueue failures become
-        GraphQL errors.
+        Records the request on the bucket row via RLS; the bucket's job
+        trigger then enqueues the same storage:provision_bucket job used on
+        INSERT, and repeated requests collapse into one pending job. This is
+        idempotent for an already-reconciled bucket; failures become GraphQL
+        errors.
         """
         provisionBucket(
           input: ProvisionBucketInput!
@@ -286,12 +207,12 @@ function createBucketProvisionerPlugin() {
                                 throw new Error('BUCKET_NOT_FOUND');
                             }
                             const { storageModule, bucket } = resolution;
-                            const jobId = await enqueueReconciliationJob(pgClient, storageModule, bucket);
+                            const provisioned = await requestReconciliation(pgClient, storageModule, bucket);
                             return {
-                                bucketId: bucket.id,
-                                bucketKey: bucket.key,
-                                physicalName: bucket.physical_name,
-                                jobId,
+                                bucketId: provisioned.id,
+                                bucketKey: provisioned.key,
+                                physicalName: provisioned.physical_name,
+                                provisionRequestedAt: provisioned.provision_requested_at,
                             };
                         });
                     });

package/types.d.ts

@@ -14,15 +14,15 @@ export interface ProvisionBucketInput {
     ownerId?: string;
 }
 /**
- * Result of the provisionBucket reconciliation enqueue mutation.
+ * Result of the provisionBucket mutation: the bucket row it stamped.
  */
 export interface ProvisionBucketPayload {
-    /** The logical bucket row queued for reconciliation */
+    /** The logical bucket row whose reconciliation was requested */
     bucketId: string;
     /** The logical bucket key */
     bucketKey: string;
     /** The physical name already recorded, or null while reconciliation is pending */
     physicalName: string | null;
-    /** The queued reconciler job */
-    jobId: string;
+    /** When reconciliation was last requested */
+    provisionRequestedAt: string;
 }