@agentic-kit/db-tools 0.11.5 → 0.12.0

package/provision-database/provision.js

@@ -0,0 +1,565 @@
+"use strict";
+// Provisioning a project's database without ever creating a second one by
+// accident. Every step runs under a per-project lock, and:
+//  - a binding is DATABASE_ID alone: it is probed, then kept (and healed) or
+//    refused, never provisioned over;
+//  - replace mode swaps a binding only if it is still the one the caller saw,
+//    and never one that is live (host path) or suspended;
+//  - a recorded ticket that reads back empty, or a call that lost its ticket,
+//    finds an in-flight provision of the same name before anything new is
+//    requested, and a completed one is only reported (binding it is `adopt`);
+//  - the host saves the binding before `.env` is written.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boundDatabaseId = boundDatabaseId;
+exports.provisionDatabase = provisionDatabase;
+exports.provisionFromTool = provisionFromTool;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const app_workspace_1 = require("../app-workspace");
+const db_probe_1 = require("../db-probe");
+const host_1 = require("../host");
+const credential_1 = require("./credential");
+const env_file_1 = require("./env-file");
+const manifest_1 = require("./manifest");
+const pending_ticket_1 = require("./pending-ticket");
+const preset_match_1 = require("./preset-match");
+const request_database_1 = require("./request-database");
+const resolve_1 = require("./resolve");
+const DEFAULT_API_ENDPOINT = 'http://api.localhost:3000/graphql';
+const DEFAULT_MODULES_ENDPOINT = 'http://modules.localhost:3000/graphql';
+function failure(code, message, extra = {}) {
+    return { ...extra, success: false, message, code };
+}
+const errorText = (err) => (err instanceof Error ? err.message : String(err));
+const today = () => new Date().toISOString().slice(0, 10);
+const noop = () => undefined;
+async function readText(file) {
+    try {
+        return await (0, promises_1.readFile)(file, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+// Edit .env from its current content, read right before the write, so changes
+// made while this call waited on the backend (by another tool or the user)
+// aren't overwritten with what the file held when the call started.
+async function updateEnvFile(envPath, edit) {
+    await (0, promises_1.writeFile)(envPath, edit(await readText(envPath)));
+}
+/** The DATABASE_ID in a project's `.env`, if any. */
+async function boundDatabaseId(cwd) {
+    return (0, env_file_1.readEnv)(await readText(node_path_1.default.join(cwd, '.env'))).DATABASE_ID || undefined;
+}
+// The per-DB endpoints are subdomain.<domain>; the provisioning domain is the api
+// endpoint's host minus its first label (api.localhost -> localhost,
+// api.launchql.dev -> launchql.dev), so dev and devnet both provision correctly.
+function provisionDomain(apiEndpoint) {
+    try {
+        const { hostname } = new URL(apiEndpoint);
+        // A bare IP host has no domain hierarchy to strip: dropping its first label
+        // ('192.168.1.10' -> '168.1.10') would yield a garbage domain. Use it verbatim.
+        if (hostname.includes(':') || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname))
+            return hostname;
+        const parts = hostname.split('.');
+        return parts.length > 1 ? parts.slice(1).join('.') : parts.join('.');
+    }
+    catch {
+        return 'localhost';
+    }
+}
+// The host's poll deadline when it's a positive number, else the default.
+function pollDeadline(ms) {
+    return typeof ms === 'number' && Number.isFinite(ms) && ms > 0 ? ms : undefined;
+}
+// ---- per-project lock ----------------------------------------------------
+const projectLocks = new Map();
+// One provision per project at a time: a second call waits, then sees what
+// the first one left (a binding, a recorded ticket) instead of racing it.
+async function withProjectLock(cwd, fn) {
+    const key = await (0, promises_1.realpath)(cwd).catch(() => node_path_1.default.resolve(cwd));
+    const previous = projectLocks.get(key) ?? Promise.resolve();
+    let release = noop;
+    const done = new Promise((resolve) => (release = resolve));
+    const tail = previous.then(() => done);
+    projectLocks.set(key, tail);
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (projectLocks.get(key) === tail)
+            projectLocks.delete(key);
+    }
+}
+/**
+ * Provision the project's database, or keep the one it is bound to. The host
+ * entry point: replace mode refuses a live binding here, and `abandonPending`
+ * and `adopt` are honoured.
+ */
+function provisionDatabase(input, ctx, exec = app_workspace_1.run) {
+    return withProjectLock(ctx.cwd, () => provision(input, ctx.cwd, exec, false));
+}
+/**
+ * The provision_database tool's entry point: its `reprovision: true` may
+ * replace a live binding (a clean rebuild), unless the host turned tool
+ * reprovisioning off.
+ */
+function provisionFromTool(input, ctx, exec = app_workspace_1.run) {
+    return withProjectLock(ctx.cwd, () => provision(input, ctx.cwd, exec, true));
+}
+async function provision(input, cwd, exec, viaTool) {
+    const name = input.databaseName?.trim();
+    if (!name)
+        return failure('failed', 'database_name is required.');
+    // Unify endpoints onto the app's backend-config store (environment-aware:
+    // *.localhost:3000 in dev, *.launchql.dev packaged). A process.env override
+    // still wins for ad-hoc dev; the hardcoded default is a last resort if the
+    // store isn't ready.
+    const host = (0, host_1.getHost)();
+    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 project provisions UNDER the account (requestDatabase owns the
+    // database to the JWT user). The account bearer authenticates the mutation
+    // and the probes, and is the ACCESS_TOKEN written to .env; it expires with
+    // the login session, and any provision run (the skip path too) refreshes it.
+    const credential = (0, credential_1.selectProvisionCredential)(host.account(), host.signInHint);
+    if (credential.mode === 'error') {
+        return failure('signed-out', `Cannot provision a database: ${credential.reason}`);
+    }
+    const envPath = node_path_1.default.join(cwd, '.env');
+    const env = (0, env_file_1.readEnv)(await readText(envPath));
+    const bound = env.DATABASE_ID || undefined;
+    const r = {
+        host,
+        cwd,
+        envPath,
+        name,
+        mode: input.mode ?? 'ensure',
+        apiEndpoint,
+        modulesEndpoint,
+        bearer: credential.bearer,
+        ownerId: credential.ownerId,
+        viaTool,
+        executor: (0, request_database_1.createProvisionExecutor)({ apiEndpoint, modulesEndpoint, bearer: credential.bearer }),
+        // The probe carries the account bearer, so it only ever targets the
+        // app-configured backend, never a .env-pinned endpoint.
+        probe: (databaseId) => (0, db_probe_1.probeDatabase)({ endpoint: apiEndpoint, bearer: credential.bearer, databaseId, signInHint: host.signInHint }),
+    };
+    let replaced;
+    if (r.mode === 'replace') {
+        const refusal = await checkReplace(r, input, bound);
+        if (refusal)
+            return refusal;
+        replaced = bound;
+    }
+    else if (bound) {
+        return keepBinding(r, env, bound, input.adopt);
+    }
+    if (input.adopt) {
+        const prewarm = startPrewarm(r, exec);
+        return bindDatabase(r, { databaseId: input.adopt, replaced, adopted: true }, prewarm);
+    }
+    return requestAndBind(r, input, env, replaced, exec);
+}
+// ---- ensure: keep the binding --------------------------------------------
+async function keepBinding(r, env, bound, adopt) {
+    const probe = await r.probe(bound);
+    if (probe.status === 'unreachable') {
+        return failure('backend-unreachable', `Cannot verify the existing database binding (DATABASE_ID=${bound}): ${probe.detail}. Retry once the backend answers; don't reprovision on an unreachable backend.`, { databaseId: bound });
+    }
+    if (probe.status === 'missing') {
+        return failure('db-missing', `Project carries a binding (DATABASE_ID=${bound}) but that database no longer exists on this backend, or this account lost access to it. ${(0, host_1.reprovisionAdvice)(r.host)}`, { databaseId: bound });
+    }
+    if (probe.ownerId && probe.ownerId !== r.ownerId) {
+        return failure('account-mismatch', `Project carries a binding (DATABASE_ID=${bound}) but that database was provisioned under a different account than the one signed in. ${(0, host_1.reprovisionAdvice)(r.host)}`, { databaseId: bound });
+    }
+    if (probe.status === 'suspended') {
+        return failure('db-suspended', suspendedText(bound, probe), { databaseId: bound });
+    }
+    if (adopt && adopt !== bound) {
+        return failure('binding-live', `The project is bound to a live database (DATABASE_ID=${bound}); adopt binds only an unbound project. Use replace mode to swap it.`, { databaseId: bound });
+    }
+    // Heal .env on the skip path: a stale token (relogin), missing or stale
+    // endpoint pins, and the binding keys a partial .env lacks.
+    const databaseName = env.DATABASE_NAME || probe.name || '';
+    const ownerId = probe.ownerId ?? r.ownerId;
+    const refresh = {};
+    if (env.ACCESS_TOKEN !== r.bearer)
+        refresh.ACCESS_TOKEN = r.bearer;
+    if (env.API_ENDPOINT !== r.apiEndpoint)
+        refresh.API_ENDPOINT = r.apiEndpoint;
+    if (env.MODULES_ENDPOINT !== r.modulesEndpoint)
+        refresh.MODULES_ENDPOINT = r.modulesEndpoint;
+    if (!env.DATABASE_NAME && databaseName)
+        refresh.DATABASE_NAME = databaseName;
+    if (!env.PGDATABASE && databaseName)
+        refresh.PGDATABASE = databaseName;
+    if (!env.OWNER_ID)
+        refresh.OWNER_ID = ownerId;
+    const saved = await saveBinding(r, {
+        cwd: r.cwd,
+        databaseId: bound,
+        databaseName,
+        ownerId,
+        apiEndpoint: r.apiEndpoint,
+        modulesEndpoint: r.modulesEndpoint,
+        skipped: true,
+    });
+    if (saved)
+        return saved;
+    let note = '';
+    if (Object.keys(refresh).length > 0) {
+        const keys = Object.keys(refresh).join(', ');
+        try {
+            await updateEnvFile(r.envPath, (content) => (0, env_file_1.mergeEnv)(content, refresh));
+            note = ` Refreshed in .env: ${keys}.`;
+        }
+        catch (err) {
+            note = ` Could not refresh ${keys} in .env: ${errorText(err)}.`;
+        }
+    }
+    const advice = r.host.toolReprovision === false ? '' : ' Pass reprovision: true only for an explicit clean rebuild.';
+    return {
+        success: true,
+        message: `Project already provisioned (DATABASE_ID=${bound}) and the database is live under this account. Skipping.${advice}${note}`,
+        databaseId: bound,
+        databaseName,
+        ownerId,
+        skipped: true,
+    };
+}
+function suspendedText(databaseId, probe) {
+    const why = probe.suspendedReason ? ` (${probe.suspendedReason})` : '';
+    return `The bound database (DATABASE_ID=${databaseId}) is suspended${why} since ${probe.suspendedAt}. Its data is kept, so it isn't replaced; nothing can read or change it until the suspension is lifted.`;
+}
+// ---- replace: compare and swap -------------------------------------------
+async function checkReplace(r, input, bound) {
+    if (r.viaTool && r.host.toolReprovision === false) {
+        return failure('reprovision-not-allowed', `provision_database can't replace this project's database: the app replaces a database only after the user approves it. ${(0, host_1.reprovisionAdvice)(r.host)}`);
+    }
+    const expected = input.replaces === undefined ? bound : input.replaces || undefined;
+    if ((expected ?? '') !== (bound ?? '')) {
+        return failure('binding-changed', `The project's binding changed (DATABASE_ID is ${bound ?? 'unset'}, expected ${expected ?? 'unset'}), so nothing was replaced.`, { databaseId: bound });
+    }
+    if (!bound)
+        return null;
+    const probe = await r.probe(bound);
+    if (probe.status === 'unreachable') {
+        return failure('backend-unreachable', `Cannot verify the binding being replaced (DATABASE_ID=${bound}): ${probe.detail}. Retry once the backend answers.`, { databaseId: bound });
+    }
+    if (probe.status === 'suspended')
+        return failure('db-suspended', suspendedText(bound, probe), { databaseId: bound });
+    // A missing or foreign-owned binding is replaced; a live one of this account
+    // only through the tool's explicit rebuild.
+    if (probe.status === 'found' && (!probe.ownerId || probe.ownerId === r.ownerId) && !r.viaTool) {
+        return failure('binding-live', `The bound database (DATABASE_ID=${bound}) is live under this account, so it wasn't replaced.`, { databaseId: bound });
+    }
+    return null;
+}
+// The account's in-flight provisions of this name, newest first. A lookup that
+// can't reach the backend refuses (nothing may be requested blind); one that
+// gets another error leaves the caller to decide.
+async function findInFlight(r, skip) {
+    try {
+        const tickets = await r.executor.listOwn({ databaseName: r.name, ownerId: r.ownerId });
+        return { inFlight: tickets.filter((t) => t.id && !skip.has(t.id) && (0, request_database_1.isTicketInFlight)(t)) };
+    }
+    catch (err) {
+        if ((0, request_database_1.isTransientProvisionError)(err)) {
+            return {
+                inFlight: [],
+                refusal: failure('backend-unreachable', `Could not check the backend for a provision of "${r.name}" already in progress (${errorText(err)}). Nothing was requested; retry once the backend answers.`),
+            };
+        }
+        return { inFlight: [], problem: errorText(err) };
+    }
+}
+const ticketOf = (r, ticket) => ({
+    ticketId: ticket.id,
+    databaseName: r.name,
+    apiEndpoint: r.apiEndpoint,
+    userId: r.ownerId,
+    attempts: 0,
+});
+function startPrewarm(r, exec) {
+    // The packages/app scaffold + install are database-INDEPENDENT, so they run
+    // alongside the provision. Best-effort: run_codegen re-runs the same
+    // idempotent steps. A call that returns early leaves it running; a retry
+    // joins that same run rather than starting a second install.
+    return (0, app_workspace_1.prewarmAppWorkspace)(r.cwd, exec).catch((err) => ({ ok: false, out: errorText(err) }));
+}
+async function requestAndBind(r, input, env, replaced, exec) {
+    const abandoned = (0, pending_ticket_1.abandonedTickets)(env);
+    const abandon = async (ids) => {
+        for (const id of ids)
+            abandoned.add(id);
+        await updateEnvFile(r.envPath, (content) => (0, pending_ticket_1.recordAbandoned)((0, pending_ticket_1.clearPendingTicket)(content), ids)).catch(noop);
+    };
+    // A ticket an earlier call stopped waiting on.
+    let current;
+    let recovered = false;
+    const recorded = (0, pending_ticket_1.recordedTicket)(env);
+    if (recorded) {
+        if (recorded.apiEndpoint !== r.apiEndpoint || recorded.userId !== r.ownerId) {
+            // Requested on another backend or by another account: not ours to follow.
+            await updateEnvFile(r.envPath, (content) => (0, pending_ticket_1.archivePendingTicket)(content, today())).catch(noop);
+        }
+        else if (input.abandonPending) {
+            await abandon([recorded.ticketId]);
+        }
+        else if (recorded.databaseName !== r.name) {
+            return failure('pending-other', `A provision of "${recorded.databaseName}" (ticket ${recorded.ticketId}) is still recorded for this project. Call provision_database with database_name "${recorded.databaseName}" to finish it; another name would start a second database.`, { ticketId: recorded.ticketId });
+        }
+        else {
+            current = recorded;
+        }
+    }
+    // No ticket of ours is recorded, but an earlier call may have lost track of
+    // one (its record failed to write, or the call was cut off): look it up by
+    // name. Only an in-flight one is resumed.
+    if (!current) {
+        const lookup = await findInFlight(r, abandoned);
+        if (lookup.refusal)
+            return lookup.refusal;
+        if (lookup.inFlight.length > 0 && input.abandonPending) {
+            await abandon(lookup.inFlight.map((t) => t.id));
+        }
+        else if (lookup.inFlight.length > 0) {
+            current = ticketOf(r, lookup.inFlight[0]);
+            recovered = true;
+        }
+    }
+    const prewarm = startPrewarm(r, exec);
+    // Resolve the module set: pinned base preset from node-type-registry, then
+    // ordered overlays (host default < project-local provision.json). A bad
+    // preset/manifest fails the run rather than provisioning a wrong module set.
+    let modules;
+    try {
+        const layers = [];
+        const hostOverlay = await r.host.provisionOverlay?.();
+        if (hostOverlay)
+            layers.push(hostOverlay);
+        const projectOverlay = await (0, manifest_1.loadProvisionManifest)(r.cwd);
+        if (projectOverlay)
+            layers.push(projectOverlay);
+        modules = (0, resolve_1.resolveProvisionModules)(layers);
+    }
+    catch (err) {
+        return failure('failed', `Cannot resolve provision modules: ${errorText(err)}`);
+    }
+    // requestDatabase claims a warm-pool database when the module set matches a
+    // cataloged preset and cold-provisions otherwise; the ticket is polled on the
+    // modules endpoint until the database AND its owner bootstrap complete. An
+    // explicit subdomain (= name) keeps the per-DB endpoints deterministic.
+    const ticketFor = (ticketId) => ({
+        ticketId,
+        databaseName: r.name,
+        apiEndpoint: r.apiEndpoint,
+        userId: r.ownerId,
+        attempts: (current?.ticketId === ticketId ? current.attempts : 0) + 1,
+    });
+    const lost = new Set();
+    let provisioned;
+    for (;;) {
+        try {
+            provisioned = await (0, request_database_1.requestDatabaseProvision)({
+                apiEndpoint: r.apiEndpoint,
+                modulesEndpoint: r.modulesEndpoint,
+                bearer: r.bearer,
+                databaseName: r.name,
+                domain: provisionDomain(r.apiEndpoint),
+                request: (0, preset_match_1.selectProvisionRequest)(modules),
+                executor: r.executor,
+                // Past the attempt cap one read says whether it finished; no more waiting.
+                pollDeadlineMs: current && current.attempts >= pending_ticket_1.MAX_PENDING_ATTEMPTS ? 0 : pollDeadline(r.host.provisionPollDeadlineMs),
+                resumeTicketId: current?.ticketId,
+            });
+            break;
+        }
+        catch (err) {
+            if (err instanceof request_database_1.ProvisionPendingError) {
+                return pendingResult(r, ticketFor(err.ticketId), err.message, recovered);
+            }
+            if (err instanceof request_database_1.ProvisionTicketLostError) {
+                // The ticket can't be read back, which doesn't mean the provision
+                // stopped. Follow another in-flight one of this name, or stop without
+                // requesting anything.
+                lost.add(err.ticketId);
+                const lookup = await findInFlight(r, new Set([...abandoned, ...lost]));
+                if (lookup.refusal)
+                    return lookup.refusal;
+                if (lookup.inFlight.length > 0) {
+                    current = ticketOf(r, lookup.inFlight[0]);
+                    recovered = true;
+                    continue;
+                }
+                await updateEnvFile(r.envPath, pending_ticket_1.clearPendingTicket).catch(noop);
+                const checked = lookup.problem
+                    ? `the backend couldn't be asked for another one (${lookup.problem})`
+                    : 'no other provision of that name is in progress';
+                return failure('ticket-lost', `The provision of "${r.name}" (ticket ${err.ticketId}) can no longer be found on this backend, and ${checked}. Nothing was created, and the record is cleared, so calling provision_database again requests a new database.`, { ticketId: err.ticketId });
+            }
+            // A definitive failure ends the recorded request, so forget it.
+            if (current)
+                await updateEnvFile(r.envPath, pending_ticket_1.clearPendingTicket).catch(noop);
+            return requestFailure(r, err);
+        }
+    }
+    return bindDatabase(r, {
+        databaseId: provisioned.databaseId,
+        ticket: ticketFor(provisioned.ticketId),
+        resumed: provisioned.resumed === true,
+        recovered,
+        replaced,
+    }, prewarm);
+}
+// The provision is still running: record its ticket so the next call with the
+// same name resumes it. Past MAX_PENDING_ATTEMPTS the ticket stays recorded
+// and the call fails `provision-stuck`: nothing new is requested while it is
+// in flight, until the host abandons it.
+async function pendingResult(r, ticket, reason, recovered) {
+    const { ticketId } = ticket;
+    let recordedOk = true;
+    try {
+        await updateEnvFile(r.envPath, (content) => (0, pending_ticket_1.recordPendingTicket)(content, ticket));
+    }
+    catch {
+        recordedOk = false;
+    }
+    if (ticket.attempts > pending_ticket_1.MAX_PENDING_ATTEMPTS) {
+        return failure('provision-stuck', `Database "${r.name}" is still not ready after ${pending_ticket_1.MAX_PENDING_ATTEMPTS} waits (${reason}). Its request (ticket ${ticketId}) stays recorded, and no other database is requested while it is in progress. Check the backend's provisioning jobs.`, { ticketId });
+    }
+    const again = `call provision_database again with database_name "${r.name}"${r.mode === 'replace' && r.viaTool ? ' and reprovision: true' : ''}`;
+    const message = recordedOk
+        ? `Database "${r.name}" is still provisioning (${reason}). The request is recorded in .env; ${again} to keep waiting on it. Don't change the name: that starts a second database.`
+        : `Database "${r.name}" is still provisioning (${reason}). Recording its ticket in .env failed, but the backend still has it: ${again} to keep waiting on it. Don't change the name: that starts a second database.`;
+    return { success: false, message, pending: true, ticketId, ...(recovered ? { recovered: true } : {}) };
+}
+const NAME_TAKEN_RE = /already exists|already taken|already in use|duplicate/i;
+async function requestFailure(r, err) {
+    const detail = errorText(err);
+    if (!NAME_TAKEN_RE.test(detail))
+        return failure('failed', `Database provisioning failed: ${detail}.`);
+    const heldBy = await ownHolder(r);
+    if (heldBy) {
+        const when = heldBy.createdAt ? `, requested ${heldBy.createdAt}` : '';
+        return failure('name-taken', `Database provisioning failed: ${detail}. The name "${r.name}" belongs to a database this account provisioned earlier (ID ${heldBy.databaseId}${when}) that this project isn't bound to, so it was not bound. Re-run with a different database_name.`, { heldBy });
+    }
+    return failure('name-taken', `Database provisioning failed: ${detail}. The database name is already taken on the backend; re-run with a different database_name.`);
+}
+// A completed provision of this name by this account whose database still
+// exists under it: reported with name-taken so the host can adopt it.
+async function ownHolder(r) {
+    let tickets;
+    try {
+        tickets = await r.executor.listOwn({ databaseName: r.name, ownerId: r.ownerId });
+    }
+    catch {
+        return undefined;
+    }
+    const done = tickets.find((t) => t.status === 'completed' && t.databaseId && !(0, request_database_1.isTicketInFlight)(t));
+    if (!done)
+        return undefined;
+    const probe = await r.probe(done.databaseId);
+    if (probe.status !== 'found' && probe.status !== 'suspended')
+        return undefined;
+    if (probe.ownerId && probe.ownerId !== r.ownerId)
+        return undefined;
+    return { databaseId: done.databaseId, yours: true, ...(done.createdAt ? { createdAt: done.createdAt } : {}) };
+}
+// ---- binding ---------------------------------------------------------------
+async function saveBinding(r, binding, ticket) {
+    if (!r.host.persistBinding)
+        return null;
+    try {
+        await r.host.persistBinding(binding);
+        return null;
+    }
+    catch (err) {
+        // Keep the ticket recorded, so the next call resumes it and binds it.
+        if (ticket)
+            await updateEnvFile(r.envPath, (content) => (0, pending_ticket_1.recordPendingTicket)(content, ticket)).catch(noop);
+        return failure('binding-not-saved', `Database "${binding.databaseName}" (ID ${binding.databaseId}) is ready, but the app couldn't save the binding (${errorText(err)}), so .env was left unchanged.${ticket ? ' Calling provision_database again with the same name binds it.' : ''}`, { databaseId: binding.databaseId, ...(ticket ? { ticketId: ticket.ticketId } : {}) });
+    }
+}
+async function bindDatabase(r, bind, prewarm) {
+    const { databaseId, ticket } = bind;
+    // Bind only a database this account owns. An unreachable backend keeps the
+    // ticket for the next call to check again.
+    const owner = await r.probe(databaseId);
+    if (owner.status === 'unreachable') {
+        if (ticket) {
+            return pendingResult(r, ticket, `provisioned, but its owner couldn't be confirmed: ${owner.detail}`, bind.recovered);
+        }
+        return failure('backend-unreachable', `Cannot verify database ${databaseId}: ${owner.detail}. Retry once the backend answers.`);
+    }
+    const visible = owner.status !== 'missing';
+    if (!visible || owner.ownerId !== r.ownerId) {
+        if (ticket)
+            await updateEnvFile(r.envPath, pending_ticket_1.clearPendingTicket).catch(noop);
+        const why = visible ? "it isn't owned by" : "it isn't visible to";
+        if (bind.adopted) {
+            return failure(visible ? 'account-mismatch' : 'db-missing', `Database ${databaseId} was not bound: ${why} the signed-in account.`);
+        }
+        return failure('failed', `Database provisioning returned database ${databaseId}, but ${why} the signed-in account, so it was not bound. Call provision_database again to request a new database.`);
+    }
+    if (bind.adopted && owner.status === 'suspended') {
+        return failure('db-suspended', suspendedText(databaseId, owner));
+    }
+    const saved = await saveBinding(r, {
+        cwd: r.cwd,
+        databaseId,
+        databaseName: r.name,
+        ownerId: r.ownerId,
+        apiEndpoint: r.apiEndpoint,
+        modulesEndpoint: r.modulesEndpoint,
+        ...(bind.replaced ? { replaces: bind.replaced } : {}),
+    }, ticket);
+    if (saved)
+        return saved;
+    // Write the binding into .env (upsert, preserving other keys), dropping any
+    // recorded pending request: the project is bound now.
+    try {
+        await updateEnvFile(r.envPath, (content) => (0, env_file_1.mergeEnv)((0, pending_ticket_1.clearPendingTicket)(bind.replaced ? (0, env_file_1.archiveBindingKeys)(content, env_file_1.ARCHIVED_BINDING_KEYS, today()) : content), (0, env_file_1.provisionEnvVars)({
+            databaseId,
+            databaseName: r.name,
+            ownerId: r.ownerId,
+            accessToken: r.bearer,
+            apiEndpoint: r.apiEndpoint,
+            modulesEndpoint: r.modulesEndpoint,
+        })));
+    }
+    catch (err) {
+        return failure('env-write-failed', `Database provisioned (ID: ${databaseId}) but writing .env failed: ${errorText(err)}`, { databaseId });
+    }
+    // Settle the concurrent prewarm so the scaffold + install are in place before
+    // run_codegen runs. A failure here is non-fatal: run_codegen redoes the work.
+    const prewarmed = (await prewarm).ok ? ' packages/app prewarmed.' : '';
+    const notes = [
+        bind.resumed ? ' Finished the provision an earlier call had started.' : '',
+        bind.recovered ? ' Found it on the backend by name: its ticket was no longer recorded.' : '',
+        prewarmed,
+        bind.replaced
+            ? ' Previous binding archived in .env (old database kept); rebuild the schema with provision_blueprint + run_codegen.'
+            : '',
+    ].join('');
+    const message = bind.adopted
+        ? `Bound database "${r.name}" (ID: ${databaseId}), which this account provisioned earlier. Credentials written to .env.${notes}`
+        : `Provisioned database "${r.name}" (ID: ${databaseId}). Credentials written to .env.${notes}`;
+    return {
+        success: true,
+        message,
+        databaseId,
+        databaseName: r.name,
+        ownerId: r.ownerId,
+        ...(bind.resumed ? { resumed: true } : {}),
+        ...(bind.recovered ? { recovered: true } : {}),
+        ...(bind.replaced ? { replaced: bind.replaced } : {}),
+    };
+}

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

@@ -16,10 +16,12 @@ export type ProvisionTicket = {
     databaseId?: string | null;
     errorMessage?: string | null;
     bootstrapError?: string | null;
+    databaseName?: string | null;
+    createdAt?: string | null;
 };
 /**
- * Request + poll seam, injectable for tests (pattern: db-probe's
- * ProbeExecutor). The default executor drives the SDK clients.
+ * Request, poll and lookup seam, injectable for tests. The default executor
+ * drives the SDK clients.
  */
 export type ProvisionRequestExecutor = {
     request(input: {
@@ -29,6 +31,11 @@ export type ProvisionRequestExecutor = {
         request: ProvisionRequest;
     }): Promise<ProvisionTicket>;
     poll(ticketId: string): Promise<ProvisionTicket | null>;
+    /** The account's newest tickets for a database name, newest first. */
+    listOwn(filter: {
+        databaseName: string;
+        ownerId: string;
+    }): Promise<ProvisionTicket[]>;
 };
 export declare const POLL_INTERVAL_MS = 2000;
 /** Stays under airpage's 5-minute per-tool timeout. */
@@ -39,12 +46,54 @@ export declare const POLL_DEADLINE_MS = 240000;
  * a creation that is about to succeed.
  */
 export declare const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+/**
+ * The provision is still running server-side, but this call stopped waiting:
+ * the deadline passed, or the backend couldn't be reached. A caller should keep
+ * `ticketId` and pass it back as `resumeTicketId`, because requesting the same
+ * name again starts a second provision rather than resuming this one.
+ */
+export declare class ProvisionPendingError extends Error {
+    readonly ticketId: string;
+    constructor(message: string, ticketId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The recorded ticket can't be read back: it is gone, or this account can't
+ * see it. Nothing says the provision stopped, so a caller must not request
+ * the same database again on this alone.
+ */
+export declare class ProvisionTicketLostError extends Error {
+    readonly ticketId: string;
+    constructor(message: string, ticketId: string);
+}
+export declare function createProvisionExecutor(args: {
+    apiEndpoint: string;
+    modulesEndpoint: string;
+    bearer: string;
+}): ProvisionRequestExecutor;
+/** A ticket whose provision or owner bootstrap is still running. */
+export declare function isTicketInFlight(ticket: ProvisionTicket): boolean;
+/**
+ * Whether an error reading or requesting a ticket says only that the backend
+ * couldn't be reached or failed: a network error thrown before any response,
+ * or an HTTP 5xx/429 the adapter reports as the only error. A GraphQL error
+ * (validation, permission, an expired or rejected token) is an answer, so the
+ * ticket can't be followed any further.
+ */
+export declare function isTransientProvisionError(err: unknown): boolean;
 /**
  * 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`.
+ * `bootstrapStatus: 'failed'` surfaces `bootstrapError`. Stopping short of
+ * either outcome throws `ProvisionPendingError`.
+ *
+ * With `resumeTicketId` the ticket of an earlier call is polled instead of
+ * requesting again, and `resumed` is true. A ticket that reads back empty
+ * throws `ProvisionTicketLostError`, never a new request: the provision may
+ * still be running where this account can't see it.
  */
 export declare function requestDatabaseProvision(args: {
     apiEndpoint: string;
@@ -56,6 +105,9 @@ export declare function requestDatabaseProvision(args: {
     executor?: ProvisionRequestExecutor;
     pollIntervalMs?: number;
     pollDeadlineMs?: number;
+    resumeTicketId?: string;
 }): Promise<{
     databaseId: string;
+    ticketId: string;
+    resumed?: true;
 }>;