@abloatai/cli 0.47.0 → 0.49.0

package/dist/cli.cjs

@@ -2318,7 +2318,7 @@ function Subscribe(postgres2, options) {
         return;
       stream = null;
       state.pid = state.secret = void 0;
-      connected(await init2(sql, slot, options.publications));
+      connected(await init4(sql, slot, options.publications));
       subscribers.forEach((event) => event.forEach(({ onsubscribe }) => onsubscribe()));
     },
     no_subscribe: true
@@ -2337,7 +2337,7 @@ function Subscribe(postgres2, options) {
   async function subscribe(event, fn, onsubscribe = noop2, onerror = noop2) {
     event = parseEvent(event);
     if (!connection2)
-      connection2 = init2(sql, slot, options.publications);
+      connection2 = init4(sql, slot, options.publications);
     const subscriber = { fn, onsubscribe };
     const fns = subscribers.has(event) ? subscribers.get(event).add(subscriber) : subscribers.set(event, /* @__PURE__ */ new Set([subscriber])).get(event);
     const unsubscribe = () => {
@@ -2356,7 +2356,7 @@ function Subscribe(postgres2, options) {
     state.pid = x2.state.pid;
     state.secret = x2.state.secret;
   }
-  async function init2(sql2, slot2, publications) {
+  async function init4(sql2, slot2, publications) {
     if (!publications)
       throw new Error("Missing publication names");
     const xs = await sql2.unsafe(
@@ -3455,14 +3455,14 @@ function requireKey() {
   }
   return apiKey;
 }
-async function request(path, apiKey, init2 = {}, baseUrl2) {
+async function request(path, apiKey, init4 = {}, baseUrl2) {
   const res = await fetch(`${baseUrl2 ?? apiUrl()}${path}`, {
-    method: init2.method ?? "GET",
+    method: init4.method ?? "GET",
     headers: {
       "content-type": "application/json",
       authorization: `Bearer ${apiKey}`
     },
-    ...init2.body !== void 0 ? { body: JSON.stringify(init2.body) } : {}
+    ...init4.body !== void 0 ? { body: JSON.stringify(init4.body) } : {}
   });
   let body = {};
   try {
@@ -3825,6 +3825,153 @@ var init_terminalWidth = __esm({
   }
 });
 
+// src/observeCliError.ts
+function installCliExitObservationBoundary() {
+  if (exitBoundaryInstalled) return;
+  exitBoundaryInstalled = true;
+  process.exit = ((code) => {
+    const numericCode = code == null ? 0 : Number(code);
+    if (numericCode === 0) return nativeProcessExit(code);
+    throw new CliFailureExit(Number.isFinite(numericCode) ? numericCode : 1);
+  });
+}
+function restoreCliExitObservationBoundary() {
+  if (!exitBoundaryInstalled) return;
+  process.exit = nativeProcessExit;
+  exitBoundaryInstalled = false;
+}
+function init2() {
+  if (!dsn) return false;
+  if (!initialized) {
+    Sentry.init({
+      dsn,
+      environment: process.env.ABLO_STAGE ?? "local",
+      release,
+      sendDefaultPii: false,
+      enableLogs: true,
+      beforeSend(event) {
+        return (0, import_errorObservation.sanitizeObservationValue)(event);
+      },
+      beforeBreadcrumb(breadcrumb) {
+        return (0, import_errorObservation.sanitizeObservationValue)(breadcrumb);
+      }
+    });
+    initialized = true;
+  }
+  return true;
+}
+function commandOperation() {
+  const command = process.argv[2];
+  const subcommand = process.argv[3];
+  const safe = (value) => value && /^[a-z][a-z0-9-]*$/i.test(value) ? value : void 0;
+  return ["ablo", safe(command), safe(subcommand)].filter(Boolean).join(" ");
+}
+function detailString(details, ...keys) {
+  for (const key of keys) {
+    const value = details?.[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return void 0;
+}
+function observeCliError(err) {
+  const normalized = (0, import_errors5.toAbloError)(err);
+  const eventId = normalized.eventId ?? (dsn ? (0, import_node_crypto.randomUUID)().replaceAll("-", "") : void 0);
+  if (!eventId || !init2()) return normalized.eventId;
+  try {
+    const spec = normalized.code ? (0, import_errorCodes.errorCodeSpec)(normalized.code) : void 0;
+    const policy = spec?.observability ?? {
+      severity: "error",
+      sentry: "issue",
+      pagingEligible: false,
+      expectedVolume: "low",
+      owner: "product"
+    };
+    const details = normalized.details;
+    const organizationId = detailString(details, "organizationId", "organization_id");
+    const projectId = detailString(details, "projectId", "project_id");
+    const branchId = detailString(details, "branchId", "branch_id");
+    const dataSourceId = detailString(details, "dataSourceId", "data_source_id");
+    const model = detailString(details, "model", "modelName", "model_name");
+    const candidate = (0, import_errorObservation.sanitizeObservationValue)({
+      eventId,
+      occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+      service: "ablo-cli",
+      stage: process.env.ABLO_STAGE ?? "local",
+      ...release ? { release } : {},
+      severity: normalized.eventId ? "warning" : policy.severity,
+      channel: "cli",
+      scope: "command",
+      operation: commandOperation(),
+      errorCode: normalized.code ?? "internal_error",
+      errorType: normalized.type,
+      category: spec?.category ?? "client",
+      retryable: spec?.retryable ?? false,
+      handled: normalized.eventId !== void 0 || policy.sentry === "log",
+      publicMessage: normalized.message,
+      internalMessage: normalized.message,
+      ...normalized.stack ? { stack: normalized.stack } : {},
+      ...normalized.requestId ? { requestId: normalized.requestId } : {},
+      ...organizationId ? { organizationId } : {},
+      ...projectId ? { projectId } : {},
+      ...branchId ? { branchId } : {},
+      ...dataSourceId ? { dataSourceId } : {},
+      ...model ? { model } : {},
+      ...err instanceof CliFailureExit ? { diagnosticContext: { exitCode: err.exitCode } } : {}
+    });
+    const observation = import_errorObservation.errorObservationSchema.parse(candidate);
+    if (normalized.eventId || policy.sentry === "log") {
+      Sentry.logger.warn(observation.publicMessage, { ...observation });
+    } else {
+      Sentry.captureException(err, {
+        event_id: observation.eventId,
+        captureContext: {
+          level: observation.severity,
+          fingerprint: [observation.service, observation.operation, observation.errorCode],
+          tags: {
+            service: observation.service,
+            channel: observation.channel,
+            scope: observation.scope,
+            error_code: observation.errorCode
+          },
+          contexts: { ablo: { ...observation } }
+        }
+      });
+    }
+    return eventId;
+  } catch {
+    return normalized.eventId;
+  }
+}
+async function flushCliErrors(timeoutMs = 2e3) {
+  if (!initialized) return true;
+  return Sentry.flush(timeoutMs);
+}
+var import_node_crypto, Sentry, import_errorCodes, import_errorObservation, import_errors5, dsn, release, initialized, nativeProcessExit, exitBoundaryInstalled, CliFailureExit;
+var init_observeCliError = __esm({
+  "src/observeCliError.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_crypto = require("crypto");
+    Sentry = __toESM(require("@sentry/node"), 1);
+    import_errorCodes = require("@abloatai/transaction/errorCodes");
+    import_errorObservation = require("@abloatai/transaction/errorObservation");
+    import_errors5 = require("@abloatai/transaction/errors");
+    dsn = process.env.ABLO_CLI_SENTRY_DSN ?? "https://1ac154bff10b06836e1ea9de9e0d92f0@o4510928209772544.ingest.de.sentry.io/4511660691423312" ?? "";
+    release = process.env.ABLO_CLI_RELEASE ?? "@abloatai/cli@0.49.0";
+    initialized = false;
+    nativeProcessExit = process.exit.bind(process);
+    exitBoundaryInstalled = false;
+    CliFailureExit = class extends Error {
+      exitCode;
+      constructor(exitCode) {
+        super(`CLI command exited with status ${exitCode}`);
+        this.name = "CliFailureExit";
+        this.exitCode = exitCode;
+      }
+    };
+  }
+});
+
 // src/renderError.ts
 function titleForType(type) {
   const core = type.replace(/^Ablo/, "").replace(/Error$/, "");
@@ -3853,6 +4000,17 @@ function wrapParagraph(text, indent) {
 function renderKnownDetails(details, line) {
   if (!details) return;
   const { retryAfterSeconds, missingIds, requiredCapability, unexecutable, errors, target } = details;
+  if (details.topology === "localhost") {
+    const commands = isStringArray(details.recommended_commands) ? details.recommended_commands : ["ablo migrate", "ablo dev --local"];
+    line(`    ${import_picocolors4.default.dim("setup")}  ${commands.join("  \u2192  ")}`);
+    if (typeof details.mode === "string") line(`    ${import_picocolors4.default.dim("mode")}   ${details.mode}`);
+    if (typeof details.limitation === "string") {
+      line(`    ${import_picocolors4.default.dim("note")}   ${details.limitation}`);
+    }
+    if (isStringArray(details.alternatives)) {
+      line(`    ${import_picocolors4.default.dim("other")}  ${details.alternatives.join(" \xB7 ")}`);
+    }
+  }
   if (typeof target === "string") line(`    ${import_picocolors4.default.dim("tried")}  ${target}`);
   if (typeof retryAfterSeconds === "number") line(`    ${import_picocolors4.default.dim("retry")}  after ${retryAfterSeconds}s`);
   if (isStringArray(missingIds) && missingIds.length > 0) {
@@ -3876,17 +4034,18 @@ function renderKnownDetails(details, line) {
   }
 }
 function renderCliError(err, opts = {}) {
+  const observedEventId = observeCliError(err);
   const line = opts.write ?? ((l2) => {
     console.error(l2);
   });
   const verbose = opts.verbose ?? (process.argv.includes("--verbose") || process.env.ABLO_VERBOSE === "1");
   const json = opts.json ?? (process.argv.includes("--json") || process.env.ABLO_JSON === "1");
   if (json) {
-    line(JSON.stringify((0, import_errors5.toAbloError)(err).toJSON()));
+    line(JSON.stringify((0, import_errors6.toAbloError)(err).toJSON()));
     process.exitCode = 1;
     return;
   }
-  if (err instanceof import_errors5.AbloError) {
+  if (err instanceof import_errors6.AbloError) {
     const codeTag = err.code ? `  ${import_picocolors4.default.dim(`[${err.code}]`)}` : "";
     line("");
     line(`  ${brand("ablo")} ${import_picocolors4.default.red("\u2717")} ${import_picocolors4.default.bold(titleForType(err.type))}${codeTag}`);
@@ -3899,10 +4058,13 @@ function renderCliError(err, opts = {}) {
     const field = (s) => fields.push(s);
     if (err.param) field(`    ${import_picocolors4.default.dim("field")}  ${err.param}`);
     renderKnownDetails(err.details, field);
-    const hint = err.code ? RECOVERY_HINT[(0, import_errors5.classifyRecovery)(err.code)] : void 0;
+    const hint = err.code ? RECOVERY_HINT[(0, import_errors6.classifyRecovery)(err.code)] : void 0;
     if (hint) field(`    ${import_picocolors4.default.dim(hint)}`);
     if (err.docUrl) field(`    ${import_picocolors4.default.dim("docs")}   ${err.docUrl}`);
     if (err.requestId) field(`    ${import_picocolors4.default.dim("ref")}    ${err.requestId}`);
+    if (err.eventId ?? observedEventId) {
+      field(`    ${import_picocolors4.default.dim("event")}  ${err.eventId ?? observedEventId}`);
+    }
     if (fields.length > 0) {
       line("");
       for (const f of fields) line(f);
@@ -3925,15 +4087,16 @@ function renderCliError(err, opts = {}) {
   line("");
   process.exitCode = 1;
 }
-var import_picocolors4, import_errors5, RECOVERY_HINT;
+var import_picocolors4, import_errors6, RECOVERY_HINT;
 var init_renderError = __esm({
   "src/renderError.ts"() {
     "use strict";
     init_cjs_shims();
     import_picocolors4 = __toESM(require_picocolors(), 1);
-    import_errors5 = require("@abloatai/transaction/errors");
+    import_errors6 = require("@abloatai/transaction/errors");
     init_terminalWidth();
     init_theme();
+    init_observeCliError();
     RECOVERY_HINT = {
       transient: "This looks transient \u2014 retry in a moment.",
       permission: "Your key isn't allowed to do this \u2014 check its scopes or role.",
@@ -4030,7 +4193,7 @@ function parsePushArgs(argv) {
         const spec = argv[++i] ?? "";
         const [from, to] = spec.split(":");
         if (!from || !to) {
-          throw new import_errors6.AbloValidationError(`--rename expects "old:new", got "${spec}"`, { code: "cli_invalid_arguments" });
+          throw new import_errors7.AbloValidationError(`--rename expects "old:new", got "${spec}"`, { code: "cli_invalid_arguments" });
         }
         renames.push({ from, to });
         break;
@@ -4044,13 +4207,13 @@ function parsePushArgs(argv) {
         const modelName = dot === -1 ? "" : path.slice(0, dot);
         const fieldName = dot === -1 ? "" : path.slice(dot + 1);
         if (!modelName || !fieldName || eq === -1) {
-          throw new import_errors6.AbloValidationError(`--backfill expects "model.field=value", got "${spec}"`, { code: "cli_invalid_arguments" });
+          throw new import_errors7.AbloValidationError(`--backfill expects "model.field=value", got "${spec}"`, { code: "cli_invalid_arguments" });
         }
         backfills.push({ model: modelName, field: fieldName, value: coerceBackfill(rawValue) });
         break;
       }
       default:
-        throw new import_errors6.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        throw new import_errors7.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
   url = url.replace(/\/+$/, "");
@@ -4078,7 +4241,7 @@ function publicationGap(value) {
 async function loadSchema(schemaPath, exportName) {
   const abs = (0, import_path3.resolve)(process.cwd(), schemaPath);
   if (!(0, import_fs4.existsSync)(abs)) {
-    throw new import_errors6.AbloValidationError(
+    throw new import_errors7.AbloValidationError(
       `schema not found at ${import_picocolors5.default.bold(schemaPath)}. Run ${import_picocolors5.default.bold("npx ablo init")} or pass ${import_picocolors5.default.bold("--schema <path>")}.`,
       { code: "cli_invalid_arguments" }
     );
@@ -4089,7 +4252,7 @@ async function loadSchema(schemaPath, exportName) {
   const nested = mod.default && typeof mod.default === "object" ? mod.default : void 0;
   const schema = mod[exportName] ?? nested?.[exportName];
   if (!schema || typeof schema !== "object" || !("models" in schema)) {
-    throw new import_errors6.AbloValidationError(
+    throw new import_errors7.AbloValidationError(
       `${import_picocolors5.default.bold(schemaPath)} has no \`${exportName}\` export that looks like a Schema. Did you \`export const ${exportName} = defineSchema({ ... })\`?`,
       { code: "cli_invalid_arguments" }
     );
@@ -4099,9 +4262,11 @@ async function loadSchema(schemaPath, exportName) {
 function maskKey(key) {
   return key ? `${key.slice(0, 12)}\u2026` : "(none)";
 }
-function schemaPushPlaneHint(code) {
-  if (code !== "test_database_not_registered") return null;
-  return `The key authenticated and already passed ${import_picocolors5.default.bold("schema:push")} authorization. This is a branch storage-provisioning error, not a key-scope error. Check the plane with ${import_picocolors5.default.bold("npx ablo branch status <branch>")}; a branch reported as hosted should not need a customer database.`;
+function schemaPushStorageHint(code) {
+  if (code === "no_data_source_registered") {
+    return `This branch is not connected to your database yet. Run ${import_picocolors5.default.bold("ablo connect")} for this branch, then retry the schema push.`;
+  }
+  return null;
 }
 function schemaGitState(schemaPath) {
   try {
@@ -4277,7 +4442,7 @@ async function push(argv) {
     try {
       process.loadEnvFile(args.envFile);
     } catch (error) {
-      throw new import_errors6.AbloValidationError(
+      throw new import_errors7.AbloValidationError(
         `could not load --env-file ${args.envFile}: ${error instanceof Error ? error.message : String(error)}`,
         { code: "cli_invalid_arguments" }
       );
@@ -4411,9 +4576,9 @@ async function push(argv) {
     const serverMsg = body.message ?? body.reason;
     console.error(import_picocolors5.default.red(`  Forbidden${code ? ` [${code}]` : ""}: ${serverMsg ?? "permission denied"}`));
     console.error(import_picocolors5.default.dim(`  Push used ${import_picocolors5.default.bold(maskKey(args.apiKey))} from ${describeKeySource(keySource)}.`));
-    const planeHint = schemaPushPlaneHint(code);
-    if (planeHint) {
-      console.error(import_picocolors5.default.dim(`  ${planeHint}`));
+    const storageHint = schemaPushStorageHint(code);
+    if (storageHint) {
+      console.error(import_picocolors5.default.dim(`  ${storageHint}`));
     } else if (code === "database_role_cannot_enforce_rls") {
       console.error(
         import_picocolors5.default.dim(
@@ -4452,17 +4617,17 @@ async function push(argv) {
       );
     }
   } else {
-    renderCliError((0, import_errors6.translateHttpError)(status2, Object.keys(body).length > 0 ? body : bodyText));
+    renderCliError((0, import_errors7.translateHttpError)(status2, Object.keys(body).length > 0 ? body : bodyText));
   }
   process.exit(1);
 }
-var import_picocolors5, import_errors6, import_credentialPolicy, import_fs4, import_path3, import_child_process, import_schema, import_schema2, DEFAULT_SCHEMA_PATH, DEFAULT_EXPORT, PUSH_USAGE;
+var import_picocolors5, import_errors7, import_credentialPolicy, import_fs4, import_path3, import_child_process, import_schema, import_schema2, DEFAULT_SCHEMA_PATH, DEFAULT_EXPORT, PUSH_USAGE;
 var init_push = __esm({
   "src/push.ts"() {
     "use strict";
     init_cjs_shims();
     import_picocolors5 = __toESM(require_picocolors(), 1);
-    import_errors6 = require("@abloatai/transaction/errors");
+    import_errors7 = require("@abloatai/transaction/errors");
     import_credentialPolicy = require("@abloatai/transaction/auth/credentialPolicy");
     import_fs4 = require("fs");
     import_path3 = require("path");
@@ -4702,7 +4867,7 @@ function connectSetupSql(input) {
   const writeRole = input.writeRole && input.writeRole.length > 0 ? input.writeRole : import_footprint.ABLO_WRITE_ROLE;
   const tables = input.tables ?? [];
   const schema = input.schema ?? "public";
-  const publication = input.publication ?? import_footprint.ABLO_PUBLICATION;
+  const publication = input.publication;
   const qualifiedTables = tables.map((table) => `${quoteIdent(schema)}.${quoteIdent(table)}`);
   const publicationTarget = tables.length > 0 ? `FOR TABLE ${qualifiedTables.join(", ")}` : "FOR ALL TABLES";
   const tableList = qualifiedTables.join(", ");
@@ -4780,8 +4945,8 @@ BEGIN
 END $$;`
   ];
 }
-function reconcilePublicationPlan(current, desiredTables, opts = {}) {
-  const pub = quoteIdent(opts.publication ?? import_footprint.ABLO_PUBLICATION);
+function reconcilePublicationPlan(current, desiredTables, opts) {
+  const pub = quoteIdent(opts.publication);
   const schema = opts.schema ?? "public";
   const qualified = (table) => `${quoteIdent(schema)}.${quoteIdent(table)}`;
   const desiredAll = desiredTables.length === 0;
@@ -4817,8 +4982,8 @@ function reconcilePublicationPlan(current, desiredTables, opts = {}) {
     recreated: false
   };
 }
-async function readPublicationState(sql, opts = {}) {
-  const publication = opts.publication ?? import_footprint.ABLO_PUBLICATION;
+async function readPublicationState(sql, opts) {
+  const publication = opts.publication;
   const schema = opts.schema ?? "public";
   const pubRows = await sql.unsafe(
     `SELECT puballtables FROM pg_publication WHERE pubname = $1`,
@@ -4833,8 +4998,8 @@ async function readPublicationState(sql, opts = {}) {
   );
   return { exists: true, allTables: false, tables: tableRows.map((r2) => r2.tablename) };
 }
-async function probeReadiness(sql, opts = {}) {
-  const publication = opts.publication ?? import_footprint.ABLO_PUBLICATION;
+async function probeReadiness(sql, opts) {
+  const publication = opts.publication;
   const schema = opts.schema ?? "public";
   const coordinated = opts.coordinatedTables && opts.coordinatedTables.length > 0 ? new Set(opts.coordinatedTables) : null;
   const items = [];
@@ -4981,6 +5146,18 @@ async function registerDirectDataSource(opts) {
         `  This deployment can\u2019t accept connection strings \u2014 use a self-hosted/hosted engine, or the signed endpoint fallback.`
       )
     );
+  } else if (err.code === "database_loopback_requires_connector") {
+    console.error(`
+  ${import_picocolors7.default.cyan("Recommended for this localhost-first project")}
+    1. ${import_picocolors7.default.bold("npx ablo migrate")} ${import_picocolors7.default.dim("(once: models + idempotency + outbox)")}
+    2. ${import_picocolors7.default.bold("npx ablo dev --local")} ${import_picocolors7.default.dim("(keep running beside the app)")}
+
+  ${import_picocolors7.default.dim("This keeps Postgres private and supports reads, coordinated writes, claims,")}
+  ${import_picocolors7.default.dim("subscriptions, and confirmations through the signed Data Source connector.")}
+  ${import_picocolors7.default.yellow("Note:")} ${import_picocolors7.default.dim("raw SQL or unrelated ORM writes are not automatically observed without WAL.")}
+
+  ${import_picocolors7.default.dim("If every arbitrary database write must be observed, use a secure database-capable")}
+  ${import_picocolors7.default.dim("tunnel, hosted direct Postgres, PrivateLink, peering, or VPN\u2014not a transaction pooler.")}`);
   } else if (err.code === "database_not_replication_ready" || err.code === "data_source_blocked") {
     for (const f of failures) {
       const { label, fix } = describeRemoteFailure(f);
@@ -5011,9 +5188,9 @@ async function registerDirectDataSource(opts) {
     }
     console.error(
       import_picocolors7.default.dim(
-        `  Ablo's servers must be able to reach this database \u2014 a localhost or private-network
-  Postgres can't use the direct path. Establish an allowlist, PrivateLink, peering, or VPN.
-  Only when no inbound route is possible, register the signed ${import_picocolors7.default.bold("dataSource()")} endpoint fallback.`
+        `  Ablo's servers must be able to reach this database for the direct WAL path.
+  For localhost development, run ${import_picocolors7.default.bold("ablo dev --local")}. For private deployments,
+  establish an allowlist, PrivateLink, peering, or VPN.`
       )
     );
   }
@@ -5075,9 +5252,9 @@ async function deregisterDataSource(opts) {
     });
     return { removed: true, response };
   } catch (err) {
-    if (err instanceof import_errors8.AbloError && err.code === "entity_not_found") return { removed: false };
-    if (err instanceof import_errors8.AbloError && err.code === "forbidden") {
-      throw new import_errors8.AbloPermissionError(
+    if (err instanceof import_errors9.AbloError && err.code === "entity_not_found") return { removed: false };
+    if (err instanceof import_errors9.AbloError && err.code === "forbidden") {
+      throw new import_errors9.AbloPermissionError(
         `${err.message}. Disconnecting needs a branch-bound secret key (sk_\u2026).`,
         {
           code: "forbidden",
@@ -5133,7 +5310,7 @@ async function disconnect(argv) {
       console.log(DISCONNECT_USAGE);
       return;
     } else {
-      throw new import_errors8.AbloValidationError(
+      throw new import_errors9.AbloValidationError(
         `unknown flag: ${arg} \u2014 see \`ablo connect deregister --help\``,
         { code: "cli_invalid_arguments" }
       );
@@ -5148,7 +5325,7 @@ async function disconnect(argv) {
     try {
       process.loadEnvFile(envFile);
     } catch (error) {
-      throw new import_errors8.AbloValidationError(
+      throw new import_errors9.AbloValidationError(
         `could not load --env-file ${envFile}: ${error instanceof Error ? error.message : String(error)}`,
         { code: "cli_invalid_arguments" }
       );
@@ -5156,7 +5333,7 @@ async function disconnect(argv) {
   }
   const selected = keyEnv ? readProjectEnvVariable(keyEnv) : null;
   if (keyEnv && !selected) {
-    throw new import_errors8.AbloAuthenticationError(
+    throw new import_errors9.AbloAuthenticationError(
       `No value named ${keyEnv} was found in the process environment, .env.local, or .env.`,
       { code: "cli_api_key_missing" }
     );
@@ -5168,7 +5345,7 @@ async function disconnect(argv) {
   const apiKey = resolved.key;
   const keySource = resolved.source ?? "stored";
   if (!apiKey) {
-    throw new import_errors8.AbloAuthenticationError(
+    throw new import_errors9.AbloAuthenticationError(
       "Disconnecting needs a branch-bound sk_ key. Set ABLO_API_KEY, pass `--env-file .env.local`, or select a named recovery key with `--key-env <NAME>`.",
       { code: "cli_api_key_missing" }
     );
@@ -5182,7 +5359,7 @@ async function disconnect(argv) {
 `);
   if (!skipConfirm) {
     if (!process.stdout.isTTY) {
-      throw new import_errors8.AbloValidationError(
+      throw new import_errors9.AbloValidationError(
         "This session has no terminal to confirm in. Re-run with --yes to disconnect non-interactively.",
         { code: "cli_invalid_arguments" }
       );
@@ -5205,14 +5382,14 @@ async function disconnect(argv) {
   }
   renderDisconnected(outcome.response, project, branchLabel);
 }
-var import_picocolors8, import_errors8, import_wire4, DISCONNECT_USAGE;
+var import_picocolors8, import_errors9, import_wire4, DISCONNECT_USAGE;
 var init_disconnect = __esm({
   "src/disconnect.ts"() {
     "use strict";
     init_cjs_shims();
     import_picocolors8 = __toESM(require_picocolors(), 1);
     init_dist2();
-    import_errors8 = require("@abloatai/transaction/errors");
+    import_errors9 = require("@abloatai/transaction/errors");
     import_wire4 = require("@abloatai/transaction/wire");
     init_config();
     init_dbRole();
@@ -5465,7 +5642,7 @@ function blockers(input) {
   }
   if (input.dataSource.kind === "none") {
     found.push({
-      problem: "no database is connected to this plane, so writes are held rather than routed",
+      problem: "no database is connected to this branch, so writes are held",
       fix: "connect one with `ablo connect apply`"
     });
   }
@@ -5517,7 +5694,7 @@ function connectApplyPlan(input) {
   const writeRole = input.writeRole && input.writeRole.length > 0 ? input.writeRole : import_footprint.ABLO_WRITE_ROLE;
   const tables = input.tables ?? [];
   const schema = input.schema ?? "public";
-  const publication = input.publication ?? import_footprint.ABLO_PUBLICATION;
+  const publication = input.publication;
   const provider = input.provider ?? "generic";
   const recipe = connectSetupSql({ tables, role, writeRole, schema, publication });
   const isWal = (s) => s.startsWith("ALTER SYSTEM SET wal_level");
@@ -5733,7 +5910,7 @@ function rotateWithoutConnection(input) {
   }
   if (!input.known || input.planeHasConnection) return null;
   if (input.existingRoles.length > 0) return null;
-  return "This plane has no connected database and Ablo's roles are not in this database, so there is no credential to re-key. Connecting for the first time is `ablo connect apply`, which creates the roles and registers them in one run.";
+  return "This branch has no connected database and Ablo's roles are not in this database, so there is no credential to re-key. Connecting for the first time is `ablo connect apply`, which creates the roles and registers them in one run.";
 }
 async function locateExistingConnection(input) {
   const result = await tryControlPlane({
@@ -5820,7 +5997,7 @@ async function runConnectApply(args) {
   const verb = rotating ? "connect rotate" : "connect apply";
   let adminUrl = args.url ?? readProjectAdminDatabaseUrl();
   if (!adminUrl) {
-    throw new import_errors9.AbloValidationError(
+    throw new import_errors10.AbloValidationError(
       "No admin connection string. Pass --url <admin-conn> (or set DATABASE_URL) and re-run.",
       { code: "cli_database_url_missing" }
     );
@@ -5837,7 +6014,7 @@ async function runConnectApply(args) {
     const loggedIn = resolveManagementKey() !== void 0;
     const ambient = ambientEnvKeyNote();
     const retry = `npx ablo connect ${rotating ? "rotate" : "apply"} --env-file .env.local --yes`;
-    throw new import_errors9.AbloAuthenticationError(
+    throw new import_errors10.AbloAuthenticationError(
       loggedIn ? `You are logged in, but connect needs a branch-bound runtime key.
 
 Logging in stores an mk_ management credential; it can manage branches but cannot read, write, or register a database. Set ABLO_API_KEY to the sk_ key for the exact branch this database should join. The server confirms whether that branch is the production root or a development child; the CLI does not infer it from the key spelling.${ambient ? `
@@ -5902,22 +6079,6 @@ ${ambient}` : ""}`,
 ` + import_picocolors11.default.dim(
         `    Replication cannot run over a pooler, so if that is what this is, point ${import_picocolors11.default.bold("--url")}
     at the database itself. Carrying on, since a database can use this port too.
-`
-      )
-    );
-  }
-  const coordinatedTables = await schemaDeclaredTables() ?? [];
-  const tables = args.tables.length > 0 ? args.tables : coordinatedTables;
-  if (tables.length === 0) {
-    throw new import_errors9.AbloValidationError(
-      `No mapped tables were found for schema ${args.schema}. Push the Ablo schema first, or pass --tables a,b,c. A project binding must enumerate its own schema-qualified tables; it cannot publish every table in a shared database.`,
-      { code: "cli_invalid_arguments" }
-    );
-  }
-  if (args.tables.length === 0) {
-    console.log(
-      import_picocolors11.default.dim(
-        `  publishing the ${tables.length} table${tables.length === 1 ? "" : "s"} declared by your Ablo schema in ${import_picocolors11.default.bold(args.schema)} (${import_picocolors11.default.bold("--tables")} to override)
 `
       )
     );
@@ -5934,7 +6095,7 @@ ${ambient}` : ""}`,
   }
   const confirmed = connectTarget?.confirmed;
   if (!confirmed?.branchId) {
-    throw new import_errors9.AbloConnectionError(
+    throw new import_errors10.AbloConnectionError(
       "Ablo could not confirm the branch this key targets, so it cannot derive an isolated database footprint safely. Check the API URL/key and re-run.",
       { code: "cli_database_unreachable" }
     );
@@ -5965,6 +6126,22 @@ ${ambient}` : ""}`,
     );
     process.exit(1);
   }
+  const coordinatedTables = await schemaDeclaredTables() ?? [];
+  const tables = args.tables.length > 0 ? args.tables : coordinatedTables;
+  if (tables.length === 0) {
+    throw new import_errors10.AbloValidationError(
+      `No mapped tables were found for schema ${args.schema}. Push the Ablo schema first, or pass --tables a,b,c. A project binding must enumerate its own schema-qualified tables; it cannot publish every table in a shared database.`,
+      { code: "cli_invalid_arguments" }
+    );
+  }
+  if (args.tables.length === 0) {
+    console.log(
+      import_picocolors11.default.dim(
+        `  publishing the ${tables.length} table${tables.length === 1 ? "" : "s"} declared by your Ablo schema in ${import_picocolors11.default.bold(args.schema)} (${import_picocolors11.default.bold("--tables")} to override)
+`
+      )
+    );
+  }
   let rotatePlane = null;
   if (rotating) {
     const state = await fetchDataSourceState(apiBaseUrl(), apiKey).catch(
@@ -6000,7 +6177,7 @@ ${ambient}` : ""}`,
   } catch (err) {
     await admin.end({ timeout: 2 }).catch(() => void 0);
     const pg = err ?? {};
-    throw new import_errors9.AbloConnectionError(`Couldn't connect: ${pg.message ?? String(err)}`, {
+    throw new import_errors10.AbloConnectionError(`Couldn't connect: ${pg.message ?? String(err)}`, {
       code: "cli_database_unreachable",
       details: { target },
       cause: err
@@ -6257,7 +6434,7 @@ ${ambient}` : ""}`,
   }
   process.exit(outcome.exitCode);
 }
-var import_picocolors11, import_errors9, import_footprint2, ROTATE_STRANDED_CREDENTIALS_NOTICE;
+var import_picocolors11, import_errors10, import_footprint2, ROTATE_STRANDED_CREDENTIALS_NOTICE;
 var init_connectApply = __esm({
   "src/connectApply.ts"() {
     "use strict";
@@ -6265,7 +6442,7 @@ var init_connectApply = __esm({
     import_picocolors11 = __toESM(require_picocolors(), 1);
     init_src();
     init_dist2();
-    import_errors9 = require("@abloatai/transaction/errors");
+    import_errors10 = require("@abloatai/transaction/errors");
     import_footprint2 = require("@abloatai/transaction/footprint");
     init_connectSetup();
     init_connectOwnership();
@@ -6329,7 +6506,7 @@ function parseConnectArgs(argv) {
         locate = true;
         break;
       default:
-        throw new import_errors10.AbloValidationError(
+        throw new import_errors11.AbloValidationError(
           `unknown connect subcommand: ${lead} (expected register, deregister, check, apply, rotate, resnapshot, scan, locate)`,
           { code: "cli_invalid_arguments" }
         );
@@ -6372,7 +6549,7 @@ function parseConnectArgs(argv) {
       case "--route": {
         const value = argv[++i] ?? "";
         if (!DIRECT_DATA_SOURCE_ROUTES.includes(value)) {
-          throw new import_errors10.AbloValidationError(
+          throw new import_errors11.AbloValidationError(
             `invalid direct route: ${value || "(missing)"} (expected ${DIRECT_DATA_SOURCE_ROUTES.join(", ")})`,
             { code: "cli_invalid_arguments" }
           );
@@ -6381,11 +6558,11 @@ function parseConnectArgs(argv) {
         break;
       }
       default:
-        throw new import_errors10.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        throw new import_errors11.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
   if (role === writeRole) {
-    throw new import_errors10.AbloValidationError("replication and write roles must be different", {
+    throw new import_errors11.AbloValidationError("replication and write roles must be different", {
       code: "cli_invalid_arguments"
     });
   }
@@ -6409,12 +6586,15 @@ function parseConnectArgs(argv) {
     manual
   };
 }
-function printConnectRecipe(args) {
+function printConnectRecipe(args, footprint) {
+  const role = args.role === import_footprint.ABLO_REPLICATION_ROLE ? footprint.replicationRole : args.role;
+  const writeRole = args.writeRole === import_footprint.ABLO_WRITE_ROLE ? footprint.writeRole : args.writeRole;
   const sql = connectSetupSql({
     tables: args.tables,
-    role: args.role,
-    writeRole: args.writeRole,
-    schema: args.schema
+    role,
+    writeRole,
+    schema: args.schema,
+    publication: footprint.publication
   });
   console.log(
     `
@@ -6465,7 +6645,7 @@ function printConnectRecipe(args) {
   console.log(
     import_picocolors12.default.dim(
       `       On Amazon RDS, the REPLICATION attribute is granted, not set directly:
-       ${import_picocolors12.default.bold(`GRANT rds_replication TO ${quoteIdent(args.role)};`)}`
+       ${import_picocolors12.default.bold(`GRANT rds_replication TO ${quoteIdent(role)};`)}`
     )
   );
   console.log(
@@ -6489,8 +6669,8 @@ function printConnectRecipe(args) {
     `
   ${import_picocolors12.default.bold("5.")} Register the two roles with Ablo. Set them just long enough to register \u2014
      Ablo holds them from here, so your app keeps only ${import_picocolors12.default.bold("ABLO_API_KEY")}:
-       ${import_picocolors12.default.bold("ABLO_REPLICATION_DATABASE_URL")}   ${import_picocolors12.default.dim(`\u2192 ${args.role} (replication only)`)}
-       ${import_picocolors12.default.bold("ABLO_WRITE_DATABASE_URL")}         ${import_picocolors12.default.dim(`\u2192 ${args.writeRole} (DML only)`)}
+       ${import_picocolors12.default.bold("ABLO_REPLICATION_DATABASE_URL")}   ${import_picocolors12.default.dim(`\u2192 ${role} (replication only)`)}
+       ${import_picocolors12.default.bold("ABLO_WRITE_DATABASE_URL")}         ${import_picocolors12.default.dim(`\u2192 ${writeRole} (DML only)`)}
        ${import_picocolors12.default.cyan("npx ablo connect register")}
 `
   );
@@ -6518,9 +6698,9 @@ function printCheckItem(item) {
     }
   }
 }
-async function probeDirectWriteReadiness(sql, opts = {}) {
+async function probeDirectWriteReadiness(sql, opts) {
   const schema = opts.schema ?? "public";
-  const publication = opts.publication ?? import_footprint.ABLO_PUBLICATION;
+  const publication = opts.publication;
   const items = [];
   const roleRows = await sql.unsafe(
     `SELECT rolname, rolsuper, rolbypassrls, rolcreatedb, rolcreaterole, rolreplication
@@ -6635,6 +6815,12 @@ async function probeDirectWriteReadiness(sql, opts = {}) {
 }
 async function auditTenantSyncInfra(sql, opts = {}) {
   const artifacts = [];
+  const branchScopedTemplates = /* @__PURE__ */ new Set([
+    import_footprint.ABLO_PUBLICATION,
+    import_footprint3.ABLO_REPLICATION_SLOT,
+    import_footprint.ABLO_REPLICATION_ROLE,
+    import_footprint.ABLO_WRITE_ROLE
+  ]);
   for (const artifact of import_footprint3.ABLO_FOOTPRINT) {
     const name = opts.names ? artifact.name === import_footprint.ABLO_PUBLICATION ? opts.names.publication : artifact.name === import_footprint3.ABLO_REPLICATION_SLOT ? opts.names.slot : artifact.name === import_footprint.ABLO_REPLICATION_ROLE ? opts.names.replicationRole : artifact.name === import_footprint.ABLO_WRITE_ROLE ? opts.names.writeRole : artifact.name : artifact.name;
     const key = artifact.kind === "table" || artifact.kind === "type" ? `${artifact.retired ? "public" : opts.schema ?? "public"}.${name}` : name;
@@ -6647,7 +6833,7 @@ async function auditTenantSyncInfra(sql, opts = {}) {
       present: rows[0]?.present === true,
       purpose: artifact.purpose,
       ...artifact.hazard ? { hazard: artifact.hazard } : {},
-      ...artifact.retired ? { retired: true } : {}
+      ...artifact.retired || !opts.names && branchScopedTemplates.has(artifact.name) ? { retired: true } : {}
     });
   }
   return artifacts;
@@ -6672,7 +6858,7 @@ function requireScopedUrl(kind, verb) {
   );
   process.exit(1);
 }
-async function probeAndReport(dbUrl, kind = "replication", opts = {}) {
+async function probeAndReport(dbUrl, kind, opts) {
   const sql = src_default(dbUrl, { max: 1, prepare: false, connect_timeout: 10, onnotice: () => {
   } });
   let items;
@@ -6683,7 +6869,7 @@ async function probeAndReport(dbUrl, kind = "replication", opts = {}) {
     const dial = dialFailureReason(err);
     if (dial) return { kind: "no-dial", reason: dial };
     const pg = err ?? {};
-    throw new import_errors10.AbloConnectionError(`Couldn't read the database: ${pg.message ?? String(err)}`, {
+    throw new import_errors11.AbloConnectionError(`Couldn't read the database: ${pg.message ?? String(err)}`, {
       code: "cli_database_unreachable",
       cause: err
     });
@@ -6701,7 +6887,7 @@ async function runCheck() {
   const apiKey = resolveRuntimeApiKey().key;
   if (!apiKey) {
     const ambient = ambientEnvKeyNote();
-    throw new import_errors10.AbloAuthenticationError(
+    throw new import_errors11.AbloAuthenticationError(
       `No branch-bound runtime key found. Set ABLO_API_KEY to the sk_ key for the branch to check, or pass \`--env-file .env.local\` explicitly.${ambient ? `
 
 ${ambient}` : ""}`,
@@ -6713,7 +6899,7 @@ ${ambient}` : ""}`,
   if (!result.ok) {
     if (result.code === "no_data_source_registered") {
       console.error(
-        `  ${import_picocolors12.default.yellow("\u2014")} No database is connected to this plane yet, so there's nothing to check.
+        `  ${import_picocolors12.default.yellow("\u2014")} This branch is not connected to a database yet, so there's nothing to check.
 ` + import_picocolors12.default.dim(
           `  Connect one with ${import_picocolors12.default.bold("ablo connect apply")}, then re-run ${import_picocolors12.default.bold("ablo connect check")}.
 `
@@ -6738,8 +6924,9 @@ ${ambient}` : ""}`,
     );
     console.error(
       import_picocolors12.default.dim(
-        `  Direct needs a route Ablo's servers can dial \u2014 public allowlist, PrivateLink, peering,
-  or VPN. Only when no inbound route can exist, use the signed ${import_picocolors12.default.bold("dataSource()")} endpoint fallback.
+        `  For localhost-first development, run ${import_picocolors12.default.bold("ablo dev --local")} and keep it beside the app.
+  The direct WAL path needs a route Ablo's servers can dial \u2014 public allowlist,
+  PrivateLink, peering, VPN, or a database-capable secure tunnel.
 `
       )
     );
@@ -6793,7 +6980,7 @@ async function runRegister(args) {
   const apiKey = resolveMutationApiKey();
   if (!apiKey) {
     const ambient = ambientEnvKeyNote();
-    throw new import_errors10.AbloAuthenticationError(
+    throw new import_errors11.AbloAuthenticationError(
       `No branch-bound runtime key found. Set ABLO_API_KEY to the sk_ key for the branch to register, or pass \`--env-file .env.local\` explicitly.${ambient ? `
 
 ${ambient}` : ""}`,
@@ -6805,13 +6992,32 @@ ${ambient}` : ""}`,
   ${brand("ablo")} ${import_picocolors12.default.dim("connect register")}  ${import_picocolors12.default.dim("register a direct DataSource")}
 `
   );
+  const target = await resolveTarget({ url: apiBaseUrl(), apiKey, keySource: "env" });
+  const confirmed = target.confirmed;
+  if (!confirmed?.branchId) {
+    throw new import_errors11.AbloValidationError(
+      "This key is not bound to a branch, so Ablo cannot validate isolated database objects safely.",
+      { code: "cli_database_unreachable" }
+    );
+  }
+  const publication = (0, import_footprint3.footprintNamesFor)({
+    organizationId: confirmed.organizationId,
+    branchId: confirmed.branchId,
+    ...confirmed.projectId ? { projectId: confirmed.projectId } : {}
+  }).publication;
   console.log(`  ${import_picocolors12.default.bold("Replication role")}
 `);
-  const replication = await probeAndReport(dbUrl, "replication", { schema: args.schema });
+  const replication = await probeAndReport(dbUrl, "replication", {
+    schema: args.schema,
+    publication
+  });
   console.log(`
   ${import_picocolors12.default.bold("Direct-write role")}
 `);
-  const write = await probeAndReport(writeDbUrl, "write", { schema: args.schema });
+  const write = await probeAndReport(writeDbUrl, "write", {
+    schema: args.schema,
+    publication
+  });
   const noDial = [
     replication.kind === "no-dial" ? `replication: ${replication.reason}` : null,
     write.kind === "no-dial" ? `write: ${write.reason}` : null
@@ -6871,7 +7077,7 @@ async function runScan(args) {
   } catch (err) {
     const pg = err ?? {};
     await sql.end({ timeout: 2 });
-    throw new import_errors10.AbloConnectionError(`Couldn't audit the database: ${pg.message ?? String(err)}`, {
+    throw new import_errors11.AbloConnectionError(`Couldn't audit the database: ${pg.message ?? String(err)}`, {
       code: "cli_database_unreachable",
       cause: err
     });
@@ -6918,12 +7124,12 @@ async function runScan(args) {
 async function runLocate(args) {
   console.log(
     `
-  ${brand("ablo")} ${import_picocolors12.default.dim("connect locate")}  ${import_picocolors12.default.dim("which plane holds this database")}
+  ${brand("ablo")} ${import_picocolors12.default.dim("connect locate")}  ${import_picocolors12.default.dim("which branch is connected to this database")}
 `
   );
   const url = args.url ?? readProjectAdminDatabaseUrl();
   if (!url) {
-    throw new import_errors10.AbloValidationError(
+    throw new import_errors11.AbloValidationError(
       "Locating needs a connection string to identify the database. Pass --url <conn> (or set DATABASE_URL) and re-run.",
       { code: "cli_database_url_missing" }
     );
@@ -6931,7 +7137,7 @@ async function runLocate(args) {
   const apiKey = resolveRuntimeApiKey().key;
   if (!apiKey) {
     const ambient = ambientEnvKeyNote();
-    throw new import_errors10.AbloAuthenticationError(
+    throw new import_errors11.AbloAuthenticationError(
       `No branch-bound runtime key found. Set ABLO_API_KEY to a key that can inspect this project, or pass \`--env-file .env.local\` explicitly.${ambient ? `
 
 ${ambient}` : ""}`,
@@ -6961,7 +7167,7 @@ ${ambient}` : ""}`,
   }
   if (!answer.held) {
     console.log(
-      `  ${import_picocolors12.default.green("\u2713")} No plane holds ${import_picocolors12.default.bold(`${label}/${args.schema}`)} \u2014 ${import_picocolors12.default.bold("ablo connect apply")} can register it here.
+      `  ${import_picocolors12.default.green("\u2713")} No branch is connected to ${import_picocolors12.default.bold(`${label}/${args.schema}`)} \u2014 ${import_picocolors12.default.bold("ablo connect apply")} can register it here.
 `
     );
     return;
@@ -6972,9 +7178,9 @@ ${ambient}` : ""}`,
   );
   console.log(
     import_picocolors12.default.dim(
-      `    Ablo binds one plane to each database schema. To move this schema, disconnect it there
+      `    Ablo connects one branch to each database schema. To move this schema, disconnect it there
     first \u2014 run `
-    ) + import_picocolors12.default.cyan("ablo connect deregister") + import_picocolors12.default.dim(` with a key for that plane, then connect here.
+    ) + import_picocolors12.default.cyan("ablo connect deregister") + import_picocolors12.default.dim(` with a key for that branch, then connect here.
 `) + import_picocolors12.default.dim(`    Confirm a candidate key first with `) + import_picocolors12.default.bold("ablo whoami --key-env <NAME>") + import_picocolors12.default.dim(`.
 `) + import_picocolors12.default.dim(`    Match the project id to a name with `) + import_picocolors12.default.bold("ablo projects list --json") + import_picocolors12.default.dim(".") + "\n"
   );
@@ -6982,7 +7188,7 @@ ${ambient}` : ""}`,
 async function runResnapshot() {
   const apiKey = resolveMutationApiKey();
   if (!apiKey) {
-    throw new import_errors10.AbloAuthenticationError(
+    throw new import_errors11.AbloAuthenticationError(
       "No branch-bound secret key found. Set ABLO_API_KEY to the sk_ key for the branch to resnapshot.",
       { code: "cli_api_key_missing" }
     );
@@ -7027,7 +7233,7 @@ async function connect(argv) {
     try {
       process.loadEnvFile(args.envFile);
     } catch (error) {
-      throw new import_errors10.AbloValidationError(
+      throw new import_errors11.AbloValidationError(
         `could not load --env-file ${args.envFile}: ${error instanceof Error ? error.message : String(error)}`,
         { code: "cli_invalid_arguments" }
       );
@@ -7065,14 +7271,36 @@ async function connect(argv) {
     await runConnectApply2(args);
     return;
   }
-  printConnectRecipe(args);
+  const apiKey = resolveRuntimeApiKey().key;
+  if (!apiKey) {
+    throw new import_errors11.AbloAuthenticationError(
+      "Ablo needs the branch key to derive isolated database object names. Set ABLO_API_KEY for this branch, then re-run `ablo connect --manual`.",
+      { code: "cli_api_key_missing" }
+    );
+  }
+  const target = await resolveTarget({ url: apiBaseUrl(), apiKey, keySource: "env" });
+  const confirmed = target.confirmed;
+  if (!confirmed?.branchId) {
+    throw new import_errors11.AbloValidationError(
+      "This key is not bound to a branch, so Ablo cannot derive isolated database object names safely.",
+      { code: "cli_database_unreachable" }
+    );
+  }
+  printConnectRecipe(
+    args,
+    (0, import_footprint3.footprintNamesFor)({
+      organizationId: confirmed.organizationId,
+      branchId: confirmed.branchId,
+      ...confirmed.projectId ? { projectId: confirmed.projectId } : {}
+    })
+  );
 }
-var import_errors10, import_picocolors12, import_footprint3, import_wire7, FOOTPRINT_LOOKUP, CONNECT_USAGE;
+var import_errors11, import_picocolors12, import_footprint3, import_wire7, FOOTPRINT_LOOKUP, CONNECT_USAGE;
 var init_connect = __esm({
   "src/connect.ts"() {
     "use strict";
     init_cjs_shims();
-    import_errors10 = require("@abloatai/transaction/errors");
+    import_errors11 = require("@abloatai/transaction/errors");
     import_picocolors12 = __toESM(require_picocolors(), 1);
     init_src();
     import_footprint3 = require("@abloatai/transaction/footprint");
@@ -7105,7 +7333,7 @@ var init_connect = __esm({
     npx ablo connect rotate               New passwords for both logins, then re-register
     npx ablo connect resnapshot           Recreate only the slot and reload existing rows
     npx ablo connect scan                 List anything Ablo ever set up in your database (read-only, never drops)
-    npx ablo connect locate               See which plane holds this database (read-only; nothing is changed)
+    npx ablo connect locate               See which branch is connected to this database (read-only; nothing is changed)
 
   Running it: bare \`ablo connect\` sets everything up for you \u2014 creating the two
   scoped logins, sharing your tables, and registering \u2014 whenever it finds a
@@ -12800,11 +13028,11 @@ var require_typescript = __commonJS({
       function compareTextSpans(a, b4) {
         return compareValues(a == null ? void 0 : a.start, b4 == null ? void 0 : b4.start) || compareValues(a == null ? void 0 : a.length, b4 == null ? void 0 : b4.length);
       }
-      function maxBy(arr, init2, mapper) {
+      function maxBy(arr, init4, mapper) {
         for (let i = 0; i < arr.length; i++) {
-          init2 = Math.max(init2, mapper(arr[i]));
+          init4 = Math.max(init4, mapper(arr[i]));
         }
-        return init2;
+        return init4;
       }
       function min(items, compare) {
         return reduceLeft(items, (x2, y3) => compare(x2, y3) === -1 ? x2 : y3);
@@ -17303,8 +17531,8 @@ ${lanes.join("\n")}
       function sysLog(s) {
         return curSysLog(s);
       }
-      function setSysLog(logger) {
-        curSysLog = logger;
+      function setSysLog(logger2) {
+        curSysLog = logger2;
       }
       function createDirectoryWatcherSupportingRecursive({
         watchDirectory,
@@ -28403,8 +28631,8 @@ ${lanes.join("\n")}
         return node.initializer;
       }
       function getDeclaredExpandoInitializer(node) {
-        const init2 = getEffectiveInitializer(node);
-        return init2 && getExpandoInitializer(init2, isPrototypeAccess(node.name));
+        const init4 = getEffectiveInitializer(node);
+        return init4 && getExpandoInitializer(init4, isPrototypeAccess(node.name));
       }
       function hasExpandoValueProperty(node, isPrototypeAssignment) {
         return forEach(node.properties, (p2) => isPropertyAssignment(p2) && isIdentifier2(p2.name) && p2.name.escapedText === "value" && p2.initializer && getExpandoInitializer(p2.initializer, isPrototypeAssignment));
@@ -61991,11 +62219,11 @@ ${lanes.join("\n")}
           if (node && isCallExpression(node)) {
             return !!getAssignedExpandoInitializer(node);
           }
-          let init2 = !node ? void 0 : isVariableDeclaration(node) ? node.initializer : isBinaryExpression(node) ? node.right : isPropertyAccessExpression(node) && isBinaryExpression(node.parent) ? node.parent.right : void 0;
-          init2 = init2 && getRightMostAssignedExpression(init2);
-          if (init2) {
+          let init4 = !node ? void 0 : isVariableDeclaration(node) ? node.initializer : isBinaryExpression(node) ? node.right : isPropertyAccessExpression(node) && isBinaryExpression(node.parent) ? node.parent.right : void 0;
+          init4 = init4 && getRightMostAssignedExpression(init4);
+          if (init4) {
             const isPrototypeAssignment = isPrototypeAccess(isVariableDeclaration(node) ? node.name : isBinaryExpression(node) ? node.left : node);
-            return !!getExpandoInitializer(isBinaryExpression(init2) && (init2.operatorToken.kind === 57 || init2.operatorToken.kind === 61) ? init2.right : init2, isPrototypeAssignment);
+            return !!getExpandoInitializer(isBinaryExpression(init4) && (init4.operatorToken.kind === 57 || init4.operatorToken.kind === 61) ? init4.right : init4, isPrototypeAssignment);
           }
           return false;
         }
@@ -62314,15 +62542,15 @@ ${lanes.join("\n")}
           } else if (isIdentifier2(node)) {
             const symbol = lookupSymbolForName(sourceFile, node.escapedText);
             if (!!symbol && !!symbol.valueDeclaration && isVariableDeclaration(symbol.valueDeclaration) && !!symbol.valueDeclaration.initializer) {
-              const init2 = symbol.valueDeclaration.initializer;
-              q2.enqueue(init2);
+              const init4 = symbol.valueDeclaration.initializer;
+              q2.enqueue(init4);
               if (isAssignmentExpression(
-                init2,
+                init4,
                 /*excludeCompoundAssignment*/
                 true
               )) {
-                q2.enqueue(init2.left);
-                q2.enqueue(init2.right);
+                q2.enqueue(init4.left);
+                q2.enqueue(init4.right);
               }
             }
           }
@@ -66910,9 +67138,9 @@ ${lanes.join("\n")}
           )) {
             return void 0;
           }
-          const init2 = isVariableDeclaration(decl) ? getDeclaredExpandoInitializer(decl) : getAssignedExpandoInitializer(decl);
-          if (init2) {
-            const initSymbol = getSymbolOfNode(init2);
+          const init4 = isVariableDeclaration(decl) ? getDeclaredExpandoInitializer(decl) : getAssignedExpandoInitializer(decl);
+          if (init4) {
+            const initSymbol = getSymbolOfNode(init4);
             if (initSymbol) {
               return mergeJSSymbols(initSymbol, symbol);
             }
@@ -73692,9 +73920,9 @@ ${lanes.join("\n")}
           }
           return widened;
         }
-        function getJSContainerObjectType(decl, symbol, init2) {
+        function getJSContainerObjectType(decl, symbol, init4) {
           var _a, _b;
-          if (!isInJSFile(decl) || !init2 || !isObjectLiteralExpression(init2) || init2.properties.length) {
+          if (!isInJSFile(decl) || !init4 || !isObjectLiteralExpression(init4) || init4.properties.length) {
             return void 0;
           }
           const exports22 = createSymbolTable();
@@ -88668,8 +88896,8 @@ ${lanes.join("\n")}
                 return unreachableNeverType;
               }
               if (isVariableDeclaration(node) && (isInJSFile(node) || isVarConstLike2(node))) {
-                const init2 = getDeclaredExpandoInitializer(node);
-                if (init2 && (init2.kind === 218 || init2.kind === 219)) {
+                const init4 = getDeclaredExpandoInitializer(node);
+                if (init4 && (init4.kind === 218 || init4.kind === 219)) {
                   return getTypeAtFlowNode(flow.antecedent);
                 }
               }
@@ -96290,8 +96518,8 @@ ${lanes.join("\n")}
             true
           );
           const prototype = (_a = assignmentSymbol == null ? void 0 : assignmentSymbol.exports) == null ? void 0 : _a.get("prototype");
-          const init2 = (prototype == null ? void 0 : prototype.valueDeclaration) && getAssignedJSPrototype(prototype.valueDeclaration);
-          return init2 ? getSymbolOfDeclaration(init2) : void 0;
+          const init4 = (prototype == null ? void 0 : prototype.valueDeclaration) && getAssignedJSPrototype(prototype.valueDeclaration);
+          return init4 ? getSymbolOfDeclaration(init4) : void 0;
         }
         function getSymbolOfExpando(node, allowDeclaration) {
           if (!node.parent) {
@@ -99307,8 +99535,8 @@ ${lanes.join("\n")}
               case 3:
               case 4:
                 const symbol = getSymbolOfNode(left);
-                const init2 = getAssignedExpandoInitializer(right);
-                return !!init2 && isObjectLiteralExpression(init2) && !!((_a = symbol == null ? void 0 : symbol.exports) == null ? void 0 : _a.size);
+                const init4 = getAssignedExpandoInitializer(right);
+                return !!init4 && isObjectLiteralExpression(init4) && !!((_a = symbol == null ? void 0 : symbol.exports) == null ? void 0 : _a.size);
               default:
                 return false;
             }
@@ -163307,13 +163535,13 @@ ${lanes.join("\n")}
             }
           } else {
             if (isVariableStatement(node) && node.parent === sourceFile && node.declarationList.flags & 2 && node.declarationList.declarations.length === 1) {
-              const init2 = node.declarationList.declarations[0].initializer;
-              if (init2 && isRequireCall(
-                init2,
+              const init4 = node.declarationList.declarations[0].initializer;
+              if (init4 && isRequireCall(
+                init4,
                 /*requireStringLiteralLikeArgument*/
                 true
               )) {
-                diags.push(createDiagnosticForNode(init2, Diagnostics.require_call_may_be_converted_to_an_import));
+                diags.push(createDiagnosticForNode(init4, Diagnostics.require_call_may_be_converted_to_an_import));
               }
             }
             const jsdocTypedefNodes = ts_codefix_exports.getJSDocTypedefNodes(node);
@@ -176204,7 +176432,7 @@ ${newComment.split("\n").map((c) => ` * ${c}`).join("\n")}
           factory.createIdentifier(name)
         );
       }
-      function makeConst(modifiers, name, init2) {
+      function makeConst(modifiers, name, init4) {
         return factory.createVariableStatement(
           modifiers,
           factory.createVariableDeclarationList(
@@ -176214,7 +176442,7 @@ ${newComment.split("\n").map((c) => ` * ${c}`).join("\n")}
               void 0,
               /*type*/
               void 0,
-              init2
+              init4
             )],
             2
             /* Const */
@@ -195188,9 +195416,9 @@ ${newComment.split("\n").map((c) => ` * ${c}`).join("\n")}
             return isFunctionLike(be.right) ? { commentOwner, parameters: be.right.parameters, hasReturn: hasReturn(be.right, options) } : { commentOwner };
           }
           case 172:
-            const init2 = commentOwner.initializer;
-            if (init2 && (isFunctionExpression(init2) || isArrowFunction(init2))) {
-              return { commentOwner, parameters: init2.parameters, hasReturn: hasReturn(init2, options) };
+            const init4 = commentOwner.initializer;
+            if (init4 && (isFunctionExpression(init4) || isArrowFunction(init4))) {
+              return { commentOwner, parameters: init4.parameters, hasReturn: hasReturn(init4, options) };
             }
         }
       }
@@ -206683,13 +206911,13 @@ ${options.prefix}` : "\n" : options.prefix
         return [];
       }
       var ThrottledOperations = class _ThrottledOperations {
-        constructor(host, logger) {
+        constructor(host, logger2) {
           this.host = host;
           this.pendingTimeouts = /* @__PURE__ */ new Map();
-          this.logger = logger.hasLevel(
+          this.logger = logger2.hasLevel(
             3
             /* verbose */
-          ) ? logger : void 0;
+          ) ? logger2 : void 0;
         }
         /**
          * Wait `number` milliseconds and then invoke `cb`.  If, while waiting, schedule
@@ -206722,10 +206950,10 @@ ${options.prefix}` : "\n" : options.prefix
         }
       };
       var GcTimer = class _GcTimer {
-        constructor(host, delay, logger) {
+        constructor(host, delay, logger2) {
           this.host = host;
           this.delay = delay;
-          this.logger = logger;
+          this.logger = logger2;
         }
         scheduleCollect() {
           if (!this.host.gc || this.timerId !== void 0) {
@@ -214086,14 +214314,14 @@ Dynamic files must always be opened with service's current directory or service
         return edits.every((edit) => textSpanEnd(edit.span) < pos);
       }
       var CommandNames = CommandTypes;
-      function formatMessage2(msg, logger, byteLength, newLine) {
-        const verboseLogging = logger.hasLevel(
+      function formatMessage2(msg, logger2, byteLength, newLine) {
+        const verboseLogging = logger2.hasLevel(
           3
           /* verbose */
         );
         const json = JSON.stringify(msg);
         if (verboseLogging) {
-          logger.info(`${msg.type}:${stringifyIndented(msg)}`);
+          logger2.info(`${msg.type}:${stringifyIndented(msg)}`);
         }
         const len = byteLength(json, "utf8");
         return `Content-Length: ${1 + len}\r
@@ -214248,7 +214476,7 @@ ${json}${newLine}`;
         const info = infos && firstOrUndefined(infos);
         return info && !info.isLocal ? { fileName: info.fileName, pos: info.textSpan.start } : void 0;
       }
-      function getReferencesWorker(projects2, defaultProject, initialLocation, useCaseSensitiveFileNames2, logger) {
+      function getReferencesWorker(projects2, defaultProject, initialLocation, useCaseSensitiveFileNames2, logger2) {
         var _a, _b;
         const perProjectResults = getPerProjectReferences(
           projects2,
@@ -214262,7 +214490,7 @@ ${json}${newLine}`;
           ),
           mapDefinitionInProject,
           (project, position) => {
-            logger.info(`Finding references to ${position.fileName} position ${position.pos} in project ${project.getProjectName()}`);
+            logger2.info(`Finding references to ${position.fileName} position ${position.pos} in project ${project.getProjectName()}`);
             return project.getLanguageService().findReferences(position.fileName, position.pos);
           },
           (referencedSymbol, cb) => {
@@ -218631,9 +218859,9 @@ Additional information: BADCLIENT: Bad error code, ${badCode} not found in range
         }
       };
       var _TypingsInstallerAdapter = class _TypingsInstallerAdapter2 {
-        constructor(telemetryEnabled, logger, host, globalTypingsCacheLocation, event, maxActiveRequestCount) {
+        constructor(telemetryEnabled, logger2, host, globalTypingsCacheLocation, event, maxActiveRequestCount) {
           this.telemetryEnabled = telemetryEnabled;
-          this.logger = logger;
+          this.logger = logger2;
           this.host = host;
           this.globalTypingsCacheLocation = globalTypingsCacheLocation;
           this.event = event;
@@ -225611,13 +225839,13 @@ var require_reusify = __commonJS({
         current.next = null;
         return current;
       }
-      function release(obj) {
+      function release2(obj) {
         tail.next = obj;
         tail = obj;
       }
       return {
         get,
-        release
+        release: release2
       };
     }
     module2.exports = reusify;
@@ -225661,7 +225889,7 @@ var require_queue = __commonJS({
           if (self.paused) return;
           for (; queueHead && _running < _concurrency; ) {
             _running++;
-            release();
+            release2();
           }
         },
         running,
@@ -225706,12 +225934,12 @@ var require_queue = __commonJS({
         self.paused = false;
         if (queueHead === null) {
           _running++;
-          release();
+          release2();
           return;
         }
         for (; queueHead && _running < _concurrency; ) {
           _running++;
-          release();
+          release2();
         }
       }
       function idle() {
@@ -225720,7 +225948,7 @@ var require_queue = __commonJS({
       function push2(value, done) {
         var current = cache.get();
         current.context = context;
-        current.release = release;
+        current.release = release2;
         current.value = value;
         current.callback = done || noop3;
         current.errorHandler = errorHandler;
@@ -225741,7 +225969,7 @@ var require_queue = __commonJS({
       function unshift(value, done) {
         var current = cache.get();
         current.context = context;
-        current.release = release;
+        current.release = release2;
         current.value = value;
         current.callback = done || noop3;
         current.errorHandler = errorHandler;
@@ -225759,7 +225987,7 @@ var require_queue = __commonJS({
           worker.call(context, current.value, current.worked);
         }
       }
-      function release(holder) {
+      function release2(holder) {
         if (holder) {
           cache.release(holder);
         }
@@ -283116,7 +283344,7 @@ var import_child_process3 = require("child_process");
 
 // src/migrate.ts
 init_cjs_shims();
-var import_errors7 = require("@abloatai/transaction/errors");
+var import_errors8 = require("@abloatai/transaction/errors");
 init_dist2();
 var import_picocolors6 = __toESM(require_picocolors(), 1);
 var import_fs5 = require("fs");
@@ -283163,7 +283391,7 @@ function parseMigrateArgs(argv) {
         targetSchema = argv[++i] ?? targetSchema;
         break;
       default:
-        throw new import_errors7.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        throw new import_errors8.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
   return { schemaPath, exportName, targetSchema, dryRun, outputFile };
@@ -283279,7 +283507,7 @@ async function migrate(argv) {
   }
   const dbUrl = readProjectAdminDatabaseUrl();
   if (!dbUrl) {
-    throw new import_errors7.AbloValidationError(
+    throw new import_errors8.AbloValidationError(
       `No ${ADMIN_URL_VAR} found (checked process env, .env.local, .env). Set it to apply, or use --dry-run to preview.`,
       { code: "cli_database_url_missing" }
     );
@@ -283494,14 +283722,14 @@ function requireKey2(explicit) {
   }
   return key;
 }
-async function request2(path, init2 = {}, context = {}) {
+async function request2(path, init4 = {}, context = {}) {
   const response = await fetch(`${apiUrl2(context.baseUrl)}${path}`, {
-    method: init2.method ?? "GET",
+    method: init4.method ?? "GET",
     headers: {
       authorization: `Bearer ${requireKey2(context.apiKey)}`,
       "content-type": "application/json"
     },
-    ...init2.body !== void 0 ? { body: JSON.stringify(init2.body) } : {}
+    ...init4.body !== void 0 ? { body: JSON.stringify(init4.body) } : {}
   });
   let body;
   try {
@@ -283584,7 +283812,7 @@ async function readStatus(ref, context = {}) {
   return import_branches.branchStatusResponseSchema.parse(response.body);
 }
 function printStatus(status2) {
-  const { branch, schema, data_source: source } = status2;
+  const { branch, schema, storage, data_source: source } = status2;
   console.log(`  ${import_picocolors14.default.bold(branch.slug)} ${import_picocolors14.default.dim(branch.id)}`);
   console.log(
     `  ${import_picocolors14.default.dim("state")}   ${branch.state === "ready" ? import_picocolors14.default.green(branch.state) : import_picocolors14.default.yellow(branch.state)}`
@@ -283600,7 +283828,7 @@ function printStatus(status2) {
       `  ${import_picocolors14.default.dim("parent")}  ${import_picocolors14.default.bold(schema.parent_compatibility)}${counts}`
     );
   }
-  const sourceLabel = source.kind === "hosted" ? "hosted branch plane" : `${source.kind} \xB7 ${source.host ?? "unknown host"}${source.database ? `/${source.database}` : ""} \xB7 ${source.status ?? "unknown"}`;
+  const sourceLabel = source ? `${source.connection} \xB7 ${source.host ?? "unknown host"}${source.database ? `/${source.database}` : ""} \xB7 ${source.status}` : storage.kind === "unbound" ? "not connected to a database" : storage.kind === "internal" ? `Ablo internal product storage \xB7 ${storage.implementation}` : storage.kind === "blocked" ? "storage configuration needs attention" : "customer database connection unavailable";
   console.log(`  ${import_picocolors14.default.dim("data")}    ${sourceLabel}`);
   if (status2.ready) {
     console.log(`
@@ -283727,15 +283955,15 @@ async function branches(argv) {
 
 // src/branchDev.ts
 init_cjs_shims();
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var import_node_child_process = require("child_process");
 var import_branches2 = require("@abloatai/transaction/branches");
-var import_errors12 = require("@abloatai/transaction/errors");
+var import_errors13 = require("@abloatai/transaction/errors");
 init_config();
 
 // src/dev.ts
 init_cjs_shims();
-var import_errors11 = require("@abloatai/transaction/errors");
+var import_errors12 = require("@abloatai/transaction/errors");
 var import_credentialPolicy2 = require("@abloatai/transaction/auth/credentialPolicy");
 var import_picocolors15 = __toESM(require_picocolors(), 1);
 init_dist2();
@@ -283747,11 +283975,15 @@ init_controlPlane();
 init_config();
 init_readiness();
 init_theme();
+init_dbRole();
+var import_source3 = require("@abloatai/transaction/source");
 function parseDevArgs(argv) {
   let schemaPath = DEFAULT_SCHEMA_PATH;
   let exportName = DEFAULT_EXPORT;
   let url = process.env.ABLO_API_URL ?? DEFAULT_URL;
   let watchEnabled = false;
+  let local = false;
+  let sourcePath = "ablo/data-source.ts";
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     switch (arg) {
@@ -283770,8 +284002,14 @@ function parseDevArgs(argv) {
       case "--no-watch":
         watchEnabled = false;
         break;
+      case "--local":
+        local = true;
+        break;
+      case "--source":
+        sourcePath = argv[++i] ?? sourcePath;
+        break;
       default:
-        throw new import_errors11.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        throw new import_errors12.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
   url = url.replace(/\/+$/, "");
@@ -283781,9 +284019,55 @@ function parseDevArgs(argv) {
     url,
     apiKey: process.env.ABLO_API_KEY,
     watch: watchEnabled,
+    local,
+    sourcePath,
     planeLabel: "branch"
   };
 }
+async function loadLocalSourceHandler(sourcePath) {
+  const abs = (0, import_path5.resolve)(process.cwd(), sourcePath);
+  if (!(0, import_fs7.existsSync)(abs)) {
+    throw new import_errors12.AbloValidationError(
+      `local Data Source not found at ${import_picocolors15.default.bold(sourcePath)}. Add the signed Data Source handler described by ${import_picocolors15.default.bold("npx ablo docs data-sources")}, or pass ${import_picocolors15.default.bold("--source <path>")}.`,
+      { code: "cli_invalid_arguments" }
+    );
+  }
+  const { createJiti } = await import("jiti");
+  const jiti = createJiti(process.cwd());
+  const mod = await jiti.import(abs);
+  const nested = mod.default && typeof mod.default === "object" ? mod.default : void 0;
+  const handler = mod.POST ?? nested?.POST;
+  if (typeof handler !== "function") {
+    throw new import_errors12.AbloValidationError(
+      `${import_picocolors15.default.bold(sourcePath)} must export a ${import_picocolors15.default.bold("POST(request)")} Data Source handler.`,
+      { code: "cli_invalid_arguments" }
+    );
+  }
+  return handler;
+}
+async function registerLocalSource(args) {
+  const response = await fetch(`${args.url}/v1/datasources`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${args.apiKey}`,
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({
+      connection: "endpoint",
+      endpoint: "http://localhost/ablo-dev/reverse-channel",
+      signingKey: args.apiKey,
+      reverseChannel: true,
+      metadata: { managed_by: "ablo dev --local" }
+    })
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new import_errors12.AbloValidationError(
+      `Could not register the local Data Source (${response.status}): ${body}`,
+      { code: "cli_invalid_arguments" }
+    );
+  }
+}
 function classifyKey(apiKey) {
   if (!apiKey) {
     return {
@@ -283921,7 +284205,7 @@ async function runPush(schema, args) {
   }
   if (status2 === 403) {
     const serverSays = body.message ?? body.reason;
-    const hint = schemaPushPlaneHint(body.code) ?? (body.code === "database_role_cannot_enforce_rls" ? `Run ${import_picocolors15.default.bold("npx ablo migrate")} \u2014 it creates the scoped role for you (your DB credential never leaves this machine).` : `Schema authoring needs a branch-bound ${import_picocolors15.default.bold("sk_")} key with ${import_picocolors15.default.bold("schema:push")} \u2014 manage keys at ${import_picocolors15.default.cyan("https://abloatai.com")}.`);
+    const hint = schemaPushStorageHint(body.code) ?? (body.code === "database_role_cannot_enforce_rls" ? `Run ${import_picocolors15.default.bold("npx ablo migrate")} \u2014 it creates the scoped role for you (your DB credential never leaves this machine).` : `Schema authoring needs a branch-bound ${import_picocolors15.default.bold("sk_")} key with ${import_picocolors15.default.bold("schema:push")} \u2014 manage keys at ${import_picocolors15.default.cyan("https://abloatai.com")}.`);
     return {
       ok: false,
       message: `${serverSays ?? "This key can't author schema (missing schema:push scope)."}
@@ -283929,6 +284213,11 @@ async function runPush(schema, args) {
     };
   }
   const serverMessage = String(body.message ?? body.reason ?? bodyText);
+  const storageHint = schemaPushStorageHint(body.code);
+  if (storageHint) {
+    return { ok: false, message: `${serverMessage}
+${import_picocolors15.default.dim(storageHint)}` };
+  }
   if (looksLikeCredentialRefusal(serverMessage)) {
     const pooled = await poolerExplanation(apiBaseUrl(), args.apiKey);
     if (pooled) {
@@ -283949,6 +284238,12 @@ async function dev(argv, runtime = {}) {
   if (runtime.apiKey) args.apiKey = runtime.apiKey;
   else if (!args.apiKey) args.apiKey = resolveRuntimeApiKey("sandbox").key;
   if (runtime.branch) args.planeLabel = runtime.branch.slug;
+  if (args.local && !args.watch) {
+    throw new import_errors12.AbloValidationError(
+      `${import_picocolors15.default.bold("--local")} opens a long-lived secure connector and cannot be combined with ${import_picocolors15.default.bold("--no-watch")}.`,
+      { code: "cli_invalid_arguments" }
+    );
+  }
   const key = classifyKey(args.apiKey);
   if (!key.ok) {
     console.error(import_picocolors15.default.red(`  ${key.reason}`));
@@ -283965,6 +284260,35 @@ async function dev(argv, runtime = {}) {
       `  ${import_picocolors15.default.dim("key")}     temporary \xB7 expires ${runtime.branch.expiresAt}`
     );
   }
+  let localAbort = null;
+  if (args.local) {
+    process.env.ABLO_API_KEY = args.apiKey;
+    if (!process.env.DATABASE_URL) {
+      const databaseUrl = readProjectEnvVariable("DATABASE_URL", process.cwd(), false);
+      if (databaseUrl) process.env.DATABASE_URL = databaseUrl.value;
+    }
+    const handler = await loadLocalSourceHandler(args.sourcePath);
+    await registerLocalSource(args);
+    localAbort = new AbortController();
+    const connector = (0, import_source3.createSourceConnector)({
+      apiKey: args.apiKey,
+      handler,
+      baseURL: args.url,
+      client: "ablo-dev",
+      onStatus(status2) {
+        if (status2 === "ready") {
+          console.log(`  ${import_picocolors15.default.green("\u2713")} local Postgres connected through the secure reverse channel`);
+        }
+      },
+      onError(error) {
+        console.error(import_picocolors15.default.yellow(`  local connector: ${error instanceof Error ? error.message : String(error)}`));
+      }
+    });
+    void connector.run(localAbort.signal).catch((error) => {
+      console.error(import_picocolors15.default.red(`  local connector stopped: ${error instanceof Error ? error.message : String(error)}`));
+    });
+    console.log(`  ${import_picocolors15.default.dim("source")}  ${args.sourcePath} ${import_picocolors15.default.dim("(outbound connector; no public URL)")}`);
+  }
   const schema = await loadSchema(args.schemaPath, args.exportName);
   const modelCount = Object.keys(schema.models).length;
   console.log(
@@ -283979,7 +284303,10 @@ async function dev(argv, runtime = {}) {
   s.start("Pushing schema definition (development branch)");
   const first = await runPush(schema, args);
   s.stop(first.message, first.ok ? 0 : 1);
-  if (!first.ok) process.exit(1);
+  if (!first.ok) {
+    localAbort?.abort();
+    process.exit(1);
+  }
   if (runtime.branch) {
     console.log(
       `
@@ -284033,6 +284360,7 @@ async function dev(argv, runtime = {}) {
   }
   const stop = () => {
     watcher.close();
+    localAbort?.abort();
     console.log(`
   ${import_picocolors15.default.dim("stopped.")}`);
     process.exit(0);
@@ -284048,6 +284376,7 @@ init_controlPlane();
 var BRANCH_DEV_USAGE = `Usage:
   ablo dev [--branch <slug>] [--branch-ttl-hours <1-168>]
            [--schema <path>] [--export <name>] [--url <url>]
+           [--local] [--source <path>]
   ablo dev --no-watch [branch options]
 
 By default, dev discovers the Git/CI branch, ensures its isolated Ablo branch,
@@ -284061,7 +284390,7 @@ function parseBranchDevArgs(argv) {
     const arg = argv[index];
     if (!arg) continue;
     if (arg === "--no-branch") {
-      throw new import_errors12.AbloValidationError(
+      throw new import_errors13.AbloValidationError(
         "--no-branch was removed: development is branch-isolated. Use --branch <slug> to select explicitly.",
         { code: "cli_invalid_arguments" }
       );
@@ -284069,7 +284398,7 @@ function parseBranchDevArgs(argv) {
     if (arg === "--branch") {
       branchSlug = argv[++index];
       if (!branchSlug) {
-        throw new import_errors12.AbloValidationError("--branch requires a slug", {
+        throw new import_errors13.AbloValidationError("--branch requires a slug", {
           code: "cli_invalid_arguments"
         });
       }
@@ -284078,7 +284407,7 @@ function parseBranchDevArgs(argv) {
     if (arg === "--branch-ttl-hours") {
       const value = Number(argv[++index]);
       if (!Number.isInteger(value) || value < 1 || value > 168) {
-        throw new import_errors12.AbloValidationError("--branch-ttl-hours must be between 1 and 168", {
+        throw new import_errors13.AbloValidationError("--branch-ttl-hours must be between 1 and 168", {
           code: "cli_invalid_arguments"
         });
       }
@@ -284096,12 +284425,12 @@ function parseBranchDevArgs(argv) {
 function branchSlugFromRef(ref) {
   const base = ref.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   if (!base) {
-    throw new import_errors12.AbloValidationError(`cannot derive an Ablo branch slug from "${ref}"`, {
+    throw new import_errors13.AbloValidationError(`cannot derive an Ablo branch slug from "${ref}"`, {
       code: "cli_invalid_arguments"
     });
   }
   const nonRoot = base === "production" ? "production-dev" : base;
-  const shortened = nonRoot.length <= 40 ? nonRoot : `${nonRoot.slice(0, 31).replace(/-+$/g, "")}-${(0, import_node_crypto.createHash)("sha256").update(nonRoot).digest("hex").slice(0, 8)}`;
+  const shortened = nonRoot.length <= 40 ? nonRoot : `${nonRoot.slice(0, 31).replace(/-+$/g, "")}-${(0, import_node_crypto2.createHash)("sha256").update(nonRoot).digest("hex").slice(0, 8)}`;
   return import_branches2.branchSlugSchema.parse(shortened);
 }
 function gitBranch() {
@@ -284118,7 +284447,7 @@ function gitBranch() {
 function discoverBranchRef(explicit, env = process.env, readGitBranch = gitBranch) {
   const value = explicit ?? env.ABLO_BRANCH ?? env.GITHUB_HEAD_REF ?? env.GITHUB_REF_NAME ?? env.VERCEL_GIT_COMMIT_REF ?? env.CI_COMMIT_REF_NAME ?? readGitBranch();
   if (!value) {
-    throw new import_errors12.AbloValidationError(
+    throw new import_errors13.AbloValidationError(
       "Could not determine the Git branch. Pass --branch <slug> or set ABLO_BRANCH.",
       { code: "cli_invalid_arguments" }
     );
@@ -284136,13 +284465,13 @@ async function runBranchDev(argv, dependencies = {}) {
   const slug = branchSlugFromRef(ref);
   const managementKey = dependencies.resolveManagementKey?.() ?? resolveManagementKey();
   if (!managementKey) {
-    throw new import_errors12.AbloValidationError(
+    throw new import_errors13.AbloValidationError(
       "Creating a development branch needs a project management credential. Run `npx ablo login` or set ABLO_MANAGEMENT_KEY.",
       { code: "cli_invalid_arguments" }
     );
   }
   if (!managementKey.startsWith("mk_")) {
-    throw new import_errors12.AbloValidationError(
+    throw new import_errors13.AbloValidationError(
       "Branch creation needs the active project management credential (mk_\u2026). Run `npx ablo login` to refresh it.",
       { code: "cli_invalid_arguments" }
     );
@@ -284169,7 +284498,7 @@ async function runBranchDev(argv, dependencies = {}) {
 // src/whoami.ts
 init_cjs_shims();
 var import_picocolors16 = __toESM(require_picocolors(), 1);
-var import_errors13 = require("@abloatai/transaction/errors");
+var import_errors14 = require("@abloatai/transaction/errors");
 init_config();
 init_controlPlane();
 
@@ -284244,7 +284573,7 @@ function parseWhoamiArgs(argv) {
       case "--key": {
         const value = argv[++i];
         if (!value || value.startsWith("--")) {
-          throw new import_errors13.AbloValidationError("`--key` needs a credential value.", {
+          throw new import_errors14.AbloValidationError("`--key` needs a credential value.", {
             code: "cli_invalid_arguments"
           });
         }
@@ -284254,12 +284583,12 @@ function parseWhoamiArgs(argv) {
       case "--key-env": {
         const value = argv[++i];
         if (!value || value.startsWith("--")) {
-          throw new import_errors13.AbloValidationError("`--key-env` needs an environment variable name.", {
+          throw new import_errors14.AbloValidationError("`--key-env` needs an environment variable name.", {
             code: "cli_invalid_arguments"
           });
         }
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
-          throw new import_errors13.AbloValidationError(
+          throw new import_errors14.AbloValidationError(
             `\`${value}\` is not a valid environment variable name.`,
             { code: "cli_invalid_arguments" }
           );
@@ -284268,13 +284597,13 @@ function parseWhoamiArgs(argv) {
         break;
       }
       default:
-        throw new import_errors13.AbloValidationError(`unknown whoami flag: ${arg}`, {
+        throw new import_errors14.AbloValidationError(`unknown whoami flag: ${arg}`, {
           code: "cli_invalid_arguments"
         });
     }
   }
   if (key && keyEnv) {
-    throw new import_errors13.AbloValidationError("Choose one credential source: `--key` or `--key-env`.", {
+    throw new import_errors14.AbloValidationError("Choose one credential source: `--key` or `--key-env`.", {
       code: "cli_invalid_arguments"
     });
   }
@@ -284285,7 +284614,7 @@ function selectWhoamiCredential(args, cwd = process.cwd()) {
   if (args.keyEnv) {
     const found = readProjectEnvVariable(args.keyEnv, cwd);
     if (!found) {
-      throw new import_errors13.AbloAuthenticationError(
+      throw new import_errors14.AbloAuthenticationError(
         `${args.keyEnv} is not set in the process environment, .env.local, or .env.`,
         { code: "cli_api_key_missing" }
       );
@@ -284314,7 +284643,7 @@ function selectWhoamiCredential(args, cwd = process.cwd()) {
     };
   }
   const ambient = ambientEnvKeyNote();
-  throw new import_errors13.AbloAuthenticationError(
+  throw new import_errors14.AbloAuthenticationError(
     `No credential found. Run \`ablo login\`, set ABLO_API_KEY, or pass \`--key-env <NAME>\`.${ambient ? `
 
 ${ambient}` : ""}`,
@@ -284332,7 +284661,7 @@ async function whoami(argv) {
   });
   const confirmed = target.confirmed;
   if (!confirmed) {
-    throw new import_errors13.AbloAuthenticationError(
+    throw new import_errors14.AbloAuthenticationError(
       "The server did not confirm an identity for this credential.",
       { code: "identity_resolve_failed" }
     );
@@ -284436,7 +284765,7 @@ var COMMANDS = [
         { run: "connect check", does: "Confirm your database is ready to share changes with Ablo" },
         { run: "connect resnapshot", does: "Reload existing rows without deregistering or rotating credentials" },
         { run: "connect scan", does: "List anything Ablo ever set up in your database (read-only)" },
-        { run: "connect locate", does: "See which plane holds a database before connecting it" },
+        { run: "connect locate", does: "See which branch is connected to a database before connecting it" },
         { run: "connect deregister", does: "Disconnect this project's database \u2014 Ablo stops reading and writing it" }
       ]
     }
@@ -284667,12 +284996,12 @@ function fullRows(group) {
 }
 
 // src/index.ts
-var import_errors21 = require("@abloatai/transaction/errors");
+var import_errors22 = require("@abloatai/transaction/errors");
 init_push();
 
 // src/generate.ts
 init_cjs_shims();
-var import_errors14 = require("@abloatai/transaction/errors");
+var import_errors15 = require("@abloatai/transaction/errors");
 var import_fs8 = require("fs");
 var import_path6 = require("path");
 var import_picocolors17 = __toESM(require_picocolors(), 1);
@@ -284698,7 +285027,7 @@ function parseGenerateArgs(argv) {
         out = argv[++i] ?? out;
         break;
       default:
-        throw new import_errors14.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        throw new import_errors15.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
   return { schemaPath, exportName, out };
@@ -284731,7 +285060,7 @@ init_cjs_shims();
 var import_child_process2 = require("child_process");
 var import_picocolors18 = __toESM(require_picocolors(), 1);
 init_dist2();
-var import_errors15 = require("@abloatai/transaction/errors");
+var import_errors16 = require("@abloatai/transaction/errors");
 var import_wire8 = require("@abloatai/transaction/wire");
 init_config();
 init_theme();
@@ -284865,7 +285194,7 @@ ${import_picocolors18.default.dim(url)}`, "Approve in your browser");
   }
   if (!provRes.ok) {
     s.stop("Could not provision a key.");
-    const err = (0, import_errors15.translateHttpError)(
+    const err = (0, import_errors16.translateHttpError)(
       provRes.status,
       await provRes.json().catch(() => null),
       provRes.headers.get("x-request-id") ?? void 0
@@ -285180,11 +285509,11 @@ async function status(args = []) {
     }
   } else if (dataSource.kind === "none") {
     console.log(
-      `  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.red("\u2717 no database connected to this plane")} ${import_picocolors19.default.dim("\u2014 writes are held")}`
+      `  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.red("\u2717 this branch is not connected to a database")} ${import_picocolors19.default.dim("\u2014 writes are held")}`
     );
   } else if (reachable) {
     console.log(
-      `  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.yellow("?")} ${import_picocolors19.default.dim(`could not read the plane's databases (${dataSource.detail})`)}`
+      `  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.yellow("?")} ${import_picocolors19.default.dim(`could not read this branch's database connection (${dataSource.detail})`)}`
     );
   }
   const pushed = reachable ? await fetchPushedSchema(apiUrl3, introspectKey) : null;
@@ -285230,7 +285559,7 @@ async function status(args = []) {
     }
   } else if (dataSource.kind === "unknown") {
     console.log(
-      `  ${import_picocolors19.default.yellow("?")} ${import_picocolors19.default.dim("nothing is blocking a write, but this key could not read the plane's databases \u2014 some checks were skipped")}`
+      `  ${import_picocolors19.default.yellow("?")} ${import_picocolors19.default.dim("nothing is blocking a write, but this key could not read the branch's database connection \u2014 some checks were skipped")}`
     );
   } else {
     console.log(
@@ -285337,7 +285666,7 @@ async function doctor() {
     checks.push({
       label: "data",
       state: "fail",
-      detail: "no database connected to this plane \u2014 writes are held",
+      detail: "this branch is not connected to a database \u2014 writes are held",
       fix: "connect one with `ablo connect apply`"
     });
   } else {
@@ -285429,7 +285758,7 @@ async function doctor() {
 
 // src/logs.ts
 init_cjs_shims();
-var import_errors16 = require("@abloatai/transaction/errors");
+var import_errors17 = require("@abloatai/transaction/errors");
 var import_wire9 = require("@abloatai/transaction/wire");
 var import_picocolors21 = __toESM(require_picocolors(), 1);
 init_config();
@@ -285471,12 +285800,12 @@ function parseLogsArgs(argv) {
         args.json = true;
         break;
       case "--mode":
-        throw new import_errors16.AbloValidationError(
+        throw new import_errors17.AbloValidationError(
           "--mode was removed. Logs follow the branch bound to ABLO_API_KEY; select a different branch by supplying its key.",
           { code: "cli_invalid_arguments" }
         );
       default:
-        throw new import_errors16.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        throw new import_errors17.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
   return args;
@@ -285755,7 +286084,7 @@ async function webhooks(argv) {
 
 // src/check.ts
 init_cjs_shims();
-var import_errors17 = require("@abloatai/transaction/errors");
+var import_errors18 = require("@abloatai/transaction/errors");
 var import_picocolors23 = __toESM(require_picocolors(), 1);
 init_src();
 var import_schema9 = require("@abloatai/transaction/schema");
@@ -285903,7 +286232,7 @@ function parseCheckArgs(argv) {
         appSchema = argv[++i] ?? appSchema;
         break;
       default:
-        throw new import_errors17.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        throw new import_errors18.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
   return { schemaPath, exportName, appSchema };
@@ -285929,7 +286258,7 @@ async function reportReadSubject(dbUrl) {
   }
   if (state.kind === "none") {
     console.log(
-      `  ${import_picocolors23.default.dim("ablo")}    ${import_picocolors23.default.yellow("!")} no database is registered for this plane, so Ablo does not read this one`
+      `  ${import_picocolors23.default.dim("ablo")}    ${import_picocolors23.default.yellow("!")} this branch is not connected to a database, so Ablo does not read this one`
     );
     console.log(
       `           ${import_picocolors23.default.dim(`Connect it with ${import_picocolors23.default.bold("ablo connect apply")}. Until then a table here is invisible to the engine.`)}
@@ -286069,9 +286398,9 @@ var ABLO_REACT = /* @__PURE__ */ new Set(["@abloatai/ablo/react", "@abloatai/hum
 function clientRoots(sf) {
   const roots = /* @__PURE__ */ new Set(["ablo", "sync"]);
   for (const decl of sf.getVariableDeclarations()) {
-    const init2 = decl.getInitializer();
-    if (!init2) continue;
-    const text = init2.getText();
+    const init4 = decl.getInitializer();
+    if (!init4) continue;
+    const text = init4.getText();
     if (/^Ablo\s*\(/.test(text) || /^useAblo\s*\(\s*\)/.test(text)) {
       roots.add(decl.getName());
     }
@@ -286238,7 +286567,7 @@ async function upgrade(argv) {
 
 // src/pull.ts
 init_cjs_shims();
-var import_errors18 = require("@abloatai/transaction/errors");
+var import_errors19 = require("@abloatai/transaction/errors");
 var import_picocolors25 = __toESM(require_picocolors(), 1);
 init_src();
 var import_fs10 = require("fs");
@@ -286267,7 +286596,7 @@ function parsePullArgs(argv) {
         force = true;
         break;
       default:
-        throw new import_errors18.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        throw new import_errors19.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
     }
   }
   return { out, appSchema, importPath, force };
@@ -286385,7 +286714,7 @@ async function pull(argv) {
 
 // src/prismaPull.ts
 init_cjs_shims();
-var import_errors19 = require("@abloatai/transaction/errors");
+var import_errors20 = require("@abloatai/transaction/errors");
 var import_picocolors26 = __toESM(require_picocolors(), 1);
 var import_fs11 = require("fs");
 init_theme();
@@ -286583,7 +286912,7 @@ function parsePrismaPullArgs(argv) {
         force = true;
         break;
       default:
-        if (arg.startsWith("--")) throw new import_errors19.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        if (arg.startsWith("--")) throw new import_errors20.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
         schema = arg;
     }
   }
@@ -286643,7 +286972,7 @@ async function prismaPull(argv) {
 // src/drizzlePull.ts
 init_cjs_shims();
 var import_picocolors27 = __toESM(require_picocolors(), 1);
-var import_errors20 = require("@abloatai/transaction/errors");
+var import_errors21 = require("@abloatai/transaction/errors");
 var import_fs12 = require("fs");
 var import_path7 = require("path");
 init_theme();
@@ -286750,7 +287079,7 @@ function parseDrizzlePullArgs(argv) {
         force = true;
         break;
       default:
-        if (arg.startsWith("--")) throw new import_errors20.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+        if (arg.startsWith("--")) throw new import_errors21.AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
         schema = arg;
     }
   }
@@ -286822,6 +287151,7 @@ async function drizzlePull(argv) {
 // src/index.ts
 init_theme();
 init_renderError();
+init_observeCliError();
 
 // src/generators/authScaffold.ts
 init_cjs_shims();
@@ -286903,7 +287233,7 @@ var LOGO = `
   ${brand("ablo")} ${import_picocolors28.default.dim("sync engine")}
 `;
 var HANDLERS = {
-  init: (argv) => init([...argv]),
+  init: (argv) => init3([...argv]),
   login: (argv) => login([...argv]),
   logout: () => logout(),
   projects: (argv) => projects([...argv]),
@@ -286956,7 +287286,7 @@ async function main() {
   const argv = process.argv.slice(3);
   if (!command && raw !== void 0 && raw !== "help" && !raw.startsWith("-")) {
     const suggestion = suggestCommand(raw);
-    throw new import_errors21.AbloValidationError(
+    throw new import_errors22.AbloValidationError(
       `\`${raw}\` isn't an ablo command.` + (suggestion ? ` Did you mean \`ablo ${suggestion}\`?` : " Run `ablo help --all` to see every command."),
       { code: "cli_invalid_arguments" }
     );
@@ -287100,7 +287430,7 @@ async function chooseBool(flagValue, fallback, interactive, prompt) {
   bailIfCancelled(value);
   return value;
 }
-async function init(args = []) {
+async function init3(args = []) {
   const opts = parseInitArgs(args);
   const interactive = Boolean(process.stdin.isTTY) && !opts.yes && !process.env.CI;
   Ie(`${brand("ablo")} ${import_picocolors28.default.dim("sync engine")}`);
@@ -287633,8 +287963,17 @@ function detectPackageManager() {
   if ((0, import_fs13.existsSync)("bun.lockb")) return "bun";
   return "npm";
 }
-main().catch((err) => {
+installCliExitObservationBoundary();
+main().catch(async (err) => {
+  if (err instanceof CliFailureExit) {
+    observeCliError(err);
+    await flushCliErrors();
+    restoreCliExitObservationBoundary();
+    process.exit(err.exitCode);
+  }
   renderCliError(err);
+  await flushCliErrors();
+  restoreCliExitObservationBoundary();
   process.exit(process.exitCode ?? 1);
 });
 /*! Bundled license information: