@opengeni/db 1.0.1 → 3.2.0-canary.0

package/src/interaction-placement-loss.ts

@@ -0,0 +1,234 @@
+import { and, eq, inArray, sql } from "drizzle-orm";
+import { type Database, withRlsContext } from "./database";
+import {
+  advanceWorkspaceInteractionRevision,
+  readWorkspaceInteractionRevision,
+} from "./interaction-revisions";
+import * as schema from "./schema";
+
+export const SOURCE_PLACEMENT_CHANGED = "source_placement_changed";
+
+const CONNECTED_PLACEMENT_LIVE_LIFECYCLES = [
+  "starting",
+  "active",
+  "suspending",
+  "restoring",
+  "ending",
+] as const;
+
+export type TerminalizeStaleConnectedInteractionPlacementResult = {
+  sourcePlacementChanged: boolean;
+  changed: boolean;
+  browserSessionIds: string[];
+  computerSessionIds: string[];
+  revision: number;
+};
+
+/**
+ * Reconcile interaction resources after their source task moves away from a
+ * Connected Machine. The source row is the race fence: a stale route lookup
+ * may never retire resources while that machine is still the active placement.
+ * Browser and Desktop resources are settled together because headed browsers
+ * can share one physical controller with a linked Desktop.
+ */
+export async function terminalizeStaleConnectedInteractionPlacement(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sourceSessionId: string;
+    connectedSandboxId: string;
+  },
+): Promise<TerminalizeStaleConnectedInteractionPlacementResult> {
+  return await withRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (scopedDb) =>
+      await scopedDb.transaction(async (tx) => {
+        const [source] = await tx
+          .select({ activeSandboxId: schema.sessions.activeSandboxId })
+          .from(schema.sessions)
+          .where(
+            and(
+              eq(schema.sessions.accountId, input.accountId),
+              eq(schema.sessions.workspaceId, input.workspaceId),
+              eq(schema.sessions.id, input.sourceSessionId),
+            ),
+          )
+          .for("update")
+          .limit(1);
+
+        const sourcePlacementChanged =
+          source !== undefined && source.activeSandboxId !== input.connectedSandboxId;
+        if (!sourcePlacementChanged) {
+          return {
+            sourcePlacementChanged: false,
+            changed: false,
+            browserSessionIds: [],
+            computerSessionIds: [],
+            revision: await readWorkspaceInteractionRevision(tx, input.workspaceId),
+          };
+        }
+
+        const browserRows = await tx
+          .select({ id: schema.browserSessions.id })
+          .from(schema.browserSessions)
+          .innerJoin(
+            schema.browserSessionAssociations,
+            and(
+              eq(schema.browserSessionAssociations.browserSessionId, schema.browserSessions.id),
+              eq(schema.browserSessionAssociations.workspaceId, input.workspaceId),
+              eq(schema.browserSessionAssociations.sessionId, input.sourceSessionId),
+              eq(schema.browserSessionAssociations.relationship, "created"),
+            ),
+          )
+          .where(
+            and(
+              eq(schema.browserSessions.accountId, input.accountId),
+              eq(schema.browserSessions.workspaceId, input.workspaceId),
+              eq(schema.browserSessions.placementKind, "connected_machine"),
+              eq(schema.browserSessions.connectedSandboxId, input.connectedSandboxId),
+              inArray(schema.browserSessions.lifecycle, [...CONNECTED_PLACEMENT_LIVE_LIFECYCLES]),
+            ),
+          );
+        const computerRows = await tx
+          .select({ id: schema.computerSessions.id })
+          .from(schema.computerSessions)
+          .innerJoin(
+            schema.computerSessionAssociations,
+            and(
+              eq(schema.computerSessionAssociations.computerSessionId, schema.computerSessions.id),
+              eq(schema.computerSessionAssociations.workspaceId, input.workspaceId),
+              eq(schema.computerSessionAssociations.sessionId, input.sourceSessionId),
+              eq(schema.computerSessionAssociations.relationship, "created"),
+            ),
+          )
+          .where(
+            and(
+              eq(schema.computerSessions.accountId, input.accountId),
+              eq(schema.computerSessions.workspaceId, input.workspaceId),
+              eq(schema.computerSessions.placementKind, "connected_machine"),
+              eq(schema.computerSessions.connectedSandboxId, input.connectedSandboxId),
+              inArray(schema.computerSessions.lifecycle, [...CONNECTED_PLACEMENT_LIVE_LIFECYCLES]),
+            ),
+          );
+
+        const browserSessionIds = [...new Set(browserRows.map((row) => row.id))].sort();
+        const computerSessionIds = [...new Set(computerRows.map((row) => row.id))].sort();
+        const resourceIds = [...browserSessionIds, ...computerSessionIds];
+        if (resourceIds.length === 0) {
+          return {
+            sourcePlacementChanged: true,
+            changed: false,
+            browserSessionIds,
+            computerSessionIds,
+            revision: await readWorkspaceInteractionRevision(tx, input.workspaceId),
+          };
+        }
+
+        const operationRows = await tx
+          .select({ operationId: schema.interactionOperations.operationId })
+          .from(schema.interactionOperations)
+          .where(
+            and(
+              eq(schema.interactionOperations.accountId, input.accountId),
+              eq(schema.interactionOperations.workspaceId, input.workspaceId),
+              inArray(schema.interactionOperations.resourceId, resourceIds),
+              inArray(schema.interactionOperations.state, ["prepared", "dispatched"]),
+            ),
+          );
+        const operationIds = operationRows.map((row) => row.operationId).sort();
+
+        // Stable lock order matches the attached-device generation-loss path.
+        for (const operationId of operationIds) {
+          await tx.execute(sql`
+            select operation_id from interaction_operations
+            where workspace_id = ${input.workspaceId} and operation_id = ${operationId}
+            for update
+          `);
+        }
+        for (const browserSessionId of browserSessionIds) {
+          await tx.execute(sql`
+            select id from browser_sessions
+            where workspace_id = ${input.workspaceId} and id = ${browserSessionId}
+            for update
+          `);
+        }
+        for (const computerSessionId of computerSessionIds) {
+          await tx.execute(sql`
+            select id from computer_sessions
+            where workspace_id = ${input.workspaceId} and id = ${computerSessionId}
+            for update
+          `);
+        }
+
+        const now = new Date();
+        if (operationIds.length > 0) {
+          await tx
+            .update(schema.interactionOperations)
+            .set({
+              state: "outcome_unknown",
+              errorCode: "outcome_unknown",
+              errorMessage: "The source task moved to another placement",
+              errorRetryable: false,
+              errorDetails: { reason: SOURCE_PLACEMENT_CHANGED },
+              settledAt: now,
+              updatedAt: now,
+            })
+            .where(
+              and(
+                eq(schema.interactionOperations.workspaceId, input.workspaceId),
+                inArray(schema.interactionOperations.operationId, operationIds),
+                inArray(schema.interactionOperations.state, ["prepared", "dispatched"]),
+              ),
+            );
+        }
+        if (browserSessionIds.length > 0) {
+          await tx
+            .update(schema.browserSessions)
+            .set({
+              lifecycle: "lost",
+              failureCode: SOURCE_PLACEMENT_CHANGED,
+              updatedAt: now,
+            })
+            .where(
+              and(
+                eq(schema.browserSessions.workspaceId, input.workspaceId),
+                inArray(schema.browserSessions.id, browserSessionIds),
+                inArray(schema.browserSessions.lifecycle, [...CONNECTED_PLACEMENT_LIVE_LIFECYCLES]),
+              ),
+            );
+        }
+        if (computerSessionIds.length > 0) {
+          await tx
+            .update(schema.computerSessions)
+            .set({
+              lifecycle: "lost",
+              failureCode: SOURCE_PLACEMENT_CHANGED,
+              updatedAt: now,
+            })
+            .where(
+              and(
+                eq(schema.computerSessions.workspaceId, input.workspaceId),
+                inArray(schema.computerSessions.id, computerSessionIds),
+                inArray(schema.computerSessions.lifecycle, [
+                  ...CONNECTED_PLACEMENT_LIVE_LIFECYCLES,
+                ]),
+              ),
+            );
+        }
+        const revision = await advanceWorkspaceInteractionRevision(
+          tx,
+          input.accountId,
+          input.workspaceId,
+        );
+        return {
+          sourcePlacementChanged: true,
+          changed: true,
+          browserSessionIds,
+          computerSessionIds,
+          revision,
+        };
+      }),
+  );
+}

package/src/managed-human-provisioning.ts

@@ -0,0 +1,116 @@
+import { and, eq, sql } from "drizzle-orm";
+import type { Database } from "./database";
+import { rawRows, setRlsContext } from "./database";
+import * as schema from "./schema";
+
+export type ManagedHumanPersonalWorkspaceProvisioning = {
+  organizationMembershipId: string;
+  personalWorkspaceId: string;
+};
+
+/**
+ * Converge the deterministic managed-human personal workspace, its inference
+ * control row, and the organization-membership anchor through the exact 0219
+ * `ensure_managed_human_personal_workspace` lifecycle seam.
+ *
+ * This is the single implementation of that preparation. The Better Auth
+ * managed-access hook and the operator membership backfill driver both call it,
+ * so neither owns a second copy of the deterministic personal-workspace
+ * identity. All authority - account binding, owner-membership proof, workspace
+ * identity, control-row validation, membership status - stays inside the
+ * SECURITY DEFINER seam, which fails closed; nothing here writes an
+ * organization-tenancy table directly.
+ *
+ * Must be called inside a transaction whose RLS context is already the exact
+ * account with no workspace. It restores that context before returning.
+ */
+export async function ensureManagedHumanPersonalWorkspace(
+  tx: Database,
+  input: { accountId: string; subjectId: string },
+): Promise<ManagedHumanPersonalWorkspaceProvisioning> {
+  const personalWorkspaceExternalSource = "opengeni:organization-membership";
+  const personalWorkspaceExternalId = `${input.accountId}:${input.subjectId}`;
+  let [personalWorkspace] = await tx
+    .select()
+    .from(schema.workspaces)
+    .where(
+      and(
+        eq(schema.workspaces.externalSource, personalWorkspaceExternalSource),
+        eq(schema.workspaces.externalId, personalWorkspaceExternalId),
+      ),
+    )
+    .limit(1);
+  if (!personalWorkspace) {
+    [personalWorkspace] = await tx
+      .insert(schema.workspaces)
+      .values({
+        accountId: input.accountId,
+        name: "Personal workspace",
+        slug: null,
+        externalSource: personalWorkspaceExternalSource,
+        externalId: personalWorkspaceExternalId,
+      })
+      .onConflictDoUpdate({
+        target: [schema.workspaces.externalSource, schema.workspaces.externalId],
+        set: { updatedAt: new Date() },
+      })
+      .returning();
+  }
+  if (!personalWorkspace) {
+    throw new Error("Failed to ensure personal workspace");
+  }
+  if (
+    personalWorkspace.accountId !== input.accountId ||
+    personalWorkspace.externalSource !== personalWorkspaceExternalSource ||
+    personalWorkspace.externalId !== personalWorkspaceExternalId
+  ) {
+    throw new Error("Managed personal workspace identity conflict");
+  }
+
+  await setRlsContext(tx, {
+    accountId: input.accountId,
+    workspaceId: personalWorkspace.id,
+  });
+  const [personalWorkspaceControl] = await tx
+    .select({ workspaceId: schema.workspaceInferenceControls.workspaceId })
+    .from(schema.workspaceInferenceControls)
+    .where(eq(schema.workspaceInferenceControls.workspaceId, personalWorkspace.id))
+    .limit(1);
+  if (!personalWorkspaceControl) {
+    await tx
+      .insert(schema.workspaceInferenceControls)
+      .values({
+        workspaceId: personalWorkspace.id,
+        accountId: input.accountId,
+      })
+      .onConflictDoNothing();
+  }
+  await setRlsContext(tx, {
+    accountId: input.accountId,
+    workspaceId: null,
+  });
+
+  const [provisionedMembership] = await rawRows<{
+    organization_membership_id: string;
+    personal_workspace_id: string;
+  }>(
+    tx,
+    sql`
+      select * from ensure_managed_human_personal_workspace(
+        ${input.accountId},
+        ${input.subjectId},
+        ${personalWorkspace.id}
+      )
+    `,
+  );
+  if (
+    !provisionedMembership ||
+    provisionedMembership.personal_workspace_id !== personalWorkspace.id
+  ) {
+    throw new Error("Managed organization membership provisioning did not converge");
+  }
+  return {
+    organizationMembershipId: provisionedMembership.organization_membership_id,
+    personalWorkspaceId: provisionedMembership.personal_workspace_id,
+  };
+}

package/src/memory-domain.ts

@@ -428,13 +428,7 @@ export const WORKSPACE_MEMORY_BLOCK_EMPTY = `## Workspace memory
 This workspace has shared long-lived memory, currently empty. Your context is lost when the session ends; memory is not. When you learn something durably useful — a preference, an environment fact, a procedure that worked, a decision and its reason — save it with memory_save (one crisp, self-contained fact per record). Never store secrets.`;
 
 export const MEMORY_SEARCH_TOOL_DESCRIPTION =
-  "Search this workspace's shared long-lived memory (semantic + keyword). Use it before starting a new non-trivial task when the injected notes or current conversation do not already answer how the workspace does something. Results persist in conversation context: do not repeat the same search as routine setup on every continuation, resume, or interrupted turn. Returns scored records with ids.";
-
-export const MEMORY_SAVE_TOOL_DESCRIPTION =
-  "Save one durable, future-useful fact to this workspace's shared memory: a stable preference, an environment fact, a procedure that worked, or a decision and its reason. Write it compactly (1–3 sentences), self-contained (no 'this session/above' references, absolute dates, name concrete things), so a future session can act on it alone. Do NOT save: session-specific state, speculation, anything derivable from the repo/docs, or near-duplicates of existing memories (search first — to refine or replace an existing record pass replaces_id). Most turns have nothing worth saving.";
-
-export const MEMORY_CORRECT_TOOL_DESCRIPTION =
-  "Flag a workspace memory as wrong or outdated the moment you discover it — this is the most valuable memory action, because a wrong memory misleads every future session. Pass the record's id (as shown in [brackets]); optionally give replacement_text with the corrected fact, otherwise the record is archived.";
+  "Search this workspace's shared long-lived memory (semantic + keyword). Use it before starting a new non-trivial task when the injected notes or current conversation do not already answer how the workspace does something. Results persist in conversation context: do not repeat the same search as routine setup on every continuation, resume, or interrupted turn. Returns scored records with ids. Indexed workspace documents are a separate store: search those with `knowledge_search`/`knowledge_get` (or `search_documents`) on the Document Search (docs) MCP server, not with this tool.";
 
 // ---------------------------------------------------------------------------
 // Text normalization + hashing (MUST match migration 0045 backfill exactly)
@@ -469,7 +463,7 @@ export function isMemoryTextTooLong(text: string): boolean {
 // ---------------------------------------------------------------------------
 
 export function estimateMemoryTokens(text: string): number {
-  return Math.ceil(text.length / 4);
+  return Math.ceil(Buffer.byteLength(text, "utf8") / 4);
 }
 
 // Short id shown in the block/tool output = first 8 chars of the uuid. Tools
@@ -491,46 +485,47 @@ export type MemoryBlockRecord = {
 // into kind sections. Episodic is excluded. Returns null if nothing renders
 // (no non-episodic records) — the caller substitutes the empty-state block.
 export function renderWorkspaceMemoryBlock(records: readonly MemoryBlockRecord[]): string | null {
-  const renderable = records.filter((record) => record.kind !== "episodic");
-  if (renderable.length === 0) {
+  if (!records.some((record) => record.kind !== "episodic")) {
     return null;
   }
+  const selected = selectWorkspaceMemoryBlockRecords(records);
+
+  const lines: string[] = [WORKSPACE_MEMORY_BLOCK_HEADER_POPULATED];
+  for (const kind of MEMORY_BLOCK_KIND_ORDER) {
+    const inSection = selected.filter((record) => record.kind === kind);
+    if (inSection.length === 0) {
+      continue;
+    }
+    lines.push("", `### ${MEMORY_KIND_SECTION_TITLES[kind]}`);
+    for (const record of inSection) {
+      lines.push(renderMemoryEntry(record));
+    }
+  }
+  return lines.join("\n");
+}
 
-  // Greedy budget fill in priority order. We track the running token estimate of
-  // the whole block (header + section titles introduced so far + entries).
+/** Canonical whole-entry prompt-budget selector, shared with receipt validation. */
+export function selectWorkspaceMemoryBlockRecords(
+  records: readonly MemoryBlockRecord[],
+): readonly MemoryBlockRecord[] {
+  const renderable = records.filter((record) => record.kind !== "episodic");
   const headerTokens = estimateMemoryTokens(WORKSPACE_MEMORY_BLOCK_HEADER_POPULATED);
   let usedTokens = headerTokens;
   const seenSections = new Set<KnowledgeMemoryKind>();
   const selected: MemoryBlockRecord[] = [];
   for (const record of renderable) {
     const entryLine = renderMemoryEntry(record);
-    let cost = estimateMemoryTokens(entryLine) + 1; // +1 for the entry's newline
+    let cost = estimateMemoryTokens(entryLine) + 1;
     if (!seenSections.has(record.kind)) {
       const sectionTitle = `### ${MEMORY_KIND_SECTION_TITLES[record.kind]}`;
-      cost += estimateMemoryTokens(sectionTitle) + 2; // title + blank line separator
-    }
-    if (usedTokens + cost > WORKSPACE_MEMORY_BLOCK_TOKEN_BUDGET) {
-      // Skip entries that don't fit instead of stopping: one oversized entry
-      // must not starve smaller lower-priority records of the remaining budget.
-      continue;
+      cost += estimateMemoryTokens(sectionTitle) + 2;
     }
+    if (usedTokens + cost > WORKSPACE_MEMORY_BLOCK_TOKEN_BUDGET) continue;
     usedTokens += cost;
     seenSections.add(record.kind);
     selected.push(record);
   }
-
-  const lines: string[] = [WORKSPACE_MEMORY_BLOCK_HEADER_POPULATED];
-  for (const kind of MEMORY_BLOCK_KIND_ORDER) {
-    const inSection = selected.filter((record) => record.kind === kind);
-    if (inSection.length === 0) {
-      continue;
-    }
-    lines.push("", `### ${MEMORY_KIND_SECTION_TITLES[kind]}`);
-    for (const record of inSection) {
-      lines.push(renderMemoryEntry(record));
-    }
-  }
-  return lines.join("\n");
+  return selected;
 }
 
 function renderMemoryEntry(record: MemoryBlockRecord): string {

package/src/migrate.ts

@@ -6,6 +6,12 @@ import postgres from "postgres";
 const DEFAULT_DATABASE_URL = "postgres://opengeni:opengeni@127.0.0.1:5432/opengeni";
 const DEFAULT_MAX_NESTED_AGENT_DEPTH = 3;
 const MAX_NESTED_AGENT_DEPTH = 2_147_483_647;
+const DEFAULT_APPLICATION_DATABASE_ROLE = "opengeni_app";
+const GOAL_REVISION_CUTOVER_MIGRATION = "0257_goal_revision_decisions_and_root_constraints.sql";
+const ATOMIC_PERSONAL_RESOURCE_CUTOVER_MIGRATION = "0306_atomic_personal_resource_attachments.sql";
+const UNREGISTERED_INVITATION_CUTOVER_MIGRATION = "0314_unregistered_organization_invitations.sql";
+const ATOMIC_CONNECTED_MACHINE_CUTOVER_MIGRATION = "0338_atomic_connected_machine_attachments.sql";
+const MAX_MIGRATION_APPLICATION_ROLES = 16;
 const batchedBackfillDirective =
   /^-- opengeni:batched-backfill batch-size=(\d+) lock-timeout=(\d+(?:ms|s|min)) statement-timeout=(\d+(?:ms|s|min))$/;
 const concurrentIndexDirective = /^-- opengeni:concurrent-index lock-timeout=(\d+(?:ms|s|min))$/;
@@ -30,6 +36,12 @@ export interface ConcurrentIndexMigration {
 
 export type MigrationRuntimeOptions = {
   maxNestedAgentDepth?: number;
+  /**
+   * Exact database login roles that may run an OpenGeni API or worker against
+   * this target. Maintenance cutovers use this list to reject a live mixed-
+   * version fleet. Dedicated-schema and custom-role deployments must supply it.
+   */
+  applicationDatabaseRoles?: string[];
 };
 
 type DeploymentDepthPolicy = {
@@ -230,6 +242,53 @@ function deploymentDepthPolicy(
   return { maxNestedAgentDepth: value, source: "deployment" };
 }
 
+function migrationApplicationRoles(
+  schema: string | undefined,
+  options: MigrationRuntimeOptions | undefined,
+): string[] {
+  const configured = options?.applicationDatabaseRoles;
+  const environment = process.env.OPENGENI_MIGRATION_APPLICATION_DATABASE_ROLES?.trim();
+  const explicit =
+    configured !== undefined
+      ? configured
+      : environment
+        ? environment.split(",").map((role) => role.trim())
+        : undefined;
+
+  if (!explicit) {
+    const configuredRuntimeRoles = [
+      process.env.OPENGENI_APP_DATABASE_USER?.trim(),
+      process.env.OPENGENI_RUNTIME_DATABASE_ROLE?.trim(),
+    ].filter((role): role is string => Boolean(role) && role !== DEFAULT_APPLICATION_DATABASE_ROLE);
+    if (schema || configuredRuntimeRoles.length > 0) {
+      throw new Error(
+        "Migration 0257 requires the exact application database roles via " +
+          "MigrationRuntimeOptions.applicationDatabaseRoles or " +
+          "OPENGENI_MIGRATION_APPLICATION_DATABASE_ROLES for dedicated-schema or custom-role deployments",
+      );
+    }
+    return [DEFAULT_APPLICATION_DATABASE_ROLE];
+  }
+
+  if (explicit.length < 1 || explicit.length > MAX_MIGRATION_APPLICATION_ROLES) {
+    throw new Error(
+      `Migration application database roles must contain 1-${MAX_MIGRATION_APPLICATION_ROLES} entries`,
+    );
+  }
+  const normalized = [...new Set(explicit)].sort((left, right) =>
+    Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8")),
+  );
+  if (
+    normalized.length !== explicit.length ||
+    normalized.some((role) => role.length === 0 || Buffer.byteLength(role, "utf8") > 63)
+  ) {
+    throw new Error(
+      "Migration application database roles must be unique, non-empty Postgres role names of at most 63 UTF-8 bytes",
+    );
+  }
+  return normalized;
+}
+
 async function persistDeploymentDepthPolicy(
   sql: postgres.Sql,
   policy: DeploymentDepthPolicy,
@@ -277,6 +336,9 @@ async function persistDeploymentDepthPolicy(
  *   2. `public` stays LAST on the path so `gen_random_uuid()` (pgcrypto) and the
  *      `vector` type — both installed into `public` by 0000 — still resolve. The
  *      `opengeni_private.*` helpers are always called with an absolute prefix.
+ * Dedicated-schema callers must also pass the exact API/worker database login
+ * identities in `applicationDatabaseRoles`; maintenance cutovers cannot infer
+ * host-managed or scoped runtime roles from the admin connection.
  *
  * `OPENGENI_DB_SCHEMA` defaults UNSET → `public` → standalone, so the default
  * binding never regresses.
@@ -312,6 +374,19 @@ export async function migrate(
     );
     const appliedRows = await sql`SELECT "name" FROM "schema_migrations"`;
     const applied = new Set(appliedRows.map((row) => row.name as string));
+    if (
+      !applied.has(GOAL_REVISION_CUTOVER_MIGRATION) ||
+      !applied.has(ATOMIC_PERSONAL_RESOURCE_CUTOVER_MIGRATION) ||
+      !applied.has(UNREGISTERED_INVITATION_CUTOVER_MIGRATION) ||
+      !applied.has(ATOMIC_CONNECTED_MACHINE_CUTOVER_MIGRATION)
+    ) {
+      const applicationRoles = migrationApplicationRoles(schema, runtimeOptions);
+      await sql`select set_config(
+        'opengeni.migration_application_roles',
+        ${JSON.stringify(applicationRoles)},
+        false
+      )`;
+    }
     for (const file of files) {
       if (applied.has(file)) {
         continue;
@@ -332,7 +407,8 @@ export async function migrate(
  * SDK entry point (Step I): run the migration chain over a host-supplied admin
  * connection string against an explicit target schema. This is the embedded
  * topology's named entry — a host calls `runMigrations(adminConnection,
- * targetSchema)` from its own provisioning code instead of relying on env vars.
+ * targetSchema, { applicationDatabaseRoles })` from its own provisioning code
+ * instead of relying on env vars.
  * `targetSchema` undefined → `public` → standalone behavior. Thin wrapper over
  * `migrate` so there is one migration engine.
  */