@agentic-kit/pi 0.10.6 → 0.11.0

package/README.md

@@ -38,6 +38,12 @@ const dbTools = createDbTools({
 pi.use(dbTools);
 ```
 
+## Provisioning
+
+`provision_database` requests a database through the `requestDatabase` mutation on the api endpoint. When the requested module set matches a cataloged preset, the backend claims a warm pre-baked database in seconds. Otherwise a background job provisions the database cold. The tool polls the provision ticket on the modules endpoint until the database and its owner bootstrap are complete. Then it writes the credentials to the project `.env` and returns.
+
+For local development, the cold path and the warm pool depend on the backend's jobs worker. Start the worker in `constructive-db` with `pnpm dev:fn`. If the worker is not running, cold tickets stay `pending` and the tool times out after 240 seconds.
+
 ## Host contract
 
 `PiToolsHost` is the only integration surface:

package/esm/provision-database/preset-match.d.ts

@@ -0,0 +1,13 @@
+import { type ProvisionModule } from './presets';
+import type { ProvisionRequest } from './request-database';
+/**
+ * The slug of the registry preset whose module set equals `resolved` under
+ * the backend's hash semantics, or undefined when no preset matches.
+ */
+export declare function matchPresetSlug(resolved: ProvisionModule[]): string | undefined;
+/**
+ * Build the requestDatabase input branch: presetSlug when the resolved set
+ * equals a registry preset (warm-pool eligible), else the explicit modules
+ * array — never both.
+ */
+export declare function selectProvisionRequest(resolved: ProvisionModule[]): ProvisionRequest;

package/esm/provision-database/preset-match.js

@@ -0,0 +1,66 @@
+// Client-side mirror of the backend's modules_hash normalization
+// (constructive-db: metaschema_private.modules_hash), used to decide whether a
+// resolved module set can be requested by preset slug — the warm-pool-eligible
+// path — or must be sent as an explicit modules array:
+//   1. A bare module name normalizes to [name, {}]; a missing/null options
+//      slot normalizes to {}.
+//   2. Options are compared verbatim after canonicalization (object keys
+//      sorted at every level) — no default-value normalization.
+//   3. Entries are sorted so the caller's ordering never affects the match.
+//   4. Duplicate normalized entries never match (the backend rejects them).
+// Only equality within this process matters, so string sort order does not
+// need to replicate PostgreSQL collation.
+//
+// The registry presets are the canonical definitions; the backend's
+// db_presets catalog is synced from them. A slug match assumes that sync —
+// preset drift would provision the backend's version of the set.
+import { allModulePresets } from './presets';
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = canonicalize(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function normalizedEntries(list) {
+    const entries = list.map((m) => {
+        const name = Array.isArray(m) ? m[0] : m;
+        const options = Array.isArray(m) ? (m[1] ?? {}) : {};
+        return JSON.stringify([name, canonicalize(options)]);
+    });
+    entries.sort();
+    for (let i = 1; i < entries.length; i++) {
+        if (entries[i] === entries[i - 1])
+            return null;
+    }
+    return entries;
+}
+/**
+ * The slug of the registry preset whose module set equals `resolved` under
+ * the backend's hash semantics, or undefined when no preset matches.
+ */
+export function matchPresetSlug(resolved) {
+    const target = normalizedEntries(resolved)?.join('\n');
+    if (!target)
+        return undefined;
+    for (const preset of allModulePresets) {
+        if (normalizedEntries(preset.modules)?.join('\n') === target) {
+            return preset.name;
+        }
+    }
+    return undefined;
+}
+/**
+ * Build the requestDatabase input branch: presetSlug when the resolved set
+ * equals a registry preset (warm-pool eligible), else the explicit modules
+ * array — never both.
+ */
+export function selectProvisionRequest(resolved) {
+    const presetSlug = matchPresetSlug(resolved);
+    return presetSlug ? { presetSlug } : { modules: resolved };
+}

package/esm/provision-database/request-database.d.ts

@@ -0,0 +1,61 @@
+import type { ProvisionModule } from './presets';
+/**
+ * Exactly one of presetSlug or modules — requestDatabase rejects both/neither
+ * (REQUEST_DATABASE_INVALID_INPUT). `selectProvisionRequest` (preset-match.ts)
+ * builds this from the resolved module set.
+ */
+export type ProvisionRequest = {
+    presetSlug: string;
+} | {
+    modules: ProvisionModule[];
+};
+export type ProvisionTicket = {
+    id?: string | null;
+    status?: string | null;
+    bootstrapStatus?: string | null;
+    databaseId?: string | null;
+    errorMessage?: string | null;
+    bootstrapError?: string | null;
+};
+/**
+ * Request + poll seam, injectable for tests (pattern: db-probe's
+ * ProbeExecutor). The default executor drives the SDK clients.
+ */
+export type ProvisionRequestExecutor = {
+    request(input: {
+        databaseName: string;
+        subdomain: string;
+        domain: string;
+        request: ProvisionRequest;
+    }): Promise<ProvisionTicket>;
+    poll(ticketId: string): Promise<ProvisionTicket | null>;
+};
+export declare const POLL_INTERVAL_MS = 2000;
+/** Stays under airpage's 5-minute per-tool timeout. */
+export declare const POLL_DEADLINE_MS = 240000;
+/**
+ * Consecutive unreadable polls tolerated before giving up. Provisioning keeps
+ * running server-side, so a dropped request or a momentary 502 must not abort
+ * a creation that is about to succeed.
+ */
+export declare const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+/**
+ * Request a database and resolve only when it is fully usable: ticket
+ * `status` AND `bootstrapStatus` both 'completed'. The ticket the mutation
+ * returns is checked before the first sleep, so a warm claim with bootstrap
+ * already done never waits. `status: 'failed'` surfaces `errorMessage`;
+ * `bootstrapStatus: 'failed'` surfaces `bootstrapError`.
+ */
+export declare function requestDatabaseProvision(args: {
+    apiEndpoint: string;
+    modulesEndpoint: string;
+    bearer: string;
+    databaseName: string;
+    domain: string;
+    request: ProvisionRequest;
+    executor?: ProvisionRequestExecutor;
+    pollIntervalMs?: number;
+    pollDeadlineMs?: number;
+}): Promise<{
+    databaseId: string;
+}>;

package/esm/provision-database/request-database.js

@@ -0,0 +1,130 @@
+// Provision a database through the api endpoint's requestDatabase mutation —
+// the pool-aware entry point. The mutation returns a ticket (a
+// database_provision_module row) immediately: a warm-pool claim arrives
+// 'completed' with the deferred owner bootstrap still pending; a cold request
+// arrives 'pending' and is fulfilled asynchronously by the backend's jobs
+// worker. The ticket is polled on the MODULES endpoint (the api endpoint has
+// no ticket query) until BOTH status and bootstrapStatus are 'completed': pi
+// hands credentials to the agent as soon as this resolves, and until owner
+// bootstrap completes the new database has zero users, so its per-DB API
+// would reject the owner token under RLS. requestDatabase owns the database
+// to the JWT user — there is no owner input. The generated ORM's default
+// adapter is plain fetch, so the SDK's FetchAdapter is injected to keep
+// *.localhost DNS/Host routing working in Node.
+import { api, modules } from '@constructive-io/sdk';
+export const POLL_INTERVAL_MS = 2_000;
+/** Stays under airpage's 5-minute per-tool timeout. */
+export const POLL_DEADLINE_MS = 240_000;
+/**
+ * Consecutive unreadable polls tolerated before giving up. Provisioning keeps
+ * running server-side, so a dropped request or a momentary 502 must not abort
+ * a creation that is about to succeed.
+ */
+export const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+const TICKET_SELECT = {
+    id: true,
+    status: true,
+    bootstrapStatus: true,
+    databaseId: true,
+    errorMessage: true,
+    bootstrapError: true,
+};
+function createSdkExecutor(args) {
+    const headers = { Authorization: `Bearer ${args.bearer}` };
+    const apiClient = api.createClient({ adapter: new api.FetchAdapter(args.apiEndpoint, headers) });
+    const modulesClient = modules.createClient({
+        adapter: new api.FetchAdapter(args.modulesEndpoint, headers),
+    });
+    return {
+        async request(input) {
+            const requestInput = {
+                databaseName: input.databaseName,
+                subdomain: input.subdomain,
+                domain: input.domain,
+                ...('presetSlug' in input.request
+                    ? { presetSlug: input.request.presetSlug }
+                    : { modules: input.request.modules }),
+            };
+            const result = await apiClient.mutation
+                .requestDatabase({ input: requestInput }, { select: { result: { select: TICKET_SELECT } } })
+                .unwrap();
+            const ticket = result.requestDatabase?.result;
+            if (!ticket)
+                throw new Error('requestDatabase returned no provision ticket.');
+            return ticket;
+        },
+        async poll(ticketId) {
+            const result = await modulesClient.databaseProvisionModule
+                .findOne({ id: ticketId, select: TICKET_SELECT })
+                .unwrap();
+            return result.databaseProvisionModule ?? null;
+        },
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Request a database and resolve only when it is fully usable: ticket
+ * `status` AND `bootstrapStatus` both 'completed'. The ticket the mutation
+ * returns is checked before the first sleep, so a warm claim with bootstrap
+ * already done never waits. `status: 'failed'` surfaces `errorMessage`;
+ * `bootstrapStatus: 'failed'` surfaces `bootstrapError`.
+ */
+export async function requestDatabaseProvision(args) {
+    const executor = args.executor ??
+        createSdkExecutor({
+            apiEndpoint: args.apiEndpoint,
+            modulesEndpoint: args.modulesEndpoint,
+            bearer: args.bearer,
+        });
+    const intervalMs = args.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const deadlineMs = args.pollDeadlineMs ?? POLL_DEADLINE_MS;
+    let ticket = await executor.request({
+        databaseName: args.databaseName,
+        subdomain: args.databaseName,
+        domain: args.domain,
+        request: args.request,
+    });
+    const ticketId = ticket.id;
+    if (!ticketId)
+        throw new Error('requestDatabase returned a provision ticket without an id.');
+    const deadline = Date.now() + deadlineMs;
+    let failures = 0;
+    for (;;) {
+        if (ticket.status === 'failed') {
+            throw new Error(ticket.errorMessage ?? 'provisioning failed');
+        }
+        if (ticket.bootstrapStatus === 'failed') {
+            throw new Error(ticket.bootstrapError ?? 'owner bootstrap failed');
+        }
+        if (ticket.status === 'completed' && ticket.bootstrapStatus === 'completed') {
+            if (!ticket.databaseId)
+                throw new Error('provisioning completed but returned no databaseId.');
+            return { databaseId: ticket.databaseId };
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`provisioning timed out after ${Math.round(deadlineMs / 1000)}s (status: ${ticket.status ?? 'unknown'}, bootstrapStatus: ${ticket.bootstrapStatus ?? 'unknown'})`);
+        }
+        await sleep(intervalMs);
+        // A poll that throws (network blip, 502) or comes back empty is retried a
+        // few times rather than failing a provision that is still running.
+        let polled;
+        try {
+            polled = await executor.poll(ticketId);
+        }
+        catch (err) {
+            if (++failures > MAX_CONSECUTIVE_POLL_FAILURES)
+                throw err;
+            continue;
+        }
+        if (!polled) {
+            if (++failures > MAX_CONSECUTIVE_POLL_FAILURES) {
+                throw new Error(`provision ticket ${ticketId} could not be read back.`);
+            }
+            continue;
+        }
+        failures = 0;
+        ticket = polled;
+    }
+}

package/esm/tools/provision-database.js

@@ -5,11 +5,12 @@ import { z } from 'zod';
 import { prewarmAppWorkspace } from '../app-workspace';
 import { probeDatabase } from '../db-probe';
 import { getHost } from '../host';
-import { createDatabaseProvision } from '../provision-database/create-database-provision';
 import { selectProvisionCredential } from '../provision-database/credential';
 import { archiveBindingKeys, ARCHIVED_BINDING_KEYS, mergeEnv, provisionEnvVars, } from '../provision-database/env-file';
 import { loadProvisionManifest } from '../provision-database/manifest';
 import { applySqlFixups } from '../provision-database/pg-fixups';
+import { selectProvisionRequest } from '../provision-database/preset-match';
+import { requestDatabaseProvision } from '../provision-database/request-database';
 import { resolveProvisionModules } from '../provision-database/resolve';
 import { toolSchema } from '../tool-schema';
 const DEFAULT_API_ENDPOINT = 'http://api.localhost:3000/graphql';
@@ -58,22 +59,6 @@ function parseEnvKeys(source) {
     }
     return env;
 }
-async function withRetry(fn, maxRetries = 5, delayMs = 2000) {
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (msg.includes('already exists') || msg.includes('exists'))
-                throw err;
-            if (attempt === maxRetries)
-                throw err;
-            await new Promise((r) => setTimeout(r, delayMs));
-        }
-    }
-    throw new Error('unreachable');
-}
 export const provisionDatabaseTool = {
     name: 'provision_database',
     label: 'Provision database',
@@ -100,9 +85,10 @@ export const provisionDatabaseTool = {
         const backend = host.backendConfig();
         const apiEndpoint = process.env.API_ENDPOINT || backend?.apiEndpoint || DEFAULT_API_ENDPOINT;
         const modulesEndpoint = process.env.MODULES_ENDPOINT || backend?.modulesEndpoint || DEFAULT_MODULES_ENDPOINT;
-        // Every new project provisions UNDER the account (owner_id = the account user),
-        // so the database is account-owned and enumerable. The account bearer is the
-        // single credential: it authenticates the provision mutation, the idempotency
+        // Every new project provisions UNDER the account (requestDatabase owns the
+        // database to the JWT user), so it is account-owned and enumerable. The
+        // account bearer is the single credential: it authenticates the provision
+        // mutation, the idempotency
         // probe below, and is the ACCESS_TOKEN written to .env for project-local
         // scripts. It expires with the login session — a relogin plus any provision
         // run (including the skip path) refreshes the .env copy. A signed-in session
@@ -180,7 +166,8 @@ export const provisionDatabaseTool = {
             existing = archiveBindingKeys(existing, ARCHIVED_BINDING_KEYS, new Date().toISOString().slice(0, 10));
         }
         // The packages/app scaffold + pnpm install are database-INDEPENDENT, so kick
-        // them off now to run concurrently with the ~90s provisioning mutation below.
+        // them off now to run concurrently with the provisioning request below
+        // (near-instant on a warm-pool hit, up to minutes on the cold path).
         // This keeps clone + install off run_codegen's critical path. Best-effort:
         // run_codegen re-runs the same idempotent steps, so a prewarm failure is
         // harmless. Never let it reject (we await it before returning).
@@ -207,21 +194,25 @@ export const provisionDatabaseTool = {
             return fail(`Cannot resolve provision modules: ${err instanceof Error ? err.message : String(err)}`);
         }
         const physicalDb = process.env.CONSTRUCTIVE_DB || 'constructive';
-        // Provision on the MODULES endpoint: createDatabaseProvisionModule creates
-        // the database owned by ownerId, provisions the module set, and bootstraps
-        // the owner into it before the row returns. The domain still derives from
-        // the api endpoint's host (per-DB endpoints live under it), and an explicit
-        // subdomain (= databaseName) keeps them deterministic (SUBDOMAIN-001).
+        // Provision on the API endpoint: requestDatabase claims a warm-pool
+        // database when the resolved module set matches a cataloged preset
+        // (near-instant) and cold-provisions asynchronously otherwise; the ticket
+        // is polled on the modules endpoint until the database AND its deferred
+        // owner bootstrap complete. No retry wrapper: a pending ticket is the
+        // normal first response, and transient poll failures are absorbed inside
+        // the poll loop. The domain still derives from the api endpoint's host
+        // (per-DB endpoints live under it), and an explicit subdomain
+        // (= databaseName) keeps them deterministic (SUBDOMAIN-001).
         let databaseId;
         try {
-            ({ databaseId } = await withRetry(() => createDatabaseProvision({
-                endpoint: modulesEndpoint,
+            ({ databaseId } = await requestDatabaseProvision({
+                apiEndpoint,
+                modulesEndpoint,
                 bearer: credential.bearer,
                 databaseName,
                 domain: provisionDomain(apiEndpoint),
-                ownerId,
-                modules,
-            })));
+                request: selectProvisionRequest(modules),
+            }));
         }
         catch (err) {
             const detail = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-kit/pi",
-  "version": "0.10.6",
+  "version": "0.11.0",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "description": "Pi adapter for agentic-kit — the Constructive typed db tools (provision, blueprint, codegen, records, policies, templates) and confirm gate as a pi coding-agent extension",
   "main": "index.js",
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@agentic-kit/harness": "^0.10.1",
-    "@constructive-io/graphql-query": "^4.12.9",
-    "@constructive-io/sdk": "^1.11.9",
-    "node-type-registry": "^1.14.3",
+    "@constructive-io/graphql-query": "^4.12.10",
+    "@constructive-io/sdk": "^1.11.10",
+    "node-type-registry": "^1.15.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -48,5 +48,5 @@
     "coding-agent",
     "constructive"
   ],
-  "gitHead": "44f56ee80a348f649a22e5bd32b35f2822726509"
+  "gitHead": "d0d796b7eb0d16c8c19405a49c0ca62ce3df117b"
 }

package/provision-database/preset-match.d.ts

@@ -0,0 +1,13 @@
+import { type ProvisionModule } from './presets';
+import type { ProvisionRequest } from './request-database';
+/**
+ * The slug of the registry preset whose module set equals `resolved` under
+ * the backend's hash semantics, or undefined when no preset matches.
+ */
+export declare function matchPresetSlug(resolved: ProvisionModule[]): string | undefined;
+/**
+ * Build the requestDatabase input branch: presetSlug when the resolved set
+ * equals a registry preset (warm-pool eligible), else the explicit modules
+ * array — never both.
+ */
+export declare function selectProvisionRequest(resolved: ProvisionModule[]): ProvisionRequest;

package/provision-database/preset-match.js

@@ -0,0 +1,70 @@
+"use strict";
+// Client-side mirror of the backend's modules_hash normalization
+// (constructive-db: metaschema_private.modules_hash), used to decide whether a
+// resolved module set can be requested by preset slug — the warm-pool-eligible
+// path — or must be sent as an explicit modules array:
+//   1. A bare module name normalizes to [name, {}]; a missing/null options
+//      slot normalizes to {}.
+//   2. Options are compared verbatim after canonicalization (object keys
+//      sorted at every level) — no default-value normalization.
+//   3. Entries are sorted so the caller's ordering never affects the match.
+//   4. Duplicate normalized entries never match (the backend rejects them).
+// Only equality within this process matters, so string sort order does not
+// need to replicate PostgreSQL collation.
+//
+// The registry presets are the canonical definitions; the backend's
+// db_presets catalog is synced from them. A slug match assumes that sync —
+// preset drift would provision the backend's version of the set.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchPresetSlug = matchPresetSlug;
+exports.selectProvisionRequest = selectProvisionRequest;
+const presets_1 = require("./presets");
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = canonicalize(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function normalizedEntries(list) {
+    const entries = list.map((m) => {
+        const name = Array.isArray(m) ? m[0] : m;
+        const options = Array.isArray(m) ? (m[1] ?? {}) : {};
+        return JSON.stringify([name, canonicalize(options)]);
+    });
+    entries.sort();
+    for (let i = 1; i < entries.length; i++) {
+        if (entries[i] === entries[i - 1])
+            return null;
+    }
+    return entries;
+}
+/**
+ * The slug of the registry preset whose module set equals `resolved` under
+ * the backend's hash semantics, or undefined when no preset matches.
+ */
+function matchPresetSlug(resolved) {
+    const target = normalizedEntries(resolved)?.join('\n');
+    if (!target)
+        return undefined;
+    for (const preset of presets_1.allModulePresets) {
+        if (normalizedEntries(preset.modules)?.join('\n') === target) {
+            return preset.name;
+        }
+    }
+    return undefined;
+}
+/**
+ * Build the requestDatabase input branch: presetSlug when the resolved set
+ * equals a registry preset (warm-pool eligible), else the explicit modules
+ * array — never both.
+ */
+function selectProvisionRequest(resolved) {
+    const presetSlug = matchPresetSlug(resolved);
+    return presetSlug ? { presetSlug } : { modules: resolved };
+}

package/provision-database/request-database.d.ts

@@ -0,0 +1,61 @@
+import type { ProvisionModule } from './presets';
+/**
+ * Exactly one of presetSlug or modules — requestDatabase rejects both/neither
+ * (REQUEST_DATABASE_INVALID_INPUT). `selectProvisionRequest` (preset-match.ts)
+ * builds this from the resolved module set.
+ */
+export type ProvisionRequest = {
+    presetSlug: string;
+} | {
+    modules: ProvisionModule[];
+};
+export type ProvisionTicket = {
+    id?: string | null;
+    status?: string | null;
+    bootstrapStatus?: string | null;
+    databaseId?: string | null;
+    errorMessage?: string | null;
+    bootstrapError?: string | null;
+};
+/**
+ * Request + poll seam, injectable for tests (pattern: db-probe's
+ * ProbeExecutor). The default executor drives the SDK clients.
+ */
+export type ProvisionRequestExecutor = {
+    request(input: {
+        databaseName: string;
+        subdomain: string;
+        domain: string;
+        request: ProvisionRequest;
+    }): Promise<ProvisionTicket>;
+    poll(ticketId: string): Promise<ProvisionTicket | null>;
+};
+export declare const POLL_INTERVAL_MS = 2000;
+/** Stays under airpage's 5-minute per-tool timeout. */
+export declare const POLL_DEADLINE_MS = 240000;
+/**
+ * Consecutive unreadable polls tolerated before giving up. Provisioning keeps
+ * running server-side, so a dropped request or a momentary 502 must not abort
+ * a creation that is about to succeed.
+ */
+export declare const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+/**
+ * Request a database and resolve only when it is fully usable: ticket
+ * `status` AND `bootstrapStatus` both 'completed'. The ticket the mutation
+ * returns is checked before the first sleep, so a warm claim with bootstrap
+ * already done never waits. `status: 'failed'` surfaces `errorMessage`;
+ * `bootstrapStatus: 'failed'` surfaces `bootstrapError`.
+ */
+export declare function requestDatabaseProvision(args: {
+    apiEndpoint: string;
+    modulesEndpoint: string;
+    bearer: string;
+    databaseName: string;
+    domain: string;
+    request: ProvisionRequest;
+    executor?: ProvisionRequestExecutor;
+    pollIntervalMs?: number;
+    pollDeadlineMs?: number;
+}): Promise<{
+    databaseId: string;
+}>;

package/provision-database/request-database.js

@@ -0,0 +1,134 @@
+"use strict";
+// Provision a database through the api endpoint's requestDatabase mutation —
+// the pool-aware entry point. The mutation returns a ticket (a
+// database_provision_module row) immediately: a warm-pool claim arrives
+// 'completed' with the deferred owner bootstrap still pending; a cold request
+// arrives 'pending' and is fulfilled asynchronously by the backend's jobs
+// worker. The ticket is polled on the MODULES endpoint (the api endpoint has
+// no ticket query) until BOTH status and bootstrapStatus are 'completed': pi
+// hands credentials to the agent as soon as this resolves, and until owner
+// bootstrap completes the new database has zero users, so its per-DB API
+// would reject the owner token under RLS. requestDatabase owns the database
+// to the JWT user — there is no owner input. The generated ORM's default
+// adapter is plain fetch, so the SDK's FetchAdapter is injected to keep
+// *.localhost DNS/Host routing working in Node.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CONSECUTIVE_POLL_FAILURES = exports.POLL_DEADLINE_MS = exports.POLL_INTERVAL_MS = void 0;
+exports.requestDatabaseProvision = requestDatabaseProvision;
+const sdk_1 = require("@constructive-io/sdk");
+exports.POLL_INTERVAL_MS = 2_000;
+/** Stays under airpage's 5-minute per-tool timeout. */
+exports.POLL_DEADLINE_MS = 240_000;
+/**
+ * Consecutive unreadable polls tolerated before giving up. Provisioning keeps
+ * running server-side, so a dropped request or a momentary 502 must not abort
+ * a creation that is about to succeed.
+ */
+exports.MAX_CONSECUTIVE_POLL_FAILURES = 3;
+const TICKET_SELECT = {
+    id: true,
+    status: true,
+    bootstrapStatus: true,
+    databaseId: true,
+    errorMessage: true,
+    bootstrapError: true,
+};
+function createSdkExecutor(args) {
+    const headers = { Authorization: `Bearer ${args.bearer}` };
+    const apiClient = sdk_1.api.createClient({ adapter: new sdk_1.api.FetchAdapter(args.apiEndpoint, headers) });
+    const modulesClient = sdk_1.modules.createClient({
+        adapter: new sdk_1.api.FetchAdapter(args.modulesEndpoint, headers),
+    });
+    return {
+        async request(input) {
+            const requestInput = {
+                databaseName: input.databaseName,
+                subdomain: input.subdomain,
+                domain: input.domain,
+                ...('presetSlug' in input.request
+                    ? { presetSlug: input.request.presetSlug }
+                    : { modules: input.request.modules }),
+            };
+            const result = await apiClient.mutation
+                .requestDatabase({ input: requestInput }, { select: { result: { select: TICKET_SELECT } } })
+                .unwrap();
+            const ticket = result.requestDatabase?.result;
+            if (!ticket)
+                throw new Error('requestDatabase returned no provision ticket.');
+            return ticket;
+        },
+        async poll(ticketId) {
+            const result = await modulesClient.databaseProvisionModule
+                .findOne({ id: ticketId, select: TICKET_SELECT })
+                .unwrap();
+            return result.databaseProvisionModule ?? null;
+        },
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Request a database and resolve only when it is fully usable: ticket
+ * `status` AND `bootstrapStatus` both 'completed'. The ticket the mutation
+ * returns is checked before the first sleep, so a warm claim with bootstrap
+ * already done never waits. `status: 'failed'` surfaces `errorMessage`;
+ * `bootstrapStatus: 'failed'` surfaces `bootstrapError`.
+ */
+async function requestDatabaseProvision(args) {
+    const executor = args.executor ??
+        createSdkExecutor({
+            apiEndpoint: args.apiEndpoint,
+            modulesEndpoint: args.modulesEndpoint,
+            bearer: args.bearer,
+        });
+    const intervalMs = args.pollIntervalMs ?? exports.POLL_INTERVAL_MS;
+    const deadlineMs = args.pollDeadlineMs ?? exports.POLL_DEADLINE_MS;
+    let ticket = await executor.request({
+        databaseName: args.databaseName,
+        subdomain: args.databaseName,
+        domain: args.domain,
+        request: args.request,
+    });
+    const ticketId = ticket.id;
+    if (!ticketId)
+        throw new Error('requestDatabase returned a provision ticket without an id.');
+    const deadline = Date.now() + deadlineMs;
+    let failures = 0;
+    for (;;) {
+        if (ticket.status === 'failed') {
+            throw new Error(ticket.errorMessage ?? 'provisioning failed');
+        }
+        if (ticket.bootstrapStatus === 'failed') {
+            throw new Error(ticket.bootstrapError ?? 'owner bootstrap failed');
+        }
+        if (ticket.status === 'completed' && ticket.bootstrapStatus === 'completed') {
+            if (!ticket.databaseId)
+                throw new Error('provisioning completed but returned no databaseId.');
+            return { databaseId: ticket.databaseId };
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`provisioning timed out after ${Math.round(deadlineMs / 1000)}s (status: ${ticket.status ?? 'unknown'}, bootstrapStatus: ${ticket.bootstrapStatus ?? 'unknown'})`);
+        }
+        await sleep(intervalMs);
+        // A poll that throws (network blip, 502) or comes back empty is retried a
+        // few times rather than failing a provision that is still running.
+        let polled;
+        try {
+            polled = await executor.poll(ticketId);
+        }
+        catch (err) {
+            if (++failures > exports.MAX_CONSECUTIVE_POLL_FAILURES)
+                throw err;
+            continue;
+        }
+        if (!polled) {
+            if (++failures > exports.MAX_CONSECUTIVE_POLL_FAILURES) {
+                throw new Error(`provision ticket ${ticketId} could not be read back.`);
+            }
+            continue;
+        }
+        failures = 0;
+        ticket = polled;
+    }
+}

package/tools/provision-database.js

@@ -11,11 +11,12 @@ const zod_1 = require("zod");
 const app_workspace_1 = require("../app-workspace");
 const db_probe_1 = require("../db-probe");
 const host_1 = require("../host");
-const create_database_provision_1 = require("../provision-database/create-database-provision");
 const credential_1 = require("../provision-database/credential");
 const env_file_1 = require("../provision-database/env-file");
 const manifest_1 = require("../provision-database/manifest");
 const pg_fixups_1 = require("../provision-database/pg-fixups");
+const preset_match_1 = require("../provision-database/preset-match");
+const request_database_1 = require("../provision-database/request-database");
 const resolve_1 = require("../provision-database/resolve");
 const tool_schema_1 = require("../tool-schema");
 const DEFAULT_API_ENDPOINT = 'http://api.localhost:3000/graphql';
@@ -64,22 +65,6 @@ function parseEnvKeys(source) {
     }
     return env;
 }
-async function withRetry(fn, maxRetries = 5, delayMs = 2000) {
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (msg.includes('already exists') || msg.includes('exists'))
-                throw err;
-            if (attempt === maxRetries)
-                throw err;
-            await new Promise((r) => setTimeout(r, delayMs));
-        }
-    }
-    throw new Error('unreachable');
-}
 exports.provisionDatabaseTool = {
     name: 'provision_database',
     label: 'Provision database',
@@ -106,9 +91,10 @@ exports.provisionDatabaseTool = {
         const backend = host.backendConfig();
         const apiEndpoint = process.env.API_ENDPOINT || backend?.apiEndpoint || DEFAULT_API_ENDPOINT;
         const modulesEndpoint = process.env.MODULES_ENDPOINT || backend?.modulesEndpoint || DEFAULT_MODULES_ENDPOINT;
-        // Every new project provisions UNDER the account (owner_id = the account user),
-        // so the database is account-owned and enumerable. The account bearer is the
-        // single credential: it authenticates the provision mutation, the idempotency
+        // Every new project provisions UNDER the account (requestDatabase owns the
+        // database to the JWT user), so it is account-owned and enumerable. The
+        // account bearer is the single credential: it authenticates the provision
+        // mutation, the idempotency
         // probe below, and is the ACCESS_TOKEN written to .env for project-local
         // scripts. It expires with the login session — a relogin plus any provision
         // run (including the skip path) refreshes the .env copy. A signed-in session
@@ -186,7 +172,8 @@ exports.provisionDatabaseTool = {
             existing = (0, env_file_1.archiveBindingKeys)(existing, env_file_1.ARCHIVED_BINDING_KEYS, new Date().toISOString().slice(0, 10));
         }
         // The packages/app scaffold + pnpm install are database-INDEPENDENT, so kick
-        // them off now to run concurrently with the ~90s provisioning mutation below.
+        // them off now to run concurrently with the provisioning request below
+        // (near-instant on a warm-pool hit, up to minutes on the cold path).
         // This keeps clone + install off run_codegen's critical path. Best-effort:
         // run_codegen re-runs the same idempotent steps, so a prewarm failure is
         // harmless. Never let it reject (we await it before returning).
@@ -213,21 +200,25 @@ exports.provisionDatabaseTool = {
             return fail(`Cannot resolve provision modules: ${err instanceof Error ? err.message : String(err)}`);
         }
         const physicalDb = process.env.CONSTRUCTIVE_DB || 'constructive';
-        // Provision on the MODULES endpoint: createDatabaseProvisionModule creates
-        // the database owned by ownerId, provisions the module set, and bootstraps
-        // the owner into it before the row returns. The domain still derives from
-        // the api endpoint's host (per-DB endpoints live under it), and an explicit
-        // subdomain (= databaseName) keeps them deterministic (SUBDOMAIN-001).
+        // Provision on the API endpoint: requestDatabase claims a warm-pool
+        // database when the resolved module set matches a cataloged preset
+        // (near-instant) and cold-provisions asynchronously otherwise; the ticket
+        // is polled on the modules endpoint until the database AND its deferred
+        // owner bootstrap complete. No retry wrapper: a pending ticket is the
+        // normal first response, and transient poll failures are absorbed inside
+        // the poll loop. The domain still derives from the api endpoint's host
+        // (per-DB endpoints live under it), and an explicit subdomain
+        // (= databaseName) keeps them deterministic (SUBDOMAIN-001).
         let databaseId;
         try {
-            ({ databaseId } = await withRetry(() => (0, create_database_provision_1.createDatabaseProvision)({
-                endpoint: modulesEndpoint,
+            ({ databaseId } = await (0, request_database_1.requestDatabaseProvision)({
+                apiEndpoint,
+                modulesEndpoint,
                 bearer: credential.bearer,
                 databaseName,
                 domain: provisionDomain(apiEndpoint),
-                ownerId,
-                modules,
-            })));
+                request: (0, preset_match_1.selectProvisionRequest)(modules),
+            }));
         }
         catch (err) {
             const detail = err instanceof Error ? err.message : String(err);

package/esm/provision-database/create-database-provision.d.ts

@@ -1,11 +0,0 @@
-import type { ProvisionModule } from './presets';
-export declare function createDatabaseProvision(args: {
-    endpoint: string;
-    bearer: string;
-    databaseName: string;
-    domain: string;
-    ownerId: string;
-    modules: ProvisionModule[];
-}): Promise<{
-    databaseId: string;
-}>;

package/esm/provision-database/create-database-provision.js

@@ -1,48 +0,0 @@
-// Provision a database through the modules endpoint's createDatabaseProvisionModule
-// mutation — an insert into database_provision_modules whose BEFORE INSERT trigger
-// creates the database, domain, API, and module set before the row returns (the
-// same contract constructive-client's admin app uses). The retired requestDatabase
-// mutation only ever existed on dev builds of the api endpoint; production
-// deployments (modules.launchql.dev) expose this one. bootstrapUser: true copies
-// the owner into the new database so its per-DB API recognizes the account user.
-// The generated ORM's default adapter is plain fetch, so the SDK's FetchAdapter is
-// injected to keep *.localhost DNS/Host routing working in Node.
-import { api, modules } from '@constructive-io/sdk';
-export async function createDatabaseProvision(args) {
-    const db = modules.createClient({
-        adapter: new api.FetchAdapter(args.endpoint, {
-            Authorization: `Bearer ${args.bearer}`,
-        }),
-    });
-    const result = await db.databaseProvisionModule
-        .create({
-        data: {
-            databaseName: args.databaseName,
-            subdomain: args.databaseName,
-            domain: args.domain,
-            ownerId: args.ownerId,
-            modules: args.modules,
-            bootstrapUser: true,
-        },
-        select: {
-            id: true,
-            databaseId: true,
-            status: true,
-            errorMessage: true,
-            completedAt: true,
-        },
-    })
-        .unwrap();
-    const record = result.createDatabaseProvisionModule?.databaseProvisionModule;
-    if (!record)
-        throw new Error('createDatabaseProvisionModule returned no provision record.');
-    if (record.status === 'failed') {
-        throw new Error(record.errorMessage ?? 'provisioning failed');
-    }
-    if (record.status !== 'completed') {
-        throw new Error(record.errorMessage ?? `provisioning did not complete (status: ${record.status ?? 'unknown'})`);
-    }
-    if (!record.databaseId)
-        throw new Error('provisioning completed but returned no databaseId.');
-    return { databaseId: record.databaseId };
-}

package/provision-database/create-database-provision.d.ts

@@ -1,11 +0,0 @@
-import type { ProvisionModule } from './presets';
-export declare function createDatabaseProvision(args: {
-    endpoint: string;
-    bearer: string;
-    databaseName: string;
-    domain: string;
-    ownerId: string;
-    modules: ProvisionModule[];
-}): Promise<{
-    databaseId: string;
-}>;

package/provision-database/create-database-provision.js

@@ -1,51 +0,0 @@
-"use strict";
-// Provision a database through the modules endpoint's createDatabaseProvisionModule
-// mutation — an insert into database_provision_modules whose BEFORE INSERT trigger
-// creates the database, domain, API, and module set before the row returns (the
-// same contract constructive-client's admin app uses). The retired requestDatabase
-// mutation only ever existed on dev builds of the api endpoint; production
-// deployments (modules.launchql.dev) expose this one. bootstrapUser: true copies
-// the owner into the new database so its per-DB API recognizes the account user.
-// The generated ORM's default adapter is plain fetch, so the SDK's FetchAdapter is
-// injected to keep *.localhost DNS/Host routing working in Node.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDatabaseProvision = createDatabaseProvision;
-const sdk_1 = require("@constructive-io/sdk");
-async function createDatabaseProvision(args) {
-    const db = sdk_1.modules.createClient({
-        adapter: new sdk_1.api.FetchAdapter(args.endpoint, {
-            Authorization: `Bearer ${args.bearer}`,
-        }),
-    });
-    const result = await db.databaseProvisionModule
-        .create({
-        data: {
-            databaseName: args.databaseName,
-            subdomain: args.databaseName,
-            domain: args.domain,
-            ownerId: args.ownerId,
-            modules: args.modules,
-            bootstrapUser: true,
-        },
-        select: {
-            id: true,
-            databaseId: true,
-            status: true,
-            errorMessage: true,
-            completedAt: true,
-        },
-    })
-        .unwrap();
-    const record = result.createDatabaseProvisionModule?.databaseProvisionModule;
-    if (!record)
-        throw new Error('createDatabaseProvisionModule returned no provision record.');
-    if (record.status === 'failed') {
-        throw new Error(record.errorMessage ?? 'provisioning failed');
-    }
-    if (record.status !== 'completed') {
-        throw new Error(record.errorMessage ?? `provisioning did not complete (status: ${record.status ?? 'unknown'})`);
-    }
-    if (!record.databaseId)
-        throw new Error('provisioning completed but returned no databaseId.');
-    return { databaseId: record.databaseId };
-}