@agentic-kit/db-tools 0.11.5 → 0.12.1

package/README.md

@@ -29,7 +29,7 @@ npm install @agentic-kit/db-tools
 
 - **18 typed db tools** — `provision_database`, `provision_blueprint`, `describe_schema`, `add_relation`, `delete_table`, `create_field` / `update_field` / `delete_field`, `add_policies`, `add_records`, `manage_entity_types`, `create_api_key`, `run_codegen`, and the template suite (`list` / `create` / `apply` / `update` / `delete`). `constructiveDbTools` is the list, in registration order.
 - **Host injection** — credentials, backend endpoints and data-plane tokens come from the host application, not from the package. Call `configureHost()` once at startup; the tools read it lazily per call.
-- **Project context** — `resolveProjectContext` / `resolveDataToken` resolve the database a tool acts on from the cwd's `.env` plus the host's session, and `deriveSubdomainEndpoint` derives its per-database endpoints.
+- **Project context** — `resolveProjectContext` / `resolveDataToken` resolve the database a tool acts on from the cwd's `.env` plus the host's session, and `deriveSubdomainEndpoint` derives its per-database endpoints. `probeDatabase` says whether that database is still there, and `readSchemaModel` reads its app tables.
 - **Provisioning model** — the pinned `node-type-registry` presets, the provision manifest, and overlay resolution (`resolveProvisionModules`).
 - **`constructiveGateDeps`** — the confirm gate's host capabilities (is the project runnable, is there a data token, what tables would a template copy) answered by these resolvers, so every adapter gates the same tools against the same project state instead of restating it.
 - **`toolSchema`** — a tool's zod parameters as plain JSON Schema, for adapters whose harness wants JSON Schema rather than zod.
@@ -56,6 +56,45 @@ A tool executes against nothing but its params and a context, so it is callable
 const result = await describeSchemaTool.execute({ database_name: 'my-app' }, { cwd: process.cwd() });
 ```
 
+## Is the bound database still there?
+
+`probeDatabase` (or `probeBoundDatabase(id)`, which uses the host's account and control endpoint) asks the platform api and returns one of:
+
+| `status` | Means | Recovery |
+| --- | --- | --- |
+| `found` | Live; carries `name`, `ownerId` and `hash` (the schema hash, which changes on every schema change) | none |
+| `suspended` | It exists and keeps its data, but is held (`suspendedAt`, `suspendedReason`) | wait for the hold to lift; never replace it |
+| `missing` | The backend answered and this account can't see it: deleted, or access lost | re-provision |
+| `unreachable` | No usable answer; `cause` is `network`, `server`, `auth` (account credential rejected) or `error` (an error the probe doesn't know) | retry or sign in; never re-provision |
+
+Only `missing` means the database is gone. On a backend without `hash`, the probe retries once without it and `hash` is undefined. `resolveProjectContext` reports the same states as `db-missing`, `db-suspended`, `account-mismatch` and `backend-unreachable` (with `cause`), and a resolved context carries `hash`.
+
+Tenant APIs answer `ACCESS_SUSPENDED` (a 403 with a JSON body) for a deleted or suspended database. The SDK's `FetchAdapter` drops that body, so `postGraphQL` and `statusAdapter` (a drop-in ORM adapter) keep each error's `extensions.code` and HTTP status, and `classifyBackendErrors` sorts them into `suspended`, `network`, `server`, `auth`, `forbidden` or `graphql`. `add_records`, `run_codegen` and `create_api_key` return `details.code: 'database-unavailable'` on `ACCESS_SUSPENDED`, and `run_codegen` doesn't retry a refused introspection.
+
+## The live schema
+
+`readSchemaModel(context)` reads the app tables (category `APP`, whoever created them) from the metaschema in one piece, or throws `SchemaReadError`; a partial read would look like columns dropped outside. Each table has its stable metaschema id, every field with its category (a status column made by `DataStatusField` is `MODULE`), a normalised type, `isRequired`, a structured default (`value`, `now`, `today`, `generated` or `expression`), the values an IN-list check allows, primary-key and unique flags, foreign keys with their delete and update actions (targets outside the app tables still resolve), and its policies. `accessOf(policies)` maps them to `shared`, `private` or `custom`. The model's `hash` is read before anything else.
+
+## Provisioning
+
+`provision_database` and the host-side `provisionDatabase(input, { cwd })` never create a second database by accident. Calls for one project run one at a time. A binding is `DATABASE_ID` alone: it is probed, then kept (healing the token, endpoints and any missing keys) or refused. Replace mode (`mode: 'replace', replaces: <the id the caller saw>`) swaps the binding only if it is still that one, and never swaps a suspended database, or a live one on the host path. A provision that outlasts the poll is recorded in `.env` and resumed by the next call. A ticket that can't be read back, or a call that lost track of its ticket, finds an in-flight provision of the same name with `listOwn` before anything is requested; a completed one is only reported. After `MAX_PENDING_ATTEMPTS` waits the call fails `provision-stuck` until the host passes `abandonPending`.
+
+Failures carry a `code`: `signed-out`, `backend-unreachable`, `db-missing`, `db-suspended`, `account-mismatch`, `binding-live`, `binding-changed`, `pending-other`, `ticket-lost`, `provision-stuck`, `name-taken` (with `heldBy` when a database of this account holds the name, which the host can bind with `adopt: <id>`), `binding-not-saved`, `env-write-failed`, `reprovision-not-allowed` or `failed`.
+
+Host hooks for this, all optional:
+
+- `persistBinding(binding)` saves the binding in the host's own store before `.env` is written. If it throws, `.env` is left alone, the ticket stays recorded, and the call fails `binding-not-saved`.
+- `toolReprovision: false` makes the tool's `reprovision: true` fail `reprovision-not-allowed`, for a host that replaces databases only after the user approves.
+- `reprovisionHint` replaces the "re-provision with `reprovision: true`" advice in failure messages.
+
+## Blueprint builds
+
+`constructBlueprint` queues the build and returns the construction id, and the backend builds one blueprint at a time. So `provision_blueprint`, `add_relation` and `apply_template` wait for their build through `buildBlueprint` (or `waitForConstruction`, given an id), which reads the construction every 2 s until it is `constructed`, and returns the construction id and its table map, or `failed`, and throws with the backend's error code and message. The error is read in a separate query after the failure, so the status reads also work on a backend without the `error` column, and there the failure says the backend gave no reason. A host that polls on its own reads the reason the same way with `readConstructionFailure`. On a backend that still builds inside the mutation, the first read already says `constructed`.
+
+The wait gives up after `CONSTRUCTION_DEADLINE_MS` (240 s: the build's own 120 s statement timeout, plus as long again in the queue), when the signal aborts, or when the status can't be read (a GraphQL error, or 3 network failures in a row), and says the build may still finish. A host that limits how long a tool runs should give these three tools more than 240 s.
+
+Once the backend has queued the build, `buildBlueprint` throws every failure as a `BlueprintBuildError` with its `constructionId`, and `provision_blueprint` puts that id on `details.constructionId`, whether the build succeeded or not. The build carries on without the call, so a host that retries failed calls shouldn't retry one that has an id: a second build of the same tables fails on the ones the first made. Without an id, nothing was queued.
+
 ## Related
 
 | Package | Role |

package/app-workspace.d.ts

@@ -1,16 +1,43 @@
 export declare const NATIVE_BUILD_DEPS: string[];
 export declare const IGNORED_BUILDS_RE: RegExp;
+export declare const COMPOSE_MARKER: string;
+export type AppKind = {
+    kind: 'composed';
+} | {
+    kind: 'template';
+} | {
+    kind: 'invalid';
+    reason: string;
+};
+/**
+ * Which flow packages/app takes. Composed needs the marker to be a JSON object
+ * and the app's own lockfile beside it. A marker that fails either check is
+ * neither: running the template fixups would rewrite a composed app, so
+ * callers stop and report the reason instead.
+ */
+export declare function detectAppKind(appDir: string): AppKind;
+export type RunCommand = (cmd: string, args: string[], cwd: string, env?: Record<string, string>) => Promise<{
+    ok: boolean;
+    out: string;
+}>;
 export declare function run(cmd: string, args: string[], cwd: string, env?: Record<string, string>): Promise<{
     ok: boolean;
     out: string;
 }>;
 export declare function ensureWorkspaceConfig(cwd: string): Promise<void>;
 export declare function pinCodegenLatest(appDir: string): Promise<void>;
-export declare function ensureAppScaffold(cwd: string): Promise<{
+export declare function ensureAppScaffold(cwd: string, exec?: RunCommand): Promise<{
+    ok: boolean;
+    out: string;
+}>;
+export declare function ensureComposedInstall(cwd: string, exec?: RunCommand): Promise<{
     ok: boolean;
     out: string;
+    installed: boolean;
 }>;
-export declare function prewarmAppWorkspace(cwd: string): Promise<{
+export declare function prewarmAppWorkspace(cwd: string, exec?: RunCommand): Promise<{
     ok: boolean;
     out: string;
 }>;
+/** Wait for a prewarm still running for `cwd`; its outcome doesn't matter here. */
+export declare function settlePrewarm(cwd: string): Promise<void>;

package/app-workspace.js

@@ -3,12 +3,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IGNORED_BUILDS_RE = exports.NATIVE_BUILD_DEPS = void 0;
+exports.COMPOSE_MARKER = exports.IGNORED_BUILDS_RE = exports.NATIVE_BUILD_DEPS = void 0;
+exports.detectAppKind = detectAppKind;
 exports.run = run;
 exports.ensureWorkspaceConfig = ensureWorkspaceConfig;
 exports.pinCodegenLatest = pinCodegenLatest;
 exports.ensureAppScaffold = ensureAppScaffold;
+exports.ensureComposedInstall = ensureComposedInstall;
 exports.prewarmAppWorkspace = prewarmAppWorkspace;
+exports.settlePrewarm = settlePrewarm;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
@@ -33,6 +36,38 @@ exports.IGNORED_BUILDS_RE = /ERR_PNPM_IGNORED_BUILDS|Ignored build scripts/;
 const DEFAULT_GRAPHQL_OVERRIDE = '16.14.0';
 const TEMPLATE_REPO = 'https://github.com/constructive-io/sandbox-templates';
 const TEMPLATE_SUBDIR = node_path_1.default.join('nextjs', 'constructive-app');
+// A composed app carries this marker, written when its template was composed.
+// It ships its own pinned package.json and pnpm-lock.yaml, so none of the
+// constructive-app fixups below apply to it.
+exports.COMPOSE_MARKER = node_path_1.default.join('.constructive', 'compose.json');
+/**
+ * Which flow packages/app takes. Composed needs the marker to be a JSON object
+ * and the app's own lockfile beside it. A marker that fails either check is
+ * neither: running the template fixups would rewrite a composed app, so
+ * callers stop and report the reason instead.
+ */
+function detectAppKind(appDir) {
+    const marker = node_path_1.default.join(appDir, exports.COMPOSE_MARKER);
+    if (!(0, node_fs_1.existsSync)(marker))
+        return { kind: 'template' };
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(marker, 'utf8'));
+    }
+    catch {
+        return { kind: 'invalid', reason: `packages/app/${exports.COMPOSE_MARKER} is not valid JSON.` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { kind: 'invalid', reason: `packages/app/${exports.COMPOSE_MARKER} is not a JSON object.` };
+    }
+    if (!(0, node_fs_1.existsSync)(node_path_1.default.join(appDir, 'pnpm-lock.yaml'))) {
+        return {
+            kind: 'invalid',
+            reason: `packages/app has ${exports.COMPOSE_MARKER} but no pnpm-lock.yaml, so it can't be installed as composed.`,
+        };
+    }
+    return { kind: 'composed' };
+}
 async function run(cmd, args, cwd, env) {
     try {
         const { stdout, stderr } = await execFileAsync(cmd, args, {
@@ -92,14 +127,14 @@ async function pinCodegenLatest(appDir) {
 // its CLI is unreliable in the non-TTY agent shell, which made the agent thrash
 // for minutes. Materialize `packages/app` deterministically by shallow-cloning
 // the template instead (PGPM-001).
-async function ensureAppScaffold(cwd) {
+async function ensureAppScaffold(cwd, exec = run) {
     const appDir = node_path_1.default.join(cwd, 'packages', 'app');
     if ((0, node_fs_1.existsSync)(node_path_1.default.join(appDir, 'package.json'))) {
         return { ok: true, out: 'packages/app already scaffolded' };
     }
     const tmp = node_path_1.default.join(node_os_1.default.tmpdir(), `airpage-app-template-${process.pid}`);
     await (0, promises_1.rm)(tmp, { recursive: true, force: true });
-    const clone = await run('git', ['clone', '--depth', '1', TEMPLATE_REPO, tmp], cwd);
+    const clone = await exec('git', ['clone', '--depth', '1', TEMPLATE_REPO, tmp], cwd);
     if (!clone.ok) {
         await (0, promises_1.rm)(tmp, { recursive: true, force: true });
         return { ok: false, out: `Template clone failed:\n${clone.out}` };
@@ -123,21 +158,77 @@ async function ensureAppScaffold(cwd) {
     await (0, promises_1.rm)(tmp, { recursive: true, force: true });
     return { ok: true, out: 'Scaffolded packages/app from the constructive-app template.' };
 }
+// pnpm writes node_modules/.modules.yaml once an install finishes linking, so a
+// partial install (interrupted, or failed mid-way) lacks it. Codegen also
+// needs its bin, so both must be there to skip the install.
+function composedInstallComplete(appDir) {
+    const modules = node_path_1.default.join(appDir, 'node_modules');
+    return ((0, node_fs_1.existsSync)(node_path_1.default.join(modules, '.modules.yaml')) &&
+        (0, node_fs_1.existsSync)(node_path_1.default.join(modules, '.bin', 'graphql-codegen')));
+}
+// Install a composed app exactly as its lockfile pins it, unless a finished
+// install is already there. The install runs in packages/app against its own
+// lockfile, from the store where it can. A nested pnpm-workspace.yaml makes the
+// app its own workspace root, so the config is left alone; without one, a root
+// pnpm-workspace.yaml would pull the install up to the project root, where no
+// lockfile exists, so pnpm is told to ignore it instead of rewriting it.
+async function ensureComposedInstall(cwd, exec = run) {
+    const appDir = node_path_1.default.join(cwd, 'packages', 'app');
+    if (composedInstallComplete(appDir)) {
+        return { ok: true, out: 'packages/app dependencies already installed.', installed: false };
+    }
+    const args = ['install', '--frozen-lockfile', '--prefer-offline'];
+    const ownsWorkspace = (0, node_fs_1.existsSync)(node_path_1.default.join(appDir, 'pnpm-workspace.yaml'));
+    if (!ownsWorkspace && (0, node_fs_1.existsSync)(node_path_1.default.join(cwd, 'pnpm-workspace.yaml'))) {
+        args.push('--ignore-workspace');
+    }
+    const install = await exec('pnpm', args, appDir);
+    if (!install.ok && !exports.IGNORED_BUILDS_RE.test(install.out)) {
+        return { ok: false, out: `pnpm install failed:\n${install.out}`, installed: true };
+    }
+    return { ok: true, out: 'Installed packages/app from its lockfile.', installed: true };
+}
 // Scaffold packages/app, hoist the workspace config, pin codegen, and run the one
 // clean install. All of this is database-INDEPENDENT, so it can be prewarmed
 // concurrently with the ~90s provision_database backend mutation to keep clone +
 // install off run_codegen's critical path. Best-effort and fully idempotent:
 // run_codegen re-runs the same steps, finding the scaffold present and the install
 // already satisfied (a fast no-op). Errors are swallowed by callers that prewarm —
-// run_codegen surfaces any real failure later.
-async function prewarmAppWorkspace(cwd) {
-    const scaffold = await ensureAppScaffold(cwd);
+// run_codegen surfaces any real failure later. A composed app only gets its
+// frozen install, and an invalid marker leaves the app untouched.
+//
+// One prewarm runs per project at a time: a call while one is in flight gets
+// that same run, so a retried provision_database (or run_codegen, via
+// settlePrewarm) never starts a second install beside it.
+const prewarmsInFlight = new Map();
+function prewarmAppWorkspace(cwd, exec = run) {
+    const key = node_path_1.default.resolve(cwd);
+    const inFlight = prewarmsInFlight.get(key);
+    if (inFlight)
+        return inFlight;
+    const started = prewarm(cwd, exec).finally(() => prewarmsInFlight.delete(key));
+    prewarmsInFlight.set(key, started);
+    return started;
+}
+/** Wait for a prewarm still running for `cwd`; its outcome doesn't matter here. */
+async function settlePrewarm(cwd) {
+    await prewarmsInFlight.get(node_path_1.default.resolve(cwd))?.catch(() => undefined);
+}
+async function prewarm(cwd, exec) {
+    const appDir = node_path_1.default.join(cwd, 'packages', 'app');
+    const app = detectAppKind(appDir);
+    if (app.kind === 'invalid')
+        return { ok: false, out: app.reason };
+    if (app.kind === 'composed') {
+        const install = await ensureComposedInstall(cwd, exec);
+        return install.ok ? { ok: true, out: 'Prewarmed packages/app install.' } : install;
+    }
+    const scaffold = await ensureAppScaffold(cwd, exec);
     if (!scaffold.ok)
         return scaffold;
-    const appDir = node_path_1.default.join(cwd, 'packages', 'app');
     await ensureWorkspaceConfig(cwd);
     await pinCodegenLatest(appDir);
-    const install = await run('pnpm', ['install', '--no-frozen-lockfile'], cwd);
+    const install = await exec('pnpm', ['install', '--no-frozen-lockfile'], cwd);
     if (!install.ok && !exports.IGNORED_BUILDS_RE.test(install.out)) {
         return { ok: false, out: `pnpm install failed:\n${install.out}` };
     }

package/blueprint-construction.d.ts

@@ -0,0 +1,60 @@
+import type { ModulesClient } from './context';
+/**
+ * How long a tool waits for its build: the build's own 120 s statement
+ * timeout, plus as long again for the builds queued ahead of it (a cold build
+ * of a curated blueprint takes 15-40 s). It stays under the 5-minute limit
+ * hosts put on the long database tools, so the tool reports the wait itself
+ * instead of being cut off.
+ */
+export declare const CONSTRUCTION_DEADLINE_MS = 240000;
+export declare const CONSTRUCTION_POLL_MS = 2000;
+/**
+ * Unreadable statuses in a row tolerated before giving up. The build goes on
+ * whether or not a read gets through, so a dropped request or a momentary 502
+ * must not end the wait.
+ */
+export declare const MAX_CONSECUTIVE_READ_FAILURES = 3;
+/** Table name → id, for the tables a construction created. */
+export type ConstructionTableMap = Record<string, string>;
+export type WaitForConstructionOptions = {
+    signal?: AbortSignal;
+    deadlineMs?: number;
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+/**
+ * Why a construction failed, from its `error` column. That column came with
+ * the queued build, and the modules SDK predates it, so it is read on its own
+ * after a failure: the status reads stay valid on a backend without it. The
+ * SDK's select type doesn't list `error`, but the ORM writes each select key
+ * as the field name.
+ */
+export declare function readConstructionFailure(modules: ModulesClient, constructionId: string): Promise<string>;
+/**
+ * Wait for a construction to finish. Resolves with its table map once it is
+ * constructed, and throws with the backend's coded error once it failed, or
+ * when the deadline passes, the signal aborts, or its status can't be read.
+ */
+export declare function waitForConstruction(modules: ModulesClient, constructionId: string, options?: WaitForConstructionOptions): Promise<ConstructionTableMap>;
+/**
+ * A build that failed after the backend queued it, or that the wait gave up
+ * on. The construction carries on without the caller, so constructing again
+ * would queue the same tables a second time.
+ */
+export declare class BlueprintBuildError extends Error {
+    readonly constructionId: string;
+    constructor(message: string, constructionId: string);
+}
+/**
+ * Construct a blueprint into a schema and wait for the build. Resolves with
+ * the construction and the created tables. Once the backend has queued the
+ * build, every failure is a BlueprintBuildError with its construction id.
+ */
+export declare function buildBlueprint(modules: ModulesClient, input: {
+    blueprintId: string;
+    schemaId: string;
+}, options?: WaitForConstructionOptions): Promise<{
+    constructionId: string;
+    tables: ConstructionTableMap;
+}>;

package/blueprint-construction.js

@@ -0,0 +1,161 @@
+"use strict";
+// Building a blueprint: constructBlueprint enqueues a `blueprint:construct`
+// job and returns the construction id at once (constructive-db#4156). A worker
+// builds one blueprint at a time, each under a 120 s statement timeout, and
+// moves the construction row pending → constructing → constructed | failed,
+// with a failed build's coded error in `error`. A backend from before that
+// builds inside the mutation and raises the build's error from it, so the
+// first read already says constructed, and the same wait serves both.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlueprintBuildError = exports.MAX_CONSECUTIVE_READ_FAILURES = exports.CONSTRUCTION_POLL_MS = exports.CONSTRUCTION_DEADLINE_MS = void 0;
+exports.readConstructionFailure = readConstructionFailure;
+exports.waitForConstruction = waitForConstruction;
+exports.buildBlueprint = buildBlueprint;
+const request_database_1 = require("./provision-database/request-database");
+/**
+ * How long a tool waits for its build: the build's own 120 s statement
+ * timeout, plus as long again for the builds queued ahead of it (a cold build
+ * of a curated blueprint takes 15-40 s). It stays under the 5-minute limit
+ * hosts put on the long database tools, so the tool reports the wait itself
+ * instead of being cut off.
+ */
+exports.CONSTRUCTION_DEADLINE_MS = 240_000;
+exports.CONSTRUCTION_POLL_MS = 2_000;
+/**
+ * Unreadable statuses in a row tolerated before giving up. The build goes on
+ * whether or not a read gets through, so a dropped request or a momentary 502
+ * must not end the wait.
+ */
+exports.MAX_CONSECUTIVE_READ_FAILURES = 3;
+const MAY_STILL_FINISH = 'The build may still finish on the backend: read the schema before you call again.';
+const errorText = (err) => (err instanceof Error ? err.message : String(err));
+function stopped() {
+    return new Error(`Stopped waiting for the blueprint build. ${MAY_STILL_FINISH}`);
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(stopped());
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(stopped());
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function tableMapOf(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    return Object.fromEntries(Object.entries(raw).filter((entry) => typeof entry[1] === 'string'));
+}
+/**
+ * A failed construction's coded error on one line: `CODE: message` for a
+ * database error, `CODE {context}` for one raised through errors.raise_error.
+ */
+function describeConstructionError(error) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const { code, message, context } = error;
+    const head = [code, message].filter((part) => typeof part === 'string' && part).join(': ');
+    const hasContext = Boolean(context && typeof context === 'object' && Object.keys(context).length);
+    const tail = hasContext ? JSON.stringify(context) : '';
+    return [head, tail].filter(Boolean).join(' ') || null;
+}
+/**
+ * Why a construction failed, from its `error` column. That column came with
+ * the queued build, and the modules SDK predates it, so it is read on its own
+ * after a failure: the status reads stay valid on a backend without it. The
+ * SDK's select type doesn't list `error`, but the ORM writes each select key
+ * as the field name.
+ */
+async function readConstructionFailure(modules, constructionId) {
+    try {
+        const result = await modules.blueprintConstruction
+            .findOne({ id: constructionId, select: { error: true } })
+            .unwrap();
+        const row = result.blueprintConstruction;
+        return describeConstructionError(row?.error) ?? 'the backend gave no reason';
+    }
+    catch (err) {
+        return `the backend gave no reason (reading it failed: ${errorText(err)})`;
+    }
+}
+/**
+ * Wait for a construction to finish. Resolves with its table map once it is
+ * constructed, and throws with the backend's coded error once it failed, or
+ * when the deadline passes, the signal aborts, or its status can't be read.
+ */
+async function waitForConstruction(modules, constructionId, options = {}) {
+    const { signal, deadlineMs = exports.CONSTRUCTION_DEADLINE_MS, pollMs = exports.CONSTRUCTION_POLL_MS, now = Date.now, sleep = abortableSleep, } = options;
+    const deadline = now() + deadlineMs;
+    let status = 'pending';
+    let readFailures = 0;
+    for (;;) {
+        if (signal?.aborted)
+            throw stopped();
+        let row;
+        try {
+            const result = await modules.blueprintConstruction
+                .findOne({ id: constructionId, select: { status: true, tableMap: true } })
+                .unwrap();
+            row = result.blueprintConstruction;
+            readFailures = 0;
+        }
+        catch (err) {
+            // A GraphQL error is the backend's answer and won't change on a reread.
+            if (!(0, request_database_1.isTransientProvisionError)(err) || ++readFailures >= exports.MAX_CONSECUTIVE_READ_FAILURES) {
+                throw new Error(`Could not read the blueprint build's status: ${errorText(err)}. ${MAY_STILL_FINISH}`);
+            }
+        }
+        if (row === null)
+            throw new Error(`The backend has no blueprint construction ${constructionId}.`);
+        if (row?.status === 'constructed')
+            return tableMapOf(row.tableMap);
+        if (row?.status === 'failed') {
+            throw new Error(`The blueprint build failed: ${await readConstructionFailure(modules, constructionId)}`);
+        }
+        status = row?.status ?? status;
+        if (now() >= deadline) {
+            const where = status === 'pending' ? "waiting in the backend's build queue" : 'building';
+            throw new Error(`The blueprint build was still ${where} after ${Math.round(deadlineMs / 1000)} s. ${MAY_STILL_FINISH}`);
+        }
+        await sleep(pollMs, signal);
+    }
+}
+/**
+ * A build that failed after the backend queued it, or that the wait gave up
+ * on. The construction carries on without the caller, so constructing again
+ * would queue the same tables a second time.
+ */
+class BlueprintBuildError extends Error {
+    constructionId;
+    constructor(message, constructionId) {
+        super(message);
+        this.name = 'BlueprintBuildError';
+        this.constructionId = constructionId;
+    }
+}
+exports.BlueprintBuildError = BlueprintBuildError;
+/**
+ * Construct a blueprint into a schema and wait for the build. Resolves with
+ * the construction and the created tables. Once the backend has queued the
+ * build, every failure is a BlueprintBuildError with its construction id.
+ */
+async function buildBlueprint(modules, input, options = {}) {
+    const result = await modules.mutation
+        .constructBlueprint({ input }, { select: { result: true } })
+        .unwrap();
+    const constructionId = result.constructBlueprint?.result;
+    if (!constructionId)
+        throw new Error('constructBlueprint returned no construction id');
+    try {
+        return { constructionId, tables: await waitForConstruction(modules, constructionId, options) };
+    }
+    catch (err) {
+        throw new BlueprintBuildError(errorText(err), constructionId);
+    }
+}

package/context.d.ts

@@ -1,4 +1,5 @@
 import { api, modules } from '@constructive-io/sdk';
+import { type UnreachableCause } from './db-probe';
 export type ApiClient = ReturnType<typeof api.createClient>;
 export type ModulesClient = ReturnType<typeof modules.createClient>;
 export type ProjectContext = {
@@ -12,12 +13,15 @@ export type ProjectContext = {
     databaseName: string;
     accessToken: string;
     dataEndpoint: string;
+    hash?: string;
 };
-export type ProjectContextFailureCode = 'no-env' | 'missing-credentials' | 'db-missing' | 'account-mismatch' | 'backend-unreachable' | 'schema-unresolved';
+export type ProjectContextFailureCode = 'no-env' | 'missing-credentials' | 'db-missing' | 'db-suspended' | 'account-mismatch' | 'backend-unreachable' | 'schema-unresolved';
 export type ResolveResult = {
     context: ProjectContext | null;
     reason: string;
     code?: ProjectContextFailureCode;
+    /** Why the backend couldn't answer, with code 'backend-unreachable'. */
+    cause?: UnreachableCause;
 };
 export declare const CONTEXT_ENV_KEYS: readonly ["ACCESS_TOKEN", "DATABASE_ID", "API_ENDPOINT", "MODULES_ENDPOINT", "DATABASE_NAME", "OWNER_ID"];
 export type ContextEnvKey = (typeof CONTEXT_ENV_KEYS)[number];

package/context.js

@@ -119,17 +119,18 @@ async function resolveProjectContext(input, options = {}) {
         databaseId,
         signInHint: host.signInHint,
     });
-    if (probe.outcome === 'unreachable') {
+    if (probe.status === 'unreachable') {
         return {
             context: null,
-            reason: `Could not reach the Constructive backend at ${controlApiEndpoint} (${probe.detail}). Check it is running, then retry.`,
+            reason: unreachableReason(controlApiEndpoint, probe.cause, probe.detail),
             code: 'backend-unreachable',
+            cause: probe.cause,
         };
     }
-    if (probe.outcome === 'missing') {
+    if (probe.status === 'missing') {
         return {
             context: null,
-            reason: `The bound database (DATABASE_ID=${databaseId}) no longer exists on this backend. Re-provision with provision_database (reprovision: true) — the schema is rebuilt from the project; records do not carry over.`,
+            reason: `The bound database (DATABASE_ID=${databaseId}) no longer exists on this backend, or this account lost access to it. ${(0, host_1.reprovisionAdvice)(host)}`,
             code: 'db-missing',
         };
     }
@@ -146,10 +147,20 @@ async function resolveProjectContext(input, options = {}) {
         probe.ownerId !== sessionUserId) {
         return {
             context: null,
-            reason: `The bound database (DATABASE_ID=${databaseId}) was provisioned under a different account than the one signed in. Re-provision with provision_database (reprovision: true) to rebuild it under this account — the schema is rebuilt from the project; records do not carry over.`,
+            reason: `The bound database (DATABASE_ID=${databaseId}) was provisioned under a different account than the one signed in. ${(0, host_1.reprovisionAdvice)(host)}`,
             code: 'account-mismatch',
         };
     }
+    // A suspended database still holds its data, so it is never a reason to
+    // reprovision: nothing can read or change it until the hold is lifted.
+    if (probe.status === 'suspended') {
+        const why = probe.suspendedReason ? ` (${probe.suspendedReason})` : '';
+        return {
+            context: null,
+            reason: `The bound database (DATABASE_ID=${databaseId}) is suspended${why} since ${probe.suspendedAt}. Its data is kept, but nothing can read or change it until the suspension is lifted.`,
+            code: 'db-suspended',
+        };
+    }
     const databaseName = env.DATABASE_NAME || probe.name || '';
     const ownerId = probe.ownerId || env.OWNER_ID || undefined;
     const dataEndpoint = databaseName
@@ -172,10 +183,24 @@ async function resolveProjectContext(input, options = {}) {
             databaseName,
             accessToken,
             dataEndpoint,
+            hash: probe.hash,
         },
         reason: '',
     };
 }
+function unreachableReason(endpoint, cause, detail) {
+    switch (cause) {
+        case 'auth':
+            // The probe's detail says the credential was rejected and how to sign in.
+            return `Could not check the bound database on the Constructive backend at ${endpoint}: ${detail}`;
+        case 'error':
+            return `The Constructive backend at ${endpoint} answered with an error while checking the bound database (${detail}). Retry; if it keeps failing, check the backend's logs.`;
+        case 'server':
+            return `The Constructive backend at ${endpoint} is failing (${detail}). Check it is running, then retry.`;
+        default:
+            return `Could not reach the Constructive backend at ${endpoint} (${detail}). Check it is running, then retry.`;
+    }
+}
 const needsAuthReason = () => `Not signed in to the app database yet. ${(0, host_1.getHost)().signInHint ??
     'Sign in from the Sheets tab, or open the Preview and sign in to your app, then try again.'}`;
 // Resolve a data-plane token for record operations: serve the broker's active

package/db-probe.d.ts

@@ -1,30 +1,38 @@
+import { postGraphQL } from './graphql-http';
+export type UnreachableCause = 'network' | 'server' | 'auth' | 'error';
 export type DatabaseProbe = {
-    outcome: 'found';
+    status: 'found';
+    databaseId: string;
+    name?: string;
+    ownerId?: string;
+    hash?: string;
+} | {
+    status: 'suspended';
+    databaseId: string;
     name?: string;
     ownerId?: string;
+    hash?: string;
+    suspendedAt: string;
+    suspendedReason?: string;
 } | {
-    outcome: 'missing';
+    status: 'missing';
+    databaseId: string;
 } | {
-    outcome: 'unreachable';
+    status: 'unreachable';
+    databaseId: string;
+    cause: UnreachableCause;
     detail: string;
 };
-export type ProbeExecutor = {
-    execute<T>(document: string, variables?: Record<string, unknown>): Promise<{
-        ok: true;
-        data: T;
-        errors: undefined;
-    } | {
-        ok: false;
-        data: null;
-        errors: {
-            message: string;
-        }[];
-    }>;
-};
 export declare function probeDatabase(args: {
     endpoint: string;
     bearer: string;
     databaseId: string;
-    executor?: ProbeExecutor;
     signInHint?: string;
+    post?: typeof postGraphQL;
 }): Promise<DatabaseProbe>;
+/**
+ * Probe a database with the host's account bearer on its configured control
+ * endpoint (never a project-pinned one). Without a bearer the answer is
+ * unreachable with cause 'auth'.
+ */
+export declare function probeBoundDatabase(databaseId: string): Promise<DatabaseProbe>;