@agentic-kit/db-tools 0.2.0

package/esm/policy/provision-helpers.d.ts

@@ -0,0 +1,38 @@
+export type CrudOperation = 'create' | 'read' | 'update' | 'delete';
+export interface OperationPolicyConfig {
+    roleName: string;
+    isPermissive: boolean;
+    policyData: Record<string, unknown>;
+    isCustomized: boolean;
+}
+export interface CrudPolicyConfigs {
+    create: OperationPolicyConfig;
+    read: OperationPolicyConfig;
+    update: OperationPolicyConfig;
+    delete: OperationPolicyConfig;
+}
+export declare const CRUD_OPERATIONS: CrudOperation[];
+export type GrantPrivilege = [string, string | string[]];
+export interface GrantEntry {
+    roles: string[];
+    privileges: GrantPrivilege[];
+}
+export interface PolicyEntry {
+    $type: string;
+    data?: Record<string, unknown>;
+    privileges?: string[];
+    policy_role?: string;
+    permissive?: boolean;
+    policy_name?: string;
+}
+export declare const ALL_CRUD_PRIVILEGES: GrantPrivilege[];
+export declare function crudOpToPrivilege(op: CrudOperation): string;
+export declare function crudOpsToPrivileges(ops: readonly CrudOperation[]): string[];
+export declare function buildGrants(roles?: string[], privileges?: GrantPrivilege[]): GrantEntry[];
+export declare function buildPolicyEntry(type: string, opts?: Partial<Omit<PolicyEntry, '$type'>>): PolicyEntry;
+export interface OperationGroup {
+    roleName: string;
+    isPermissive: boolean;
+    privileges: string[];
+}
+export declare function groupOperationsByConfig(enabledOperations: readonly CrudOperation[], operations: CrudPolicyConfigs): OperationGroup[];

package/esm/policy/provision-helpers.js

@@ -0,0 +1,50 @@
+export const CRUD_OPERATIONS = ['create', 'read', 'update', 'delete'];
+export const ALL_CRUD_PRIVILEGES = [
+    ['select', '*'],
+    ['insert', '*'],
+    ['update', '*'],
+    ['delete', '*'],
+];
+const CRUD_OP_TO_LOWER_PRIVILEGE = {
+    create: 'insert',
+    read: 'select',
+    update: 'update',
+    delete: 'delete',
+};
+export function crudOpToPrivilege(op) {
+    return CRUD_OP_TO_LOWER_PRIVILEGE[op];
+}
+export function crudOpsToPrivileges(ops) {
+    return ops.map(crudOpToPrivilege);
+}
+export function buildGrants(roles = ['authenticated'], privileges = ALL_CRUD_PRIVILEGES) {
+    return [{ roles, privileges }];
+}
+export function buildPolicyEntry(type, opts = {}) {
+    const entry = { $type: type };
+    if (opts.data && Object.keys(opts.data).length > 0)
+        entry.data = opts.data;
+    if (opts.privileges && opts.privileges.length > 0)
+        entry.privileges = opts.privileges;
+    if (opts.policy_role)
+        entry.policy_role = opts.policy_role;
+    if (opts.permissive !== undefined)
+        entry.permissive = opts.permissive;
+    if (opts.policy_name)
+        entry.policy_name = opts.policy_name;
+    return entry;
+}
+export function groupOperationsByConfig(enabledOperations, operations) {
+    const groupMap = new Map();
+    for (const op of enabledOperations) {
+        const config = operations[op];
+        const key = `${config.roleName}:${config.isPermissive}`;
+        let group = groupMap.get(key);
+        if (!group) {
+            group = { roleName: config.roleName, isPermissive: config.isPermissive, privileges: [] };
+            groupMap.set(key, group);
+        }
+        group.privileges.push(...crudOpsToPrivileges([op]));
+    }
+    return [...groupMap.values()];
+}

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

@@ -0,0 +1,14 @@
+export type AccountCredential = {
+    userId: string;
+    accessToken: string;
+    apiKey?: string;
+};
+export type ProvisionCredential = {
+    mode: 'account';
+    ownerId: string;
+    bearer: string;
+} | {
+    mode: 'error';
+    reason: string;
+};
+export declare function selectProvisionCredential(account: AccountCredential | null | undefined, signInHint?: string): ProvisionCredential;

package/esm/provision-database/credential.js

@@ -0,0 +1,19 @@
+// Pure: decide which credential authenticates a project's provisioning. Under the
+// account gate a signed-in session is guaranteed, so every new project provisions
+// UNDER the account (account-owned + enumerable): the database's owner_id is the
+// account's own userId, and the account's API key (falling back to its session
+// token) is the bearer that authenticates the provision mutation and lands in the
+// project .env as ACCESS_TOKEN (refreshed on every provision run, including the
+// skip path). A signed-in session with no usable bearer (keychain locked) is an
+// explicit error, never a silent throwaway owner.
+// Side-effect-free so the branch is unit-testable without runtime/network.
+export function selectProvisionCredential(account, signInHint) {
+    const bearer = account?.apiKey ?? account?.accessToken;
+    if (account?.userId && bearer) {
+        return { mode: 'account', ownerId: account.userId, bearer };
+    }
+    return {
+        mode: 'error',
+        reason: `No usable account credential. ${signInHint ?? 'Sign in (or unlock your session) before provisioning a database.'}`,
+    };
+}

package/esm/provision-database/env-file.d.ts

@@ -0,0 +1,37 @@
+export type EnvVars = Record<string, string>;
+/**
+ * Upsert `vars` into the existing `.env` `content`. Existing keys are replaced
+ * in place (preserving surrounding lines/comments); new keys are appended.
+ * Returns the new file body, trailing-newline-terminated.
+ */
+export declare function mergeEnv(content: string, vars: EnvVars): string;
+/** The credential keys provision_database owns in a project's .env. */
+export declare const PROVISION_ENV_KEYS: readonly ["DATABASE_ID", "DATABASE_NAME", "OWNER_ID", "ACCESS_TOKEN", "PGDATABASE", "API_ENDPOINT", "MODULES_ENDPOINT"];
+/**
+ * Keys archived as comments on reprovision — the binding identity: which
+ * database, under whom, on which backend. ACCESS_TOKEN is the account login
+ * token, identical across bindings, so it is overwritten in place rather than
+ * archived.
+ */
+export declare const ARCHIVED_BINDING_KEYS: readonly ["DATABASE_ID", "DATABASE_NAME", "OWNER_ID", "PGDATABASE", "API_ENDPOINT", "MODULES_ENDPOINT"];
+/**
+ * Build the provisioning credential block written to a project's .env. The
+ * endpoint pins record which backend owns this binding — outside-app consumers
+ * (verify-feature.sh, skill scripts, dev-server shells) resolve them instead of
+ * falling back to localhost defaults when the app targets a hosted backend.
+ */
+export declare function provisionEnvVars(args: {
+    databaseId: string;
+    databaseName: string;
+    ownerId: string;
+    accessToken: string;
+    apiEndpoint: string;
+    modulesEndpoint: string;
+}): EnvVars;
+/**
+ * Comment out the given keys in place (`# archived <date>: KEY=value`) so a
+ * reprovision keeps the previous binding readable in the file instead of
+ * silently overwriting it. Every other line — including existing comments and
+ * already-archived entries — passes through untouched.
+ */
+export declare function archiveBindingKeys(content: string, keys: readonly string[], archivedOn: string): string;

package/esm/provision-database/env-file.js

@@ -0,0 +1,85 @@
+// Pure .env merge — used by provision_database to persist provisioning
+// credentials without clobbering existing keys: replace a key in place if
+// present, else append.
+// Kept side-effect-free so it is unit-testable (the tool does the fs write).
+/**
+ * Upsert `vars` into the existing `.env` `content`. Existing keys are replaced
+ * in place (preserving surrounding lines/comments); new keys are appended.
+ * Returns the new file body, trailing-newline-terminated.
+ */
+export function mergeEnv(content, vars) {
+    let out = content;
+    for (const [key, val] of Object.entries(vars)) {
+        // Escape the key for the regex, and use a replacement function so `$`
+        // sequences in the value are never treated as replacement specials.
+        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const regex = new RegExp(`^${escapedKey}=.*`, 'm');
+        if (regex.test(out))
+            out = out.replace(regex, () => `${key}=${val}`);
+        else
+            out += `\n${key}=${val}`;
+    }
+    return out.trim() + '\n';
+}
+/** The credential keys provision_database owns in a project's .env. */
+export const PROVISION_ENV_KEYS = [
+    'DATABASE_ID',
+    'DATABASE_NAME',
+    'OWNER_ID',
+    'ACCESS_TOKEN',
+    'PGDATABASE',
+    'API_ENDPOINT',
+    'MODULES_ENDPOINT',
+];
+/**
+ * Keys archived as comments on reprovision — the binding identity: which
+ * database, under whom, on which backend. ACCESS_TOKEN is the account login
+ * token, identical across bindings, so it is overwritten in place rather than
+ * archived.
+ */
+export const ARCHIVED_BINDING_KEYS = [
+    'DATABASE_ID',
+    'DATABASE_NAME',
+    'OWNER_ID',
+    'PGDATABASE',
+    'API_ENDPOINT',
+    'MODULES_ENDPOINT',
+];
+/**
+ * Build the provisioning credential block written to a project's .env. The
+ * endpoint pins record which backend owns this binding — outside-app consumers
+ * (verify-feature.sh, skill scripts, dev-server shells) resolve them instead of
+ * falling back to localhost defaults when the app targets a hosted backend.
+ */
+export function provisionEnvVars(args) {
+    return {
+        DATABASE_ID: args.databaseId,
+        DATABASE_NAME: args.databaseName,
+        OWNER_ID: args.ownerId,
+        ACCESS_TOKEN: args.accessToken,
+        PGDATABASE: args.databaseName,
+        API_ENDPOINT: args.apiEndpoint,
+        MODULES_ENDPOINT: args.modulesEndpoint,
+    };
+}
+/**
+ * Comment out the given keys in place (`# archived <date>: KEY=value`) so a
+ * reprovision keeps the previous binding readable in the file instead of
+ * silently overwriting it. Every other line — including existing comments and
+ * already-archived entries — passes through untouched.
+ */
+export function archiveBindingKeys(content, keys, archivedOn) {
+    const keySet = new Set(keys);
+    return content
+        .split('\n')
+        .map((line) => {
+        if (line.trimStart().startsWith('#'))
+            return line;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            return line;
+        const key = line.slice(0, eq).trim();
+        return keySet.has(key) ? `# archived ${archivedOn}: ${line.trim()}` : line;
+    })
+        .join('\n');
+}

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

@@ -0,0 +1,10 @@
+import type { ProvisionOverlay } from './resolve';
+export declare const PROVISION_MANIFEST_FILE = "provision.json";
+export type ProvisionManifest = ProvisionOverlay;
+/** Validate an untrusted value as a provision manifest, throwing on bad shape. */
+export declare function parseProvisionManifest(value: unknown): ProvisionManifest;
+/**
+ * Load `<dir>/provision.json` as an overlay, or `null` when absent. A malformed
+ * file throws so a broken overlay is surfaced rather than silently ignored.
+ */
+export declare function loadProvisionManifest(dir: string): Promise<ProvisionManifest | null>;

package/esm/provision-database/manifest.js

@@ -0,0 +1,48 @@
+// `provision.json` overlay manifest.
+//
+// A pure-data overlay, distributed the same way skills are: written into a
+// config/app directory (locally, or materialized there from appstash / a pinned
+// git ref) and read at provision time. It NEVER installs or executes a package
+// — the base preset is a pinned build-time dependency; this file only selects a
+// preset and layers add/remove on top.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+export const PROVISION_MANIFEST_FILE = 'provision.json';
+const ModuleSchema = z.union([
+    z.string(),
+    z.tuple([z.string(), z.record(z.string(), z.unknown())]),
+]);
+const ProvisionManifestSchema = z
+    .object({
+    preset: z.string().optional(),
+    add: z.array(ModuleSchema).optional(),
+    remove: z.array(z.string()).optional(),
+})
+    .strict();
+/** Validate an untrusted value as a provision manifest, throwing on bad shape. */
+export function parseProvisionManifest(value) {
+    return ProvisionManifestSchema.parse(value);
+}
+/**
+ * Load `<dir>/provision.json` as an overlay, or `null` when absent. A malformed
+ * file throws so a broken overlay is surfaced rather than silently ignored.
+ */
+export async function loadProvisionManifest(dir) {
+    const file = path.join(dir, PROVISION_MANIFEST_FILE);
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Invalid ${PROVISION_MANIFEST_FILE} at ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return parseProvisionManifest(parsed);
+}

package/esm/provision-database/pg-fixups.d.ts

@@ -0,0 +1,16 @@
+export type FixupResult = {
+    applied: boolean;
+    note: string;
+};
+export type PgEnv = {
+    host?: string;
+    port?: string;
+    user?: string;
+    password?: string;
+};
+export declare function parsePgpmEnv(stdout: string): PgEnv;
+export declare function resolvePgEnv(): Promise<PgEnv | null>;
+export declare function applySqlFixups(args: {
+    databaseName: string;
+    physicalDb: string;
+}): Promise<FixupResult>;

package/esm/provision-database/pg-fixups.js

@@ -0,0 +1,132 @@
+// Post-provision SQL fixups for a freshly provisioned database.
+//
+// Two things must happen at the Postgres level that the provisioning GraphQL API
+// does not do for us:
+//
+//  1. Naming settings — `constructive.simple_schema_names` and
+//     `schema_use_underscores` make later `provision_blueprint` calls create an
+//     `app_public` schema (which resolveSchemaId looks for) instead of a
+//     hyphenated `<db>-<hex>-app-public` one. These ALTER DATABASE settings
+//     PERSIST, so we set them once here, before any blueprint construction.
+//
+//  2. Membership defaults — new sign-ups otherwise land with
+//     is_approved=false/is_verified=false, the AuthzEntityMembership policy then
+//     denies every insert/select, and CRUD rows silently never persist
+//     (BLUEPRINT-PENDING-001). We flip the defaults (future sign-ups) AND any
+//     memberships already created during provisioning.
+//
+// All SQL targets the PHYSICAL control-plane database (`constructive`), NOT the
+// app's database name — that name is only a schema prefix (MEMBERSHIP-DB-001).
+//
+// Connection creds come from the ambient PG* env vars, falling back to sourcing
+// `pgpm env` (the same mechanism the old `eval "$(pgpm env)"` shell step used).
+// If neither yields a connection, provisioning still succeeded — we return a
+// note so the tool can warn the user that sign-in/CRUD may need a manual fixup.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+// Parse `pgpm env` output. It prints shell assignments (optionally `export`-
+// prefixed), one per line: `export PGHOST=localhost`. Quotes are stripped.
+export function parsePgpmEnv(stdout) {
+    const env = {};
+    for (const rawLine of stdout.split('\n')) {
+        const line = rawLine.trim().replace(/^export\s+/, '');
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+    }
+    return {
+        host: env.PGHOST,
+        port: env.PGPORT,
+        user: env.PGUSER,
+        password: env.PGPASSWORD,
+    };
+}
+export async function resolvePgEnv() {
+    if (process.env.PGHOST) {
+        return {
+            host: process.env.PGHOST,
+            port: process.env.PGPORT,
+            user: process.env.PGUSER,
+            password: process.env.PGPASSWORD,
+        };
+    }
+    try {
+        const { stdout } = await execFileAsync('pgpm', ['env'], { timeout: 15_000 });
+        const parsed = parsePgpmEnv(stdout);
+        return parsed.host ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Find the memberships schema for this app. Schema names use hyphens locally
+// (`<db>-<hex>-memberships-public`) but may use underscores when the naming
+// settings are active — match both, scoped to this app's name prefix.
+const MEMBERSHIPS_SCHEMA_QUERY = `
+  SELECT schema_name FROM information_schema.schemata
+   WHERE (schema_name LIKE '%memberships-public' OR schema_name LIKE '%memberships_public')
+         AND (schema_name LIKE $1 OR schema_name LIKE $2)
+   ORDER BY schema_name DESC LIMIT 1`;
+export async function applySqlFixups(args) {
+    const pgEnv = await resolvePgEnv();
+    if (!pgEnv) {
+        return {
+            applied: false,
+            note: 'Could not reach Postgres (no PGHOST and `pgpm env` unavailable). Database provisioned, but membership defaults were not enabled — sign-in/CRUD may fail until the constructive DB is fixed up manually.',
+        };
+    }
+    // pg is dynamically imported so the main bundle never loads it unless a
+    // provision actually runs with Postgres access. The import lives inside the
+    // try: fixups are best-effort, so even a broken pg module must degrade to a
+    // note instead of failing the tool after the database is already provisioned.
+    let pool;
+    try {
+        const { Pool } = await import('pg');
+        pool = new Pool({
+            host: pgEnv.host,
+            port: pgEnv.port ? Number(pgEnv.port) : undefined,
+            user: pgEnv.user,
+            password: pgEnv.password,
+            database: args.physicalDb,
+        });
+        const db = args.physicalDb;
+        // Persistent naming settings — so future provision_blueprint calls land an
+        // `app_public` schema resolveSchemaId can find.
+        await pool.query(`ALTER DATABASE "${db}" SET constructive.simple_schema_names = 'true'`);
+        await pool.query(`ALTER DATABASE "${db}" SET constructive.schema_use_underscores = 'true'`);
+        const schemaResult = await pool.query(MEMBERSHIPS_SCHEMA_QUERY, [
+            `${args.databaseName}-%`,
+            `${args.databaseName}\\_%`,
+        ]);
+        if (schemaResult.rows.length === 0) {
+            return {
+                applied: true,
+                note: `Naming settings applied, but no memberships schema was found for "${args.databaseName}" — sign-in may need a manual membership fixup.`,
+            };
+        }
+        const membershipsSchema = schemaResult.rows[0].schema_name;
+        await pool.query(`UPDATE "${membershipsSchema}".app_membership_defaults SET is_approved = TRUE, is_verified = TRUE`);
+        await pool.query(`UPDATE "${membershipsSchema}".app_memberships
+         SET is_approved = TRUE, is_verified = TRUE
+       WHERE is_approved = FALSE OR is_verified = FALSE`);
+        return { applied: true, note: `Membership defaults enabled (schema: ${membershipsSchema}).` };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            applied: false,
+            note: `Database provisioned, but SQL fixups failed (${message}). Sign-in/CRUD may fail until membership defaults are enabled manually.`,
+        };
+    }
+    finally {
+        await pool?.end().catch(() => { });
+    }
+}

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

@@ -0,0 +1,4 @@
+import { allModulePresets, getModulePreset, type ModulePreset } from 'node-type-registry';
+export type ProvisionModule = string | [string, Record<string, unknown>];
+export declare const DEFAULT_PROVISION_PRESET: string;
+export { allModulePresets, getModulePreset, type ModulePreset };

package/esm/provision-database/presets.js

@@ -0,0 +1,13 @@
+// Provision module presets — the canonical source of truth.
+//
+// The module list is NEVER hand-copied here. It is imported from the pinned
+// `node-type-registry` package (the same presets the backend and dashboard use),
+// so bumping that dependency is how the base module set moves. Hosts customize
+// on top with an ordered overlay (see `resolve.ts`) rather than editing a list.
+import { allModulePresets, getModulePreset, PresetB2bStorage, } from 'node-type-registry';
+// Default base preset. `b2b:storage` = the full multi-tenant B2B shape plus file
+// storage, matching Constructive's app shape. It carries the app-scoped secret,
+// identity-provider, and storage modules the backend's provisioning requires —
+// the drift the old hand-copied list caused (a dropped, then bare/unscoped, set).
+export const DEFAULT_PROVISION_PRESET = PresetB2bStorage.name;
+export { allModulePresets, getModulePreset };

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;
+}>;