@caelo-cms/provisioning 0.11.1 → 0.11.3

package/dist/agent-db.js

@@ -6509,6 +6509,98 @@ function decodeEscapedLineBreaks(value, language) {
 ${"\t".repeat(tabs.length / 2)}`);
 }
 
+// ../shared/src/lists/default-types.ts
+var DEFAULT_LIST_TYPES = [
+  {
+    slug: "texts",
+    name: "Texts",
+    purpose: "A flat list of short texts inside one module: feature bullets, chips, steps.",
+    role: "content",
+    root: { allow: ["text"] },
+    nodes: {
+      text: {
+        label: "Text",
+        fields: [{ name: "text", label: "Text", type: "text", required: true }]
+      }
+    }
+  },
+  {
+    slug: "links",
+    name: "Links",
+    purpose: "A flat group of links: legal links, social links, a footer column.",
+    role: "content",
+    root: { allow: ["link"] },
+    nodes: {
+      link: {
+        label: "Link",
+        fields: [
+          { name: "label", label: "Label", type: "text", required: true },
+          { name: "link", label: "Link", type: "link", required: true }
+        ],
+        current_from: "link"
+      }
+    }
+  },
+  {
+    slug: "menu",
+    name: "Menu",
+    purpose: "Site navigation with up to three levels: header menu, footer menu, mobile menu. Use a custom type for mega menus with columns or teasers.",
+    role: "navigation",
+    root: { allow: ["entry"] },
+    nodes: {
+      entry: {
+        label: "Menu entry",
+        fields: [
+          { name: "label", label: "Label", type: "text", required: true },
+          { name: "link", label: "Link", type: "link" }
+        ],
+        children: { name: "children", allow: ["entry"] },
+        current_from: "link"
+      }
+    },
+    max_depth: 3
+  },
+  {
+    slug: "categories",
+    name: "Categories",
+    purpose: "A category tree pages are assigned to: blog sections, product groups, doc areas.",
+    role: "vocabulary",
+    root: { allow: ["category"] },
+    nodes: {
+      category: {
+        label: "Category",
+        fields: [
+          { name: "name", label: "Name", type: "text", required: true },
+          { name: "slug", label: "Slug", type: "text", required: true },
+          { name: "description", label: "Description", type: "richtext" },
+          { name: "landing_page", label: "Landing page", type: "link" }
+        ],
+        children: { name: "children", allow: ["category"] },
+        current_from: "landing_page"
+      }
+    },
+    max_depth: 6
+  },
+  {
+    slug: "tags",
+    name: "Tags",
+    purpose: "Flat keywords pages are tagged with, for filters, tag clouds and related content.",
+    role: "vocabulary",
+    root: { allow: ["tag"] },
+    nodes: {
+      tag: {
+        label: "Tag",
+        fields: [
+          { name: "name", label: "Name", type: "text", required: true },
+          { name: "slug", label: "Slug", type: "text", required: true },
+          { name: "color", label: "Color", type: "text", maxLength: 9 }
+        ]
+      }
+    }
+  }
+];
+var SITE_TEXTS_LIST_TYPE = "site-texts";
+
 // ../shared/src/lists/fields.ts
 var LIST_RESERVED_NAMES = new Set([
   "id",
@@ -6769,11 +6861,14 @@ var moduleFieldModuleListSchema = object({
   min: number2().int().nonnegative().optional(),
   max: number2().int().positive().max(256).optional()
 }).strict();
+var SHIPPED_LIST_TYPE_SLUGS = [...DEFAULT_LIST_TYPES.map((t) => t.slug), SITE_TEXTS_LIST_TYPE].map((slug) => `"${slug}"`).join(", ");
 var moduleFieldListSchema = object({
   name: moduleFieldName,
   kind: literal("list"),
   label: moduleFieldLabel,
-  listType: slugSchema,
+  listType: string2({
+    error: (iss) => iss.input === undefined ? `a list field needs listType: ${SHIPPED_LIST_TYPE_SLUGS} or a custom type's slug (list_list_types shows them)` : undefined
+  }).regex(/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/, "slug must be lowercase letters, digits, or hyphens (1\u201364 chars, no leading/trailing hyphen)"),
   bind: _enum(["local", "shared", "source"]).optional(),
   list: string2().regex(LIST_REF_RE, "list must be caelo:list/<id>").optional(),
   source: sourceDefSchema.optional(),
@@ -6968,8 +7063,9 @@ var pageSetModulesSchema = object({
   expectedVersion: number2().int().nonnegative().optional(),
   blocks: array(object({
     blockName: slugSchema,
-    moduleIds: array(string2().uuid())
-  }).strict())
+    moduleIds: array(string2().uuid()),
+    contentInstanceIds: array(string2().uuid().nullable()).optional()
+  }).strict().refine((b) => b.contentInstanceIds === undefined || b.contentInstanceIds.length === b.moduleIds.length, { message: "contentInstanceIds needs one entry (or null) per moduleIds entry" }))
 }).strict();
 var syncModeSchema = _enum(["synced", "unsynced"]);
 var contentValuesSchema = record(string2(), unknown());
@@ -7382,6 +7478,8 @@ var movePositionInputSchema = preprocess(stripSurroundingQuotes, union([
 var moveModuleToolInput = object({
   pageId: string2().uuid(),
   moduleId: string2().uuid(),
+  fromBlockName: string2().min(1).max(80).optional(),
+  fromPosition: preprocess((v) => typeof v === "string" && /^\d+$/.test(v) ? Number.parseInt(v, 10) : v, number2().int().min(0).max(1000).optional()),
   toBlockName: string2().min(1).max(80).optional(),
   position: movePositionInputSchema
 }).strict();
@@ -7588,20 +7686,42 @@ var bugIntakeRegisterRequest = object({
   publicKey: string2().regex(/^[A-Za-z0-9+/]{43}=$/, "publicKey must be a base64 Ed25519 key"),
   caeloVersion: string2().min(1).max(64)
 }).strict();
+var bugReportKind = _enum(["defect", "suggestion"]);
+var BUG_REPORT_KIND_BEFORE_1192 = "defect";
+var bugReportSeverity = _enum(["blocking", "degraded", "cosmetic"]);
 var bugIntakeReport = object({
   protocolVersion: literal(BUG_INTAKE_PROTOCOL_VERSION),
   reportId: string2().uuid(),
   caeloVersion: string2().min(1).max(64),
   fingerprint: fingerprintSchema,
   source: _enum(["ai", "auto"]),
-  severity: _enum(["blocking", "degraded", "cosmetic"]),
+  kind: bugReportKind.default(BUG_REPORT_KIND_BEFORE_1192),
+  severity: bugReportSeverity.nullable(),
   blockedTask: boolean2(),
   suspectedTool: string2().max(200).nullable(),
   title: string2().min(1).max(BUG_INTAKE_LIMITS.title),
   whatHappened: string2().min(1).max(BUG_INTAKE_LIMITS.whatHappened),
   expected: string2().min(1).max(BUG_INTAKE_LIMITS.expected),
   evidence: string2().max(BUG_INTAKE_LIMITS.evidence).nullable()
-}).strict();
+}).strict().superRefine((r, ctx) => {
+  if (r.kind === "defect" && r.severity === null) {
+    ctx.addIssue({ code: "custom", path: ["severity"], message: "a defect needs a severity" });
+  }
+  if (r.kind === "suggestion" && r.severity !== null) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["severity"],
+      message: "a suggestion has no severity; send null"
+    });
+  }
+  if (r.kind === "suggestion" && r.source === "auto") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["kind"],
+      message: "an auto-captured report is always a defect"
+    });
+  }
+});
 var bugClusterStatus = _enum(["open", "fixed", "regression", "wontfix"]);
 var bugIntakeClusterInfo = object({
   clusterId: string2().min(1).max(100),
@@ -7758,7 +7878,7 @@ var buildPageTargetSchema = object({
     if (createKeys.length > 0) {
       ctx.addIssue({
         code: ZodIssueCode.custom,
-        message: `pageId targets an EXISTING page \u2014 drop ${createKeys.join(", ")}. ` + "To create a new page instead, omit pageId and pass slug + title."
+        message: `pageId targets an EXISTING page \u2014 drop ${createKeys.join(", ")}. ` + (createKeys.includes("status") ? "`status` only applies to a page this call creates; publish an existing page with set_pages_status_many. " : "") + "To create a new page instead, omit pageId and pass slug + title."
       });
     }
     return;
@@ -8926,6 +9046,16 @@ var PAGE_PROP_RE = new RegExp(`^page/(${SEG2})/props/(${SEG2})$`);
 var LIST_HIDDEN_RE = new RegExp(`^list/(${SEG2})/item/(${SEG2})$`);
 var INSTANCE_HIDDEN_RE = new RegExp(`^instance/(${SEG2})/(${SEG2})/item/(${SEG2})$`);
 var STRUCTURAL_TYPES = new Set(["module", "term"]);
+// ../shared/src/live-events.ts
+var LIVE_TOPICS = [
+  "agents",
+  "pending",
+  "credentials",
+  "quality",
+  "crawl",
+  "deploys"
+];
+var TOPIC_SET = new Set(LIVE_TOPICS);
 // ../shared/src/markup-structure.ts
 var LEAF_TAGS = new Set(["svg", "math", "script", "style", "noscript", "iframe"]);
 // ../shared/src/page-log.ts
@@ -18539,6 +18669,40 @@ function isRlsDenial(error) {
   return false;
 }
 
+// ../query-api/src/operation.ts
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+function isReadOperation(op) {
+  return "kind" in op && op.kind === "reads";
+}
+var OP_COVERAGE_FILE_DEFAULT = "coverage/op-coverage.jsonl";
+var recordedNames = new Set;
+var coverageDirEnsured = false;
+function recordOpInvocation(name) {
+  if (recordedNames.has(name))
+    return;
+  recordedNames.add(name);
+  const file = process.env.CAELO_OP_COVERAGE_FILE ?? OP_COVERAGE_FILE_DEFAULT;
+  if (!coverageDirEnsured) {
+    mkdirSync(dirname(file), { recursive: true });
+    coverageDirEnsured = true;
+  }
+  appendFileSync(file, `${name}
+`, { flag: "a" });
+}
+function defineOperation(def) {
+  if (process.env.CAELO_OP_COVERAGE !== "1")
+    return def;
+  const original = def.handler;
+  return {
+    ...def,
+    handler: (ctx, input, tx) => {
+      recordOpInvocation(def.name);
+      return original(ctx, input, tx);
+    }
+  };
+}
+
 // ../query-api/src/plugin-schema-provision.ts
 import { createHash } from "crypto";
 var DROPPED_COLUMNS_SETTING = "caelo.plugin_dropped_columns";
@@ -18577,6 +18741,119 @@ async function provisionPluginSchemaInTx(tx, caller, opts) {
   };
 }
 
+// ../query-api/src/pool-guard.ts
+import { AsyncLocalStorage } from "async_hooks";
+var POOL_ACQUIRE_TIMEOUT_MS = 1e4;
+var ALLOWLIST = [
+  { holder: "deploy.promote", issue: 1225, nestedCheckouts: true, noSessionTimeouts: true },
+  {
+    holder: "quality_audits.publish_anyway",
+    issue: 1225,
+    nestedCheckouts: true,
+    noSessionTimeouts: true
+  },
+  {
+    holder: "quality_audits.execute_proposal",
+    issue: 1225,
+    nestedCheckouts: true,
+    noSessionTimeouts: true
+  },
+  {
+    holder: "deploy.execute_proposal",
+    issue: 1225,
+    nestedCheckouts: true,
+    noSessionTimeouts: true
+  },
+  {
+    holder: "deploy.build_plugin_data",
+    issue: 1220,
+    nestedCheckouts: true,
+    noSessionTimeouts: true
+  },
+  {
+    holder: "plugins.activation_lock",
+    issue: 1220,
+    nestedCheckouts: true,
+    noSessionTimeouts: false
+  },
+  { holder: "static-generator.build", issue: 1220, nestedCheckouts: true, noSessionTimeouts: true },
+  { holder: "plugins.render_hook", issue: 1220, nestedCheckouts: true, noSessionTimeouts: false }
+];
+var NESTED_CHECKOUT_ALLOWLIST = new Map(ALLOWLIST.map((entry) => [entry.holder, entry]));
+
+class NestedPoolCheckoutError extends Error {
+  pool;
+  holder;
+  requester;
+  name = "NestedPoolCheckoutError";
+  constructor(pool, holder, requester) {
+    super(`${requester} asked the ${pool} database pool for a second connection while ${holder} holds a transaction of that pool in the same call chain. ` + "Enough of these at once deadlock the whole pool (issue #1210), so it is refused. Nothing of this call ran. " + `Fix in the code: pass ${holder}'s transaction to the inner work (op.handler(ctx, input, tx)) or move the inner work out of the transaction (transaction: "none").`);
+    this.pool = pool;
+    this.holder = holder;
+    this.requester = requester;
+  }
+}
+
+class PoolAcquireTimeoutError extends Error {
+  pool;
+  requester;
+  timeoutMs;
+  name = "PoolAcquireTimeoutError";
+  constructor(pool, requester, timeoutMs) {
+    super(`the ${pool} database pool had no free connection for ${requester} within ${timeoutMs} ms: every connection is busy. ` + "Nothing was changed. Retry in a few seconds; if it keeps happening the admin is overloaded or a request holds its connections \u2014 the server log names it.");
+    this.pool = pool;
+    this.requester = requester;
+    this.timeoutMs = timeoutMs;
+  }
+}
+var allowances = new AsyncLocalStorage;
+class PoolGuard {
+  #stores = {
+    admin: new AsyncLocalStorage,
+    public: new AsyncLocalStorage
+  };
+  enter(pool, holder) {
+    const allowedBy = this.assertMayCheckout(pool, holder);
+    return { holder, active: true, allowedBy };
+  }
+  assertMayCheckout(pool, requester) {
+    const outer = this.#stores[pool].getStore();
+    if (outer === undefined || !outer.active)
+      return null;
+    const allowedBy = outer.allowedBy ?? (NESTED_CHECKOUT_ALLOWLIST.get(outer.holder)?.nestedCheckouts ? outer.holder : null) ?? allowances.getStore() ?? null;
+    if (allowedBy === null)
+      throw new NestedPoolCheckoutError(pool, outer.holder, requester);
+    return allowedBy;
+  }
+  async run(pool, marker, fn) {
+    try {
+      return await this.#stores[pool].run(marker, fn);
+    } finally {
+      marker.active = false;
+    }
+  }
+}
+function exemptFromSessionTimeouts(holder) {
+  return NESTED_CHECKOUT_ALLOWLIST.get(holder)?.noSessionTimeouts === true;
+}
+async function liftSessionTimeouts(tx) {
+  await tx.execute(sql`SELECT set_config('statement_timeout', '0', true)`);
+  await tx.execute(sql`SELECT set_config('lock_timeout', '0', true)`);
+  await tx.execute(sql`SELECT set_config('idle_in_transaction_session_timeout', '0', true)`);
+}
+function detachedRunner(operation, open) {
+  const transaction = (fn) => open(fn);
+  return new Proxy({}, {
+    get(_target, property) {
+      if (property === "transaction")
+        return transaction;
+      if (property === "then")
+        return;
+      throw new Error(`${operation} is a detached operation (transaction: "none") and holds no transaction; it used tx.${String(property)}. Wrap the step in tx.transaction(async (t) => \u2026) or run it as its own operation.`);
+    }
+  });
+}
+
 // ../query-api/src/post-commit.ts
 var pendingByTx = new WeakMap;
 function collectPostCommitEffects(tx) {
@@ -18598,6 +18875,16 @@ async function runPostCommitEffects(effects) {
   }
   return failures;
 }
+var committedListeners = new Set;
+function notifyOperationCommitted(operationName) {
+  for (const listener of committedListeners) {
+    try {
+      listener(operationName);
+    } catch (thrown) {
+      console.error(`[query-api] committed-operation listener failed for ${operationName}`, thrown);
+    }
+  }
+}
 
 // ../query-api/src/adapter.ts
 var SQL3 = globalThis.Bun?.SQL;
@@ -18674,8 +18961,12 @@ class DatabaseAdapter {
   #publicRaw;
   #skipVerify;
   #roles;
+  #acquireTimeoutMs;
+  #guard = new PoolGuard;
   #verifyPromise = null;
   #projectionPublisher = null;
+  #onStatement;
+  #drizzleOptions;
   constructor(config) {
     this.#roles = config.expectedRoles ?? DEFAULT_ROLES;
     if (config.adminDatabaseUrl === null !== (this.#roles.admin === null)) {
@@ -18687,9 +18978,47 @@ class DatabaseAdapter {
     const open = (url) => new SQL3(url, poolMax === undefined ? { idleTimeout } : { max: poolMax, idleTimeout });
     this.#adminRaw = config.adminDatabaseUrl === null ? null : open(config.adminDatabaseUrl);
     this.#publicRaw = open(config.publicDatabaseUrl);
-    this.#admin = this.#adminRaw === null ? null : drizzle(this.#adminRaw);
-    this.#public = drizzle(this.#publicRaw);
+    this.#onStatement = config.onStatement ?? null;
+    const observe = this.#onStatement;
+    this.#drizzleOptions = observe ? { logger: { logQuery: (query) => observe(query) } } : {};
+    this.#admin = this.#adminRaw === null ? null : drizzle(this.#adminRaw, this.#drizzleOptions);
+    this.#public = drizzle(this.#publicRaw, this.#drizzleOptions);
     this.#skipVerify = config.skipRoleVerification === true;
+    this.#acquireTimeoutMs = config.poolAcquireTimeoutMs ?? POOL_ACQUIRE_TIMEOUT_MS;
+  }
+  async#transaction(pool, holder, fn) {
+    const raw = pool === "admin" ? this.#adminRaw : this.#publicRaw;
+    if (raw === null)
+      throw new AdminDatabaseUnavailableError(holder);
+    const marker = this.#guard.enter(pool, holder);
+    const reserved = await this.#reserve(pool, raw, holder);
+    try {
+      const db = drizzle({ client: reserved, ...this.#drizzleOptions });
+      this.#onStatement?.("BEGIN");
+      const out = await db.transaction((tx) => this.#guard.run(pool, marker, async () => {
+        if (exemptFromSessionTimeouts(holder))
+          await liftSessionTimeouts(tx);
+        return fn(tx);
+      }));
+      this.#onStatement?.("COMMIT");
+      return out;
+    } finally {
+      reserved.release();
+    }
+  }
+  async#reserve(pool, raw, requester) {
+    const deadline = new AbortController;
+    const timer = setTimeout(() => deadline.abort(), this.#acquireTimeoutMs);
+    try {
+      return await raw.reserve({ signal: deadline.signal });
+    } catch (e) {
+      if (deadline.signal.aborted) {
+        throw new PoolAcquireTimeoutError(pool, requester, this.#acquireTimeoutMs);
+      }
+      throw e;
+    } finally {
+      clearTimeout(timer);
+    }
   }
   get hasAdminDatabase() {
     return this.#admin !== null;
@@ -18777,15 +19106,22 @@ class DatabaseAdapter {
     return row;
   }
   async runOperation(op, ctx, validatedInput) {
+    const pool = op.database === "cms_admin" ? "admin" : "public";
+    this.#guard.assertMayCheckout(pool, op.name);
+    if (op.database === "cms_admin")
+      this.#adminDb(`operation ${op.name}`);
     if (!this.#skipVerify)
       await this.verifyRoles();
-    const db = op.database === "cms_admin" ? this.#adminDb(`operation ${op.name}`) : this.#public;
+    if (isReadOperation(op))
+      return this.#runReadOperation(op, ctx, validatedInput);
+    if (op.transaction === "none")
+      return this.#runDetached(op, ctx, validatedInput);
     let publishAfterCommit = false;
     let postCommit = [];
     let result;
     let handlerError = null;
     try {
-      result = await db.transaction(async (tx) => {
+      result = await this.#transaction(pool, op.name, async (tx) => {
         postCommit = collectPostCommitEffects(tx);
         await this.#setIdentity(tx, ctx);
         if (op.database === "cms_admin") {
@@ -18802,6 +19138,8 @@ class DatabaseAdapter {
         return out;
       });
     } catch (thrown) {
+      if (thrown instanceof NestedPoolCheckoutError)
+        throw thrown;
       if (thrown instanceof OperationAbortError) {
         return err(thrown.queryError);
       }
@@ -18832,6 +19170,8 @@ class DatabaseAdapter {
         publishFailure = `The change is saved, but the public site does not serve it yet: publishing it failed (${thrown instanceof Error ? thrown.message : String(thrown)}). Do not repeat the change; it is published automatically within seconds once the public database answers.`;
       }
     }
+    if (result.ok)
+      notifyOperationCommitted(op.name);
     if (effectFailures.length > 0) {
       const effects = postCommitFailureMessage(effectFailures);
       return err({
@@ -18845,12 +19185,80 @@ class DatabaseAdapter {
     }
     return result;
   }
+  async#runDetached(op, ctx, validatedInput) {
+    try {
+      const branches = op.database === "cms_admin" ? namedBranches(ctx, validatedInput) : [];
+      if (branches.length > 0) {
+        const denied = await this.#transaction("admin", op.name, async (tx) => {
+          await this.#setIdentity(tx, ctx);
+          return firstInvisibleBranch(tx, branches);
+        });
+        if (denied !== null)
+          return err(branchNotFound(op.name, denied));
+      }
+      const options = { holder: op.name };
+      const runner = detachedRunner(op.name, (fn) => op.database === "cms_admin" ? this.withAdminTransaction(ctx, fn, options) : this.withPublicTransaction(ctx, fn, options));
+      return await op.handler(ctx, validatedInput, runner);
+    } catch (thrown) {
+      if (thrown instanceof NestedPoolCheckoutError)
+        throw thrown;
+      if (thrown instanceof OperationAbortError)
+        return err(thrown.queryError);
+      const pgDetail = extractPgFields(thrown);
+      return err({
+        kind: "HandlerError",
+        operation: op.name,
+        message: thrown instanceof Error ? thrown.message : String(thrown),
+        ...pgDetail ? { pgDetail } : {}
+      });
+    }
+  }
   async#setIdentity(tx, ctx) {
-    await tx.execute(sql`SELECT set_config('caelo.actor_id', ${ctx.actorId}, true)`);
-    await tx.execute(sql`SELECT set_config('caelo.actor_kind', ${ctx.actorKind}, true)`);
-    await tx.execute(sql`SELECT set_config('caelo.plugin_id', ${ctx.pluginId ?? ""}, true)`);
-    await tx.execute(sql`SELECT set_config('caelo.chat_branch_id', ${ctx.chatBranchId ?? ""}, true)`);
-    await tx.execute(sql`SELECT set_config('caelo.chat_task_id', ${ctx.chatTaskId ?? ""}, true)`);
+    await tx.execute(sql`SELECT
+      set_config('caelo.actor_id', ${ctx.actorId}, true),
+      set_config('caelo.actor_kind', ${ctx.actorKind}, true),
+      set_config('caelo.plugin_id', ${ctx.pluginId ?? ""}, true),
+      set_config('caelo.chat_branch_id', ${ctx.chatBranchId ?? ""}, true),
+      set_config('caelo.chat_task_id', ${ctx.chatTaskId ?? ""}, true)`);
+  }
+  async#runReadOperation(op, ctx, validatedInput) {
+    try {
+      const branches = namedBranches(ctx, validatedInput);
+      if (branches.length > 0) {
+        const denied = await this.#shortRead(ctx, op.name, (tx) => firstInvisibleBranch(tx, branches));
+        if (denied !== null)
+          return err(branchNotFound(op.name, denied));
+      }
+      return await op.handler(ctx, validatedInput, this.readScope(ctx, op.name));
+    } catch (thrown) {
+      if (thrown instanceof NestedPoolCheckoutError)
+        throw thrown;
+      if (thrown instanceof OperationAbortError)
+        return err(thrown.queryError);
+      if (isRlsDenial(thrown)) {
+        return err({
+          kind: "RLSDenied",
+          operation: op.name,
+          detail: thrown.message ?? "RLS policy denied the read"
+        });
+      }
+      const pgDetail = extractPgFields(thrown);
+      return err({
+        kind: "HandlerError",
+        operation: op.name,
+        message: thrown instanceof Error ? thrown.message : String(thrown),
+        ...pgDetail ? { pgDetail } : {}
+      });
+    }
+  }
+  readScope(ctx, holder = "reads.read") {
+    return { read: (fn) => this.#shortRead(ctx, holder, fn) };
+  }
+  #shortRead(ctx, holder, fn) {
+    return this.#transaction("admin", holder, async (tx) => {
+      await this.#setIdentity(tx, ctx);
+      return fn(tx);
+    });
   }
   async#settlePostCommit(operation, ctx, effects) {
     if (effects.length === 0)
@@ -18866,7 +19274,7 @@ class DatabaseAdapter {
       if (this.#admin === null)
         continue;
       try {
-        await this.#admin.transaction(async (tx) => {
+        await this.#transaction("admin", `${operation}.post_commit`, async (tx) => {
           await this.#setIdentity(tx, ctx);
           await recordAudit(tx, {
             actorId: ctx.actorId,
@@ -18891,13 +19299,15 @@ class DatabaseAdapter {
   async close() {
     await Promise.all([this.#adminRaw?.end(), this.#publicRaw.end()]);
   }
-  async withAdminTransaction(ctx, fn) {
-    const admin = this.#adminDb("withAdminTransaction");
+  async withAdminTransaction(ctx, fn, options = {}) {
+    const holder = options.holder ?? "withAdminTransaction";
+    this.#guard.assertMayCheckout("admin", holder);
+    this.#adminDb(holder);
     if (!this.#skipVerify)
       await this.verifyRoles();
     let publishAfterCommit = false;
     let postCommit = [];
-    const out = await admin.transaction(async (tx) => {
+    const out = await this.#transaction("admin", holder, async (tx) => {
       postCommit = collectPostCommitEffects(tx);
       await this.#setIdentity(tx, ctx);
       const denied = await firstInvisibleBranch(tx, namedBranches(ctx, undefined));
@@ -18908,25 +19318,27 @@ class DatabaseAdapter {
       publishAfterCommit = await this.#projectionDirty(tx);
       return result;
     });
-    const effectFailures = await this.#settlePostCommit("withAdminTransaction", ctx, postCommit);
+    const effectFailures = await this.#settlePostCommit(holder, ctx, postCommit);
     if (publishAfterCommit)
       await this.#publishAfterCommit();
     if (effectFailures.length > 0)
       throw new Error(postCommitFailureMessage(effectFailures));
     return out;
   }
-  async withPublicTransaction(ctx, fn) {
+  async withPublicTransaction(ctx, fn, options = {}) {
+    const holder = options.holder ?? "withPublicTransaction";
+    this.#guard.assertMayCheckout("public", holder);
     if (!this.#skipVerify)
       await this.verifyRoles();
     let postCommit = [];
-    const out = await this.#public.transaction(async (tx) => {
+    const out = await this.#transaction("public", holder, async (tx) => {
       postCommit = collectPostCommitEffects(tx);
       await tx.execute(sql`SELECT set_config('caelo.actor_id', ${ctx.actorId}, true)`);
       await tx.execute(sql`SELECT set_config('caelo.actor_kind', ${ctx.actorKind}, true)`);
       await tx.execute(sql`SELECT set_config('caelo.plugin_id', ${ctx.pluginId ?? ""}, true)`);
       return await fn(tx);
     });
-    const effectFailures = await this.#settlePostCommit("withPublicTransaction", ctx, postCommit);
+    const effectFailures = await this.#settlePostCommit(holder, ctx, postCommit);
     if (effectFailures.length > 0)
       throw new Error(postCommitFailureMessage(effectFailures));
     return out;
@@ -18934,9 +19346,11 @@ class DatabaseAdapter {
   rawAdmin() {
     if (this.#adminRaw === null)
       throw new AdminDatabaseUnavailableError("rawAdmin");
+    this.#guard.assertMayCheckout("admin", "rawAdmin()");
     return this.#adminRaw;
   }
   rawPublic() {
+    this.#guard.assertMayCheckout("public", "rawPublic()");
     return this.#publicRaw;
   }
   async provisionPluginPublicSchema(opts) {
@@ -18945,12 +19359,11 @@ class DatabaseAdapter {
     }
     if (!this.#skipVerify)
       await this.verifyRoles();
-    const outcome = await this.#public.transaction(async (tx) => {
+    const outcome = await this.#transaction("public", "provisionPluginPublicSchema", async (tx) => {
       return provisionPluginSchemaInTx(tx, "provisionPluginPublicSchema", opts);
     });
     if (outcome.droppedColumns.length > 0) {
-      const admin = this.#adminDb("provisionPluginPublicSchema");
-      await admin.transaction(async (tx) => {
+      await this.#transaction("admin", "provisionPluginPublicSchema", async (tx) => {
         await tx.execute(sql.raw("SELECT set_config('caelo.actor_kind', 'system', true)"));
         await auditDroppedColumns(tx, "cms_public", opts.pluginId, outcome);
       });
@@ -18960,10 +19373,10 @@ class DatabaseAdapter {
     if (!/^[0-9a-f-]{36}$/i.test(opts.pluginId)) {
       throw new Error(`provisionPluginAdminSchema: pluginId "${opts.pluginId}" is not a UUID`);
     }
-    const admin = this.#adminDb("provisionPluginAdminSchema");
+    this.#adminDb("provisionPluginAdminSchema");
     if (!this.#skipVerify)
       await this.verifyRoles();
-    await admin.transaction(async (tx) => {
+    await this.#transaction("admin", "provisionPluginAdminSchema", async (tx) => {
       const outcome = await provisionPluginSchemaInTx(tx, "provisionPluginAdminSchema", opts);
       if (outcome.droppedColumns.length > 0) {
         await auditDroppedColumns(tx, "cms_admin", opts.pluginId, outcome);
@@ -18971,13 +19384,13 @@ class DatabaseAdapter {
     });
   }
   async dropPluginAdminSchema(opts) {
-    const admin = this.#adminDb("dropPluginAdminSchema");
+    this.#adminDb("dropPluginAdminSchema");
     if (!this.#skipVerify)
       await this.verifyRoles();
     if (!/^plugin_[a-z][a-z0-9_]*$/.test(opts.schemaName)) {
       throw new Error(`dropPluginAdminSchema: refusing to drop schema "${opts.schemaName}" \u2014 name doesn't match plugin_<slug> pattern`);
     }
-    await admin.transaction(async (tx) => {
+    await this.#transaction("admin", "dropPluginAdminSchema", async (tx) => {
       await tx.execute(sql.raw("SELECT set_config('caelo.actor_kind', 'system', true)"));
       await tx.execute(sql.raw(`DROP SCHEMA IF EXISTS "${opts.schemaName}" CASCADE`));
       await tx.execute(sql`DELETE FROM plugin_schema_provisions WHERE schema_name = ${opts.schemaName}`);
@@ -18989,16 +19402,19 @@ class DatabaseAdapter {
     if (!/^plugin_[a-z][a-z0-9_]*$/.test(opts.schemaName)) {
       throw new Error(`dropPluginPublicSchema: refusing to drop schema "${opts.schemaName}" \u2014 name doesn't match plugin_<slug> pattern`);
     }
-    await this.#public.transaction(async (tx) => {
+    await this.#transaction("public", "dropPluginPublicSchema", async (tx) => {
       await tx.execute(sql.raw("SELECT set_config('caelo.actor_kind', 'system', true)"));
       await tx.execute(sql.raw(`DROP SCHEMA IF EXISTS "${opts.schemaName}" CASCADE`));
       await tx.execute(sql`DELETE FROM plugin_schema_provisions WHERE schema_name = ${opts.schemaName}`);
     });
   }
   get admin() {
-    return this.#adminDb("admin pool");
+    const db = this.#adminDb("admin pool");
+    this.#guard.assertMayCheckout("admin", "adapter.admin");
+    return db;
   }
   get public() {
+    this.#guard.assertMayCheckout("public", "adapter.public");
     return this.#public;
   }
 }
@@ -19041,37 +19457,17 @@ async function execute(registry, adapter, ctx, name, rawInput, options = {}) {
   if (!parsed.success) {
     return err({ kind: "ValidationFailed", issues: parsed.error.issues });
   }
-  return adapter.runOperation(op, ctx, parsed.data);
-}
-// ../query-api/src/operation.ts
-import { appendFileSync, mkdirSync } from "fs";
-import { dirname } from "path";
-var OP_COVERAGE_FILE_DEFAULT = "coverage/op-coverage.jsonl";
-var recordedNames = new Set;
-var coverageDirEnsured = false;
-function recordOpInvocation(name) {
-  if (recordedNames.has(name))
-    return;
-  recordedNames.add(name);
-  const file = process.env.CAELO_OP_COVERAGE_FILE ?? OP_COVERAGE_FILE_DEFAULT;
-  if (!coverageDirEnsured) {
-    mkdirSync(dirname(file), { recursive: true });
-    coverageDirEnsured = true;
+  if (!isReadOperation(op) && op.stepwise) {
+    const result = await op.stepwise(ctx, parsed.data, {
+      registry,
+      adapter,
+      ...options.signal ? { signal: options.signal } : {}
+    });
+    if (result.ok)
+      notifyOperationCommitted(op.name);
+    return result;
   }
-  appendFileSync(file, `${name}
-`, { flag: "a" });
-}
-function defineOperation(def) {
-  if (process.env.CAELO_OP_COVERAGE !== "1")
-    return def;
-  const original = def.handler;
-  return {
-    ...def,
-    handler: (ctx, input, tx) => {
-      recordOpInvocation(def.name);
-      return original(ctx, input, tx);
-    }
-  };
+  return adapter.runOperation(op, ctx, parsed.data);
 }
 // ../query-api/src/registry.ts
 class OperationRegistry {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/provisioning",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "private": false,
   "license": "MPL-2.0",
   "description": "Pulumi-driven provisioning for Caelo CMS — `bunx @caelo-cms/provisioning --provider <self-hosted|gcp|aws|azure>` brings up a TLS-served install with Postgres + storage + secrets manager + the admin + the API gateway.",
@@ -40,7 +40,7 @@
     "prepublishOnly": "tsc -b --force && bun build ../platform-updater/src/agent-db.ts --target=bun --outfile=dist/agent-db.js && tsc --project stacks/gcp/tsconfig.json && tsc --project stacks/gcp-firebase/tsconfig.json"
   },
   "dependencies": {
-    "@caelo-cms/shared": "^0.11.1",
+    "@caelo-cms/shared": "^0.11.3",
     "@clack/prompts": "1.8.1",
     "@pulumi/command": "^1",
     "@pulumi/gcp": "^10",