@databricks-solutions/lakebase-scm-utils 0.3.9 → 0.3.11

package/dist/scripts/lakebase/snapshot.cli.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+
+// scripts/lakebase/databricks-cli.ts
+import { execFile, execFileSync as execFileSync2 } from "child_process";
+import { promisify } from "util";
+import { join as join2 } from "path";
+
+// scripts/lakebase/kit-config.ts
+function intFromEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var KIT_TIMEOUTS = {
+  cliDefault: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_DEFAULT_MS", 3e4),
+  cliCreateProject: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_CREATE_PROJECT_MS", 18e4),
+  cliCreateBranch: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_CREATE_BRANCH_MS", 6e4),
+  cliCreateEndpoint: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_CREATE_ENDPOINT_MS", 6e4),
+  readyWait: intFromEnv("LAKEBASE_KIT_TIMEOUT_READY_WAIT_MS", 12e4),
+  readyPoll: intFromEnv("LAKEBASE_KIT_TIMEOUT_READY_POLL_MS", 5e3),
+  pgConnect: intFromEnv("LAKEBASE_KIT_TIMEOUT_PG_CONNECT_MS", 1e4),
+  pgStatement: intFromEnv("LAKEBASE_KIT_TIMEOUT_PG_STATEMENT_MS", 15e3),
+  gitDefault: intFromEnv("LAKEBASE_KIT_TIMEOUT_GIT_DEFAULT_MS", 5e3),
+  gitCheckout: intFromEnv("LAKEBASE_KIT_TIMEOUT_GIT_CHECKOUT_MS", 1e4),
+  gitNetwork: intFromEnv("LAKEBASE_KIT_TIMEOUT_GIT_NETWORK_MS", 15e3),
+  gitPush: intFromEnv("LAKEBASE_KIT_TIMEOUT_GIT_PUSH_MS", 3e4),
+  cliLong: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_LONG_MS", 6e4),
+  cmdShort: intFromEnv("LAKEBASE_KIT_TIMEOUT_CMD_SHORT_MS", 5e3),
+  initializrCacheTtl: intFromEnv("LAKEBASE_KIT_INITIALIZR_CACHE_TTL_MS", 10 * 60 * 1e3),
+  featureBranchTtlMs: intFromEnv("LAKEBASE_KIT_FEATURE_BRANCH_TTL_MS", 30 * DAY_MS),
+  testBranchTtlMs: intFromEnv("LAKEBASE_KIT_TEST_BRANCH_TTL_MS", 14 * DAY_MS),
+  uatBranchTtlMs: intFromEnv("LAKEBASE_KIT_UAT_BRANCH_TTL_MS", 14 * DAY_MS),
+  perfBranchTtlMs: intFromEnv("LAKEBASE_KIT_PERF_BRANCH_TTL_MS", 7 * DAY_MS)
+};
+function urlFromEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  return raw.replace(/\/+$/, "");
+}
+var KIT_REGISTRIES = {
+  mavenCentral: urlFromEnv("LAKEBASE_KIT_REGISTRY_MAVEN_CENTRAL", "https://repo1.maven.org/maven2"),
+  springInitializr: urlFromEnv("LAKEBASE_KIT_REGISTRY_SPRING_INITIALIZR", "https://start.spring.io")
+};
+
+// scripts/lakebase/databricks-profile.ts
+import * as fs from "fs";
+import { execFileSync } from "child_process";
+
+// scripts/util/exec.ts
+import * as cp from "child_process";
+
+// scripts/lakebase/databricks-profile.ts
+function normalizeHost(host) {
+  return host.trim().replace(/\/+$/, "").toLowerCase();
+}
+function selectProfileForHost(profilesJson, host) {
+  const target = normalizeHost(host);
+  if (!target) return void 0;
+  const start = profilesJson.indexOf("{");
+  if (start < 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(profilesJson.slice(start));
+  } catch {
+    return void 0;
+  }
+  const profiles = parsed.profiles;
+  if (!Array.isArray(profiles)) return void 0;
+  const names = profiles.filter((p) => {
+    if (!p || typeof p !== "object") return false;
+    const rec = p;
+    return typeof rec.name === "string" && typeof rec.host === "string" && rec.valid === true && normalizeHost(rec.host) === target;
+  }).map((p) => p.name);
+  const distinct = Array.from(new Set(names));
+  return distinct.length === 1 ? distinct[0] : void 0;
+}
+function resolveProfileForHostSync(host, timeoutMs = KIT_TIMEOUTS.cliDefault) {
+  if (!normalizeHost(host)) return void 0;
+  let out2;
+  try {
+    out2 = execFileSync("databricks", ["auth", "profiles", "-o", "json"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: timeoutMs
+    });
+  } catch {
+    return void 0;
+  }
+  return selectProfileForHost(out2, host);
+}
+
+// scripts/lakebase/env-file.ts
+import * as fs2 from "fs";
+import * as path from "path";
+function readEnvVar(envPath, key) {
+  if (!fs2.existsSync(envPath)) return void 0;
+  let value;
+  for (const line of fs2.readFileSync(envPath, "utf-8").split("\n")) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("#") || !trimmed.startsWith(`${key}=`)) continue;
+    value = trimmed.slice(key.length + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return value && value.length > 0 ? value : void 0;
+}
+
+// scripts/lakebase/databricks-cli.ts
+var execFileP = promisify(execFile);
+var DatabricksCliError = class extends Error {
+  constructor(message, profile, stderr) {
+    super(message);
+    this.profile = profile;
+    this.stderr = stderr;
+    this.name = "DatabricksCliError";
+  }
+  profile;
+  stderr;
+};
+var DatabricksAuthError = class extends DatabricksCliError {
+  constructor(profile, detail) {
+    const login = `databricks auth login${profile ? ` --profile ${profile}` : ""}`;
+    super(
+      `Databricks authentication failed${profile ? ` for profile "${profile}"` : ""}: the cached token is missing or expired. Re-authenticate, then re-run:
+  ${login}
+${detail}`,
+      profile,
+      detail
+    );
+    this.name = "DatabricksAuthError";
+  }
+};
+var profileByHost = /* @__PURE__ */ new Map();
+var profileByEnvFile = /* @__PURE__ */ new Map();
+var hostByEnvFile = /* @__PURE__ */ new Map();
+function envFileHost(cwd) {
+  if (hostByEnvFile.has(cwd)) return hostByEnvFile.get(cwd);
+  const v = readEnvVar(join2(cwd, ".env"), "DATABRICKS_HOST");
+  hostByEnvFile.set(cwd, v);
+  return v;
+}
+function effectiveHost(opts) {
+  const base = opts.env ?? process.env;
+  const cwd = opts.cwd ?? process.cwd();
+  const h = opts.host ?? base.DATABRICKS_HOST ?? envFileHost(cwd);
+  return h?.trim() || void 0;
+}
+function isAuthFailure(text) {
+  return /refresh token is invalid|auth login|could not be retrieved because|not authenticated|no valid.*(credential|token)|invalid.*(access token|credential)|\b401\b|unauthorized/i.test(
+    text
+  );
+}
+function resolveProfile(opts) {
+  const base = opts.env ?? process.env;
+  if (opts.profile) return opts.profile;
+  const envProfile = base.DATABRICKS_CONFIG_PROFILE?.trim();
+  if (envProfile) return envProfile;
+  const cwd = opts.cwd ?? process.cwd();
+  let fromEnvFile;
+  if (profileByEnvFile.has(cwd)) {
+    fromEnvFile = profileByEnvFile.get(cwd);
+  } else {
+    fromEnvFile = readEnvVar(join2(cwd, ".env"), "DATABRICKS_CONFIG_PROFILE");
+    profileByEnvFile.set(cwd, fromEnvFile);
+  }
+  if (fromEnvFile) return fromEnvFile;
+  const host = effectiveHost(opts);
+  if (!host) return void 0;
+  if (profileByHost.has(host)) return profileByHost.get(host);
+  const resolved = resolveProfileForHostSync(host, opts.timeout);
+  profileByHost.set(host, resolved);
+  return resolved;
+}
+function buildInvocation(args, opts) {
+  const base = opts.env ?? process.env;
+  const trimmedHost = effectiveHost(opts)?.replace(/\/+$/, "");
+  const env = { ...base };
+  if (trimmedHost) env.DATABRICKS_HOST = trimmedHost;
+  delete env.DATABRICKS_WORKSPACE_ID;
+  const profile = resolveProfile(opts);
+  const argv = profile && !opts.noProfile && !args.includes("--profile") ? [...args, "--profile", profile] : args;
+  return { argv, env, profile };
+}
+function classifyDatabricksError(err, argv, profile) {
+  const e = err;
+  const asText = (v) => typeof v === "string" ? v : Buffer.isBuffer(v) ? v.toString("utf8") : "";
+  const stderr = asText(e.stderr).trim();
+  const stdout = asText(e.stdout).trim();
+  const haystack = `${e.message ?? ""}
+${stderr}
+${stdout}`;
+  if (isAuthFailure(haystack)) {
+    return new DatabricksAuthError(profile, stderr || stdout || (e.message ?? ""));
+  }
+  const killed = e.killed === true;
+  const signal = e.signal ?? void 0;
+  const detail = stderr ? `
+stderr: ${stderr}` : stdout ? `
+stdout: ${stdout}` : killed || signal ? `
+(no output; the CLI was killed${signal ? ` by ${signal}` : ""}, likely a TIMEOUT; raise the budget via the matching LAKEBASE_KIT_TIMEOUT_* env var)` : e.code !== void 0 ? `
+(no stderr/stdout; exit ${e.code})` : "";
+  return new DatabricksCliError(
+    `databricks ${argv.join(" ")} failed: ${e.message}${detail}`,
+    profile,
+    stderr || stdout
+  );
+}
+async function runDatabricks(args, opts = {}) {
+  const { argv, env, profile } = buildInvocation(args, opts);
+  const timeout = opts.timeout ?? KIT_TIMEOUTS.cliDefault;
+  try {
+    if (opts.input !== void 0) {
+      return await execDatabricksWithStdin(argv, opts.input, env, timeout);
+    }
+    const { stdout } = await execFileP("databricks", argv, { env, timeout });
+    return stdout.toString();
+  } catch (err) {
+    throw classifyDatabricksError(err, argv, profile);
+  }
+}
+function execDatabricksWithStdin(argv, input, env, timeout) {
+  return new Promise((resolve, reject) => {
+    const child = execFile("databricks", argv, { env, timeout }, (err, stdout, stderr) => {
+      if (err) {
+        err.stdout = String(stdout ?? "");
+        err.stderr = String(stderr ?? "");
+        reject(err);
+        return;
+      }
+      resolve(String(stdout ?? ""));
+    });
+    child.stdin?.on("error", () => {
+    });
+    child.stdin?.end(input);
+  });
+}
+
+// scripts/lakebase/branch-utils.ts
+function projectPath(instance) {
+  return `projects/${instance}`;
+}
+
+// scripts/lakebase/snapshot.ts
+function branchResource(instance, branch) {
+  return branch.includes("/") ? branch : `${projectPath(instance)}/branches/${branch}`;
+}
+function snapshotResource(instance, snapshot) {
+  return snapshot.includes("/") ? snapshot : `${projectPath(instance)}/snapshots/${snapshot}`;
+}
+function buildSnapshotSpec(args) {
+  if (args.sourceBranchTime && args.sourceBranchLsn) {
+    throw new Error("sourceBranchTime and sourceBranchLsn are mutually exclusive \u2014 pass at most one point-in-time.");
+  }
+  if (args.ttl && args.noExpiry === true) {
+    throw new Error(`Cannot set both ttl ("${args.ttl}") and noExpiry: true \u2014 they are mutually exclusive.`);
+  }
+  const spec = { source_branch: branchResource(args.instance, args.sourceBranch) };
+  if (args.sourceBranchTime) spec.source_branch_time = args.sourceBranchTime;
+  else if (args.sourceBranchLsn) spec.source_branch_lsn = args.sourceBranchLsn;
+  if (args.ttl) spec.ttl = args.ttl;
+  else if (args.noExpiry ?? true) spec.no_expiry = true;
+  return spec;
+}
+async function createSnapshot(args) {
+  const spec = buildSnapshotSpec(args);
+  return runDatabricks(
+    ["postgres", "create-snapshot", projectPath(args.instance), args.snapshot, "--json", JSON.stringify({ spec })],
+    { host: args.host, timeout: KIT_TIMEOUTS.cliCreateBranch }
+  );
+}
+async function deleteSnapshot(args) {
+  return runDatabricks(["postgres", "delete-snapshot", snapshotResource(args.instance, args.snapshot)], {
+    host: args.host
+  });
+}
+async function listSnapshots(args) {
+  return runDatabricks(["postgres", "list-snapshots", projectPath(args.instance), "-o", "json"], { host: args.host });
+}
+
+// scripts/lakebase/snapshot.cli.ts
+function parseArgs(argv) {
+  const out2 = {};
+  let i = 0;
+  if (argv[0] && !argv[0].startsWith("-")) {
+    out2.subcommand = argv[0];
+    i = 1;
+  }
+  for (; i < argv.length; i++) {
+    switch (argv[i]) {
+      case "--instance":
+        out2.instance = argv[++i];
+        break;
+      case "--snapshot":
+        out2.snapshot = argv[++i];
+        break;
+      case "--branch":
+        out2.branch = argv[++i];
+        break;
+      case "--at-time":
+        out2.atTime = argv[++i];
+        break;
+      case "--at-lsn":
+        out2.atLsn = argv[++i];
+        break;
+      case "--ttl":
+        out2.ttl = argv[++i];
+        break;
+      case "--no-expiry":
+        out2.noExpiry = true;
+        break;
+      case "--host":
+        out2.host = argv[++i];
+        break;
+      case "--pretty":
+        out2.pretty = true;
+        break;
+      case "--help":
+      case "-h":
+        out2.help = true;
+        break;
+    }
+  }
+  return out2;
+}
+var USAGE = `usage: lakebase-snapshot <create|delete|list> --instance <project> [flags]
+  create  --snapshot <id> --branch <src> [--at-time <iso> | --at-lsn <lsn>] [--ttl <s> | --no-expiry]
+  delete  --snapshot <id>
+  list
+Then branch from it: lakebase-branch create --branch <v> --from-snapshot <id> --instance <project>`;
+function out(result, pretty) {
+  process.stdout.write(JSON.stringify(result, null, pretty ? 2 : void 0) + "\n");
+}
+function need(a, keys) {
+  const missing = keys.filter((k) => a[k] === void 0 || a[k] === "");
+  if (missing.length) {
+    process.stderr.write(`missing ${missing.map((k) => "--" + String(k)).join(", ")}
+${USAGE}
+`);
+    return false;
+  }
+  return true;
+}
+async function main() {
+  const a = parseArgs(process.argv.slice(2));
+  if (a.help || !a.subcommand) {
+    process.stderr.write(USAGE + "\n");
+    return a.help ? 0 : 2;
+  }
+  switch (a.subcommand) {
+    case "create": {
+      if (!need(a, ["instance", "snapshot", "branch"])) return 2;
+      const raw = await createSnapshot({
+        instance: a.instance,
+        snapshot: a.snapshot,
+        sourceBranch: a.branch,
+        sourceBranchTime: a.atTime,
+        sourceBranchLsn: a.atLsn,
+        ttl: a.ttl,
+        noExpiry: a.noExpiry,
+        host: a.host
+      });
+      out({ created: a.snapshot, raw: raw.trim() || void 0 }, !!a.pretty);
+      return 0;
+    }
+    case "delete": {
+      if (!need(a, ["instance", "snapshot"])) return 2;
+      await deleteSnapshot({ instance: a.instance, snapshot: a.snapshot, host: a.host });
+      out({ deleted: a.snapshot }, !!a.pretty);
+      return 0;
+    }
+    case "list": {
+      if (!need(a, ["instance"])) return 2;
+      const raw = await listSnapshots({ instance: a.instance, host: a.host });
+      try {
+        out(JSON.parse(raw), !!a.pretty);
+      } catch {
+        process.stdout.write(raw);
+      }
+      return 0;
+    }
+    default:
+      process.stderr.write(`unknown subcommand '${a.subcommand}'
+${USAGE}
+`);
+      return 2;
+  }
+}
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(String(err instanceof Error ? err.message : err) + "\n");
+    process.exit(1);
+  }
+);

package/dist/scripts/util/index.cjs

@@ -1667,8 +1667,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.9".length > 0) {
-    cached = "0.3.9";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.js

@@ -1630,8 +1630,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.9".length > 0) {
-    cached = "0.3.9";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Lakebase SCM + substrate engine: database branching, paired-branch SCM workflows, connection/credential minting, schema migration, project scaffold + deploy primitives, and the git/github utility layer. Extracted from consort for portable, standalone consumption by lakebase-scm-extension and the SFTDD orchestration.",
   "type": "module",
   "private": false,
@@ -107,6 +107,7 @@
     "lakebase-scm-recover-orphans": "./dist/scripts/lakebase/scm-recover-orphans.cli.js",
     "lakebase-scm-state": "./dist/scripts/lakebase/scm-state.cli.js",
     "lakebase-scm-wait-ci": "./dist/scripts/lakebase/scm-wait-ci.cli.js",
+    "lakebase-snapshot": "./dist/scripts/lakebase/snapshot.cli.js",
     "lakebase-sync-ci-secrets": "./dist/scripts/lakebase/sync-ci-secrets.cli.js"
   },
   "scripts": {

package/scripts/git/commit-push.ts

@@ -45,24 +45,70 @@ export class WorkflowScopeError extends Error {
  * For non-initial-commit flows, prefer the primitives in ./commits.ts.
  */
 export async function commitAndPush(args: CommitAndPushArgs): Promise<void> {
-  await exec("git add -A", { cwd: args.projectDir });
-  await exec(`git commit -m ${JSON.stringify(args.message)}`, {
-    cwd: args.projectDir,
+  await commitInitial(args.projectDir, args.message);
+  if (args.push === false) return;
+  await pushInitial({ projectDir: args.projectDir, remote: args.remote, branch: args.branch });
+}
+
+/** Stage everything and make the initial commit (no push). */
+export async function commitInitial(projectDir: string, message: string): Promise<void> {
+  await exec("git add -A", { cwd: projectDir });
+  await exec(`git commit -m ${JSON.stringify(message)}`, {
+    cwd: projectDir,
     timeout: 30_000,
   });
-  if (args.push === false) return;
+}
+
+export interface PushInitialArgs {
+  projectDir: string;
+  /** Remote name. Default: "origin". */
+  remote?: string;
+  /** Branch name. Default: "main". */
+  branch?: string;
+  /**
+   * Total push attempts (>= 1). Default 1 (preserves commitAndPush's behavior).
+   * The create flow passes 2: the FIRST push fires the project's pre-push hook,
+   * which triggers the one-time cold download of the Consort toolkit — that race
+   * can fail the push, but the toolkit is CACHED afterward, so a single retry then
+   * sails through (the cold-download incident). A `workflow`-scope rejection is a
+   * real auth gap, never retried.
+   */
+  attempts?: number;
+  /** Delay between attempts (ms). Default 1500. Injected in tests. */
+  delayMs?: number;
+  /** Injectable sleep (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injectable runner (tests); defaults to the real `git push`. */
+  run?: (cmd: string, cwd: string) => Promise<void>;
+}
+
+/**
+ * Push the initial branch with `-u`, retrying a transient failure up to
+ * `attempts` times. Maps the GitHub `workflow`-scope rejection to
+ * {@link WorkflowScopeError} (thrown immediately, never retried). Throws the last
+ * error after the final attempt.
+ */
+export async function pushInitial(args: PushInitialArgs): Promise<void> {
   const remote = args.remote ?? "origin";
   const branch = args.branch ?? "main";
-  try {
-    await exec(`git push -u ${remote} ${branch}`, {
-      cwd: args.projectDir,
-      timeout: 30_000,
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (/without `?workflow`? scope|workflow scope/i.test(msg)) {
-      throw new WorkflowScopeError(args.projectDir);
+  const attempts = Math.max(1, args.attempts ?? 1);
+  const sleep = args.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const run =
+    args.run ??
+    ((cmd: string, cwd: string) => exec(cmd, { cwd, timeout: 30_000 }).then(() => undefined));
+  let lastErr: unknown;
+  for (let i = 1; i <= attempts; i++) {
+    try {
+      await run(`git push -u ${remote} ${branch}`, args.projectDir);
+      return;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/without `?workflow`? scope|workflow scope/i.test(msg)) {
+        throw new WorkflowScopeError(args.projectDir);
+      }
+      lastErr = err;
+      if (i < attempts) await sleep(args.delayMs ?? 1500);
     }
-    throw err;
   }
+  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
 }

package/scripts/lakebase/branch-create.ts

@@ -87,6 +87,57 @@ export interface CreateBranchArgs extends BranchLookupOpts {
    * caller's expectation. Default: false (fallback enabled).
    */
   strictParent?: boolean;
+  /**
+   * Branch from an immutable SNAPSHOT instead of a source branch (the kit's
+   * fast verify-branch provisioning: snapshot the committed schema once, then
+   * branch copy-on-write from it per cycle — no `alembic upgrade head` rebuild,
+   * and a FIXED point so the fork never goes stale). Accepts a bare snapshot id
+   * or a full `projects/<p>/snapshots/<id>` path. Maps to `spec.source_snapshot`,
+   * which the Lakebase API treats as mutually exclusive with source_branch /
+   * source_branch_time / source_branch_lsn — so when set, the parentBranch
+   * resolution below is skipped entirely.
+   */
+  fromSnapshot?: string;
+  /**
+   * Point-in-time for a branch-from-branch create: an ISO-8601 timestamp.
+   * Maps to `spec.source_branch_time` — branch the source branch AS OF this
+   * time (PITR). Mutually exclusive with sourceBranchLsn and with fromSnapshot.
+   */
+  sourceBranchTime?: string;
+  /**
+   * Point-in-time for a branch-from-branch create: an LSN (e.g. "0/16B3748").
+   * Maps to `spec.source_branch_lsn`. Mutually exclusive with sourceBranchTime
+   * and with fromSnapshot.
+   */
+  sourceBranchLsn?: string;
+}
+
+/** The create-branch request `spec` — one source group (source_branch [+time|+lsn]
+ *  OR source_snapshot) plus exactly one expiration (no_expiry | ttl). */
+interface BranchSpec {
+  source_branch?: string;
+  source_snapshot?: string;
+  source_branch_time?: string;
+  source_branch_lsn?: string;
+  no_expiry?: boolean;
+  ttl?: string;
+}
+
+/** Resolve a snapshot arg (bare id or full path) to the full snapshot resource path. */
+function snapshotPath(instance: string, snapshot: string): string {
+  return snapshot.includes("/") ? snapshot : `${projectPath(instance)}/snapshots/${snapshot}`;
+}
+
+/** Apply the expiration policy (ttl wins; else default no_expiry: true) onto a spec,
+ *  refusing the inconsistent ttl + noExpiry:true combination. */
+function applyExpiration(spec: BranchSpec, ttl: string | undefined, noExpiry: boolean | undefined): void {
+  if (ttl && noExpiry === true) {
+    throw new LakebaseBranchError(
+      `Cannot set both ttl ("${ttl}") and noExpiry: true on the same branch – they are mutually exclusive. Pass one or the other.`,
+    );
+  }
+  if (ttl) spec.ttl = ttl;
+  else if (noExpiry ?? true) spec.no_expiry = true;
 }
 
 /**
@@ -104,6 +155,38 @@ export async function createBranch(args: CreateBranchArgs): Promise<LakebaseBran
   const sanitized = sanitizeBranchName(args.branch);
   const lookup: BranchLookupOpts = { instance: args.instance, host: args.host };
 
+  // SNAPSHOT SOURCE (fast verify-branch provisioning): branch copy-on-write from an
+  // immutable snapshot. source_snapshot is mutually exclusive with the source_branch
+  // family, so this path skips parentBranch resolution entirely. Idempotent: a branch
+  // that already exists under this name is returned as-is (the ephemeral verify branches
+  // this serves are single-use; we don't re-assert the snapshot lineage of a survivor).
+  if (args.fromSnapshot) {
+    if (args.parentBranch || args.sourceBranchTime || args.sourceBranchLsn) {
+      throw new LakebaseBranchError(
+        `fromSnapshot is mutually exclusive with parentBranch / sourceBranchTime / sourceBranchLsn ` +
+          `(the Lakebase API rejects source_snapshot combined with any source_branch field).`,
+      );
+    }
+    const existing = await getBranchByName(sanitized, lookup);
+    if (existing) return existing;
+    const spec: BranchSpec = { source_snapshot: snapshotPath(args.instance, args.fromSnapshot) };
+    applyExpiration(spec, args.ttl, args.noExpiry);
+    try {
+      await createWithTtlRecovery(args.instance, sanitized, spec, args.host);
+    } catch (err) {
+      if (err instanceof LakebaseBranchTtlTooLongError) throw err;
+      const landed = await getBranchByName(sanitized, lookup);
+      if (!landed) throw err;
+    }
+    return waitForBranchReady({
+      instance: args.instance,
+      host: args.host,
+      branch: sanitized,
+      timeoutMs: args.readyTimeoutMs ?? KIT_TIMEOUTS.readyWait,
+      pollIntervalMs: args.pollIntervalMs ?? KIT_TIMEOUTS.readyPoll,
+    });
+  }
+
   // Resolve the source (parent) branch full path first – needed both for
   // create AND for the idempotency-vs-conflict comparison below.
   let sourceBranchPath: string | undefined;
@@ -182,22 +265,18 @@ export async function createBranch(args: CreateBranchArgs): Promise<LakebaseBran
     return existing;
   }
 
-  // Expiration policy: ttl wins if set; otherwise default to no_expiry: true.
-  // Refuse the inconsistent combination (ttl + noExpiry: true both set).
-  if (args.ttl && args.noExpiry === true) {
+  if (args.sourceBranchTime && args.sourceBranchLsn) {
     throw new LakebaseBranchError(
-      `Cannot set both ttl ("${args.ttl}") and noExpiry: true on the same ` +
-        `branch – they are mutually exclusive. Pass one or the other.`,
+      `sourceBranchTime and sourceBranchLsn are mutually exclusive – pass at most one point-in-time.`,
     );
   }
-  const specObj: { source_branch: string; no_expiry?: boolean; ttl?: string } = {
-    source_branch: sourceBranchPath,
-  };
-  if (args.ttl) {
-    specObj.ttl = args.ttl;
-  } else if (args.noExpiry ?? true) {
-    specObj.no_expiry = true;
-  }
+  const specObj: BranchSpec = { source_branch: sourceBranchPath };
+  // PITR: pin the source branch at a timestamp or LSN (source_branch_time /
+  // source_branch_lsn) — e.g. branch the higher env AS OF the committed-schema point.
+  if (args.sourceBranchTime) specObj.source_branch_time = args.sourceBranchTime;
+  else if (args.sourceBranchLsn) specObj.source_branch_lsn = args.sourceBranchLsn;
+  // Expiration policy: ttl wins if set; otherwise default to no_expiry: true.
+  applyExpiration(specObj, args.ttl, args.noExpiry);
   try {
     await createWithTtlRecovery(args.instance, sanitized, specObj, args.host);
   } catch (err) {
@@ -299,7 +378,7 @@ function assertSourceMatches(
 async function createWithTtlRecovery(
   instance: string,
   sanitized: string,
-  specObj: { source_branch: string; no_expiry?: boolean; ttl?: string },
+  specObj: BranchSpec,
   host: string | undefined,
 ): Promise<void> {
   const originalTtl = specObj.ttl;