@supacloud/cli 0.81.0 → 0.82.0

package/dist/index.js

@@ -178699,7 +178699,17 @@ function outcomeUnknownGuidance(text) {
   }
   if (typeof payload !== "object" || payload === null || !("ok" in payload) || payload.ok !== false || !("error" in payload) || typeof payload.error !== "object" || payload.error === null || !("code" in payload.error) || payload.error.code !== "OUTCOME_UNKNOWN")
     return null;
-  return "OUTCOME_UNKNOWN：操作结果无法确认，服务端可能已经完成操作，但客户端未收到可验证的最终结果。" + "请先查询当前状态或操作回执，再决定是否重试；不要直接重复提交。";
+  const data = payload;
+  const { project_ref: ref, application_id: id, environment_id: environment } = data;
+  const safeScope = typeof ref === "string" && /^[a-z0-9-]{1,20}$/.test(ref) && typeof id === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(id) && typeof environment === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(environment);
+  let command;
+  if (safeScope && (data.operation === "applications.promote_application" || data.operation === "applications.reconcile_promotion") && typeof data.mutation_id === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(data.mutation_id)) {
+    command = `supacloud-cli app promote-status --ref ${ref} --id ${id} --environment_id ${environment} --mutation_id ${data.mutation_id}`;
+  } else if (safeScope && (data.operation === "applications.create_preview" || data.operation === "applications.cleanup_preview")) {
+    command = `supacloud-cli app preview-list --ref ${ref} --id ${id} --environment_id ${environment}`;
+  }
+  return "OUTCOME_UNKNOWN：操作结果无法确认，服务端可能已经完成操作，但客户端未收到可验证的最终结果。" + "请先查询当前状态或操作回执，再决定是否重试；不要直接重复提交。" + (command ? `
+保持原 --env/--env-file 选择，先查询：${command}` : "");
 }
 
 // src/shared/cli.ts
@@ -179093,21 +179103,8 @@ function resolveSupaCloudContext(env = process.env, cwd = process.cwd(), selecti
 var ACTION_POLICY = {
   deploy: { write: ["deploy"] },
   applications: {
-    read: ["list_releases", "get_release", "get_runtime", "get_deployment_evidence", "get_configuration", "get_release_transfer_plan", "get_promotion_plan", "get_rollback_snapshot", "get_history", "get_deploy_plan", "logs", "get_preview_plan"],
-    write: [
-      "upload_release",
-      "put_configuration",
-      "transfer_release",
-      "activate_release",
-      "deploy_release",
-      "rollback_release",
-      "reconcile_activation",
-      "retire_activation",
-      "create_preview",
-      "list_previews",
-      "get_preview",
-      "cleanup_preview"
-    ]
+    read: ["list_releases", "get_release", "get_runtime", "get_deployment_evidence", "get_configuration", "get_release_transfer_plan", "get_promotion_plan", "get_rollback_snapshot", "get_history", "get_deploy_plan", "get_promotion_status", "get_preview_plan", "logs"],
+    write: ["upload_release", "put_configuration", "transfer_release", "promote_application", "reconcile_promotion", "create_preview", "list_previews", "get_preview", "cleanup_preview", "activate_release", "deploy_release", "rollback_release", "reconcile_activation", "retire_activation"]
   },
   project: {
     read: ["get", "endpoints", "health", "logs", "api_keys", "settings", "tasks", "task_detail", "task_stats", "dlq", "background_settings"],
@@ -179202,8 +179199,8 @@ var ACTION_POLICY = {
   ai: { local: ["show_skill", "install_skill"] },
   app: {
     local: ["init", "generate", "dev", "watch", "verify-plan", "compile", "check", "graph", "explain", "export-tools", "context", "doctor", "fix", "plan", "build"],
-    read: ["status", "logs", "transfer-plan", "promote-plan", "rollback-plan", "history", "deploy-plan", "diff", "preview-plan"],
-    write: ["upload", "configure", "transfer", "deploy", "rollback", "reconcile", "retire", "preview", "previews", "preview-status", "preview-cleanup"]
+    read: ["status", "logs", "transfer-plan", "promote-plan", "rollback-plan", "history", "deploy-plan", "diff", "promote-status", "preview-plan"],
+    write: ["upload", "configure", "transfer", "promote", "promote-reconcile", "deploy", "rollback", "reconcile", "retire", "preview", "previews", "preview-list", "preview-create", "preview-status", "preview-cleanup"]
   },
   db: {
     local: ["context", "lint", "explain", "diff", "role_sql"],
@@ -187550,6 +187547,374 @@ var ApplicationActivationResultSchema2 = ApplicationActivationResultSchema;
 var ApplicationActivationRetirementResultSchema2 = ApplicationActivationRetirementResultSchema;
 var ApplicationRollbackSnapshotSchema2 = ApplicationRollbackSnapshotSchema;
 var ApplicationActivationHistoryCursorSchema2 = ApplicationActivationHistoryCursorSchema;
+var ApplicationPromotionPlanSchema2 = ApplicationPromotionPlanSchema;
+
+// src/shared/mutation-protocol.ts
+import { createHash as createHash6 } from "node:crypto";
+var MUTATION_ID_PATTERN2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+var FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+var OPERATION_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,127}$/;
+var RESOURCE_KEY_PATTERN = /^v1\/(?:[a-z0-9][a-z0-9._-]{0,63})\/([A-Za-z0-9_-]{2,171})$/;
+var RESOURCE_ID_CONTROL_PATTERN = /[\u0000-\u001f\u007f-\u009f]/u;
+var FAILURE_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+var LEASE_OWNER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,254}$/;
+var TIMESTAMP_PATTERN2 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+var MAX_STATUS_RESPONSE_BYTES = 196608;
+var MAX_JSON_DEPTH = 32;
+var MAX_RESOURCE_ID_BYTES = 128;
+var FATAL_UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+var MUTATION_STATUSES = new Set([
+  "pending",
+  "running",
+  "succeeded",
+  "failed_retryable",
+  "failed_terminal",
+  "outcome_unknown"
+]);
+var MUTATION_RESPONSE_KEYS = ["project_ref", "mutation"];
+var MUTATION_KEYS = [
+  "project_ref",
+  "mutation_id",
+  "operation",
+  "resource_key",
+  "request_fingerprint",
+  "principal",
+  "status",
+  "checkpoint",
+  "receipt",
+  "response_status",
+  "failure_code",
+  "lease",
+  "completed_at",
+  "created_at",
+  "updated_at"
+];
+var PRINCIPAL_KEYS = ["type", "id"];
+var LEASE_KEYS = ["owner", "expires_at", "fencing_epoch"];
+function isMutationId(candidate) {
+  return typeof candidate === "string" && MUTATION_ID_PATTERN2.test(candidate);
+}
+function assertCanonicalJsonNode(candidate, seen, depth) {
+  if (candidate === null || typeof candidate === "string" || typeof candidate === "boolean")
+    return;
+  if (typeof candidate === "number" && Number.isFinite(candidate))
+    return;
+  if (typeof candidate !== "object" || depth > MAX_JSON_DEPTH) {
+    throw new Error("Mutation request must be bounded JSON");
+  }
+  if (seen.has(candidate))
+    throw new Error("Mutation request must not contain cycles");
+  seen.add(candidate);
+  const prototype = Object.getPrototypeOf(candidate);
+  const plainRecord = prototype === Object.prototype || prototype === null;
+  const children = Array.isArray(candidate) ? candidate : plainRecord ? Object.values(candidate) : null;
+  if (!children)
+    throw new Error("Mutation request must contain only JSON objects and arrays");
+  for (const child of children)
+    assertCanonicalJsonNode(child, seen, depth + 1);
+  seen.delete(candidate);
+}
+function stableStringifyNode(jsonValue) {
+  if (jsonValue === null || typeof jsonValue !== "object") {
+    const serialized = JSON.stringify(jsonValue);
+    if (serialized === undefined)
+      throw new Error("Mutation request must contain exact JSON values");
+    return serialized;
+  }
+  if (Array.isArray(jsonValue))
+    return `[${jsonValue.map(stableStringifyNode).join(",")}]`;
+  const record = jsonValue;
+  const fields = Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringifyNode(record[key])}`);
+  return `{${fields.join(",")}}`;
+}
+function mutationRequestFingerprint(normalizedRequest) {
+  assertCanonicalJsonNode(normalizedRequest, new WeakSet, 0);
+  return createHash6("sha256").update(stableStringifyNode(normalizedRequest)).digest("hex");
+}
+function objectRecord3(candidate) {
+  return candidate && typeof candidate === "object" && !Array.isArray(candidate) ? candidate : null;
+}
+function exactRecord(candidate, keys) {
+  const record = objectRecord3(candidate);
+  if (!record || Object.keys(record).length !== keys.length)
+    return null;
+  return keys.every((key) => Object.hasOwn(record, key)) ? record : null;
+}
+function emptyProjection(candidate) {
+  const record = objectRecord3(candidate);
+  return record && Object.keys(record).length === 0 ? record : null;
+}
+function canonicalTimestamp2(candidate) {
+  if (typeof candidate !== "string" || !TIMESTAMP_PATTERN2.test(candidate))
+    return false;
+  const milliseconds = Date.parse(candidate);
+  return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === candidate;
+}
+function nullableTimestamp(candidate) {
+  return candidate === null || canonicalTimestamp2(candidate);
+}
+function safePrincipal(candidate) {
+  const principal = exactRecord(candidate, PRINCIPAL_KEYS);
+  if (!principal || !["master", "admin", "project"].includes(String(principal["type"])))
+    return null;
+  if (typeof principal["id"] !== "string" || !principal["id"] || principal["id"].length > 320 || principal["id"].trim() !== principal["id"] || /[\u0000-\u001f\u007f]/u.test(principal["id"]))
+    return null;
+  return { type: principal["type"], id: principal["id"] };
+}
+function safeLease(candidate) {
+  const lease = exactRecord(candidate, LEASE_KEYS);
+  if (!lease || lease["owner"] !== null && (typeof lease["owner"] !== "string" || !LEASE_OWNER_PATTERN.test(lease["owner"])))
+    return null;
+  if (!nullableTimestamp(lease["expires_at"]) || !Number.isSafeInteger(lease["fencing_epoch"]) || Number(lease["fencing_epoch"]) < 0)
+    return null;
+  return {
+    owner: lease["owner"],
+    expires_at: lease["expires_at"],
+    fencing_epoch: Number(lease["fencing_epoch"])
+  };
+}
+function safeResponseStatus(candidate) {
+  if (candidate === null)
+    return null;
+  return Number.isInteger(candidate) && Number(candidate) >= 100 && Number(candidate) <= 599 ? Number(candidate) : undefined;
+}
+function validLeaseState(status, lease) {
+  const running = status === "running";
+  return running ? lease.owner !== null && lease.expires_at !== null && lease.fencing_epoch > 0 : lease.owner === null && lease.expires_at === null;
+}
+function validMutationLifecycle(mutation, receipt, responseStatus) {
+  const terminal = ["succeeded", "failed_terminal", "outcome_unknown"].includes(String(mutation["status"]));
+  if (mutation["completed_at"] !== null !== terminal)
+    return false;
+  if (mutation["status"] === "succeeded") {
+    return receipt !== null && responseStatus !== null && responseStatus >= 200 && responseStatus < 300 && mutation["failure_code"] === null;
+  }
+  if (mutation["status"] === "failed_terminal") {
+    return receipt !== null && typeof mutation["failure_code"] === "string";
+  }
+  if (mutation["status"] === "failed_retryable" || mutation["status"] === "outcome_unknown") {
+    return receipt !== null && typeof mutation["failure_code"] === "string";
+  }
+  if (mutation["status"] === "pending") {
+    return receipt === null && responseStatus === null && mutation["failure_code"] === null;
+  }
+  return true;
+}
+function canonicalMutationResourceKey(candidate) {
+  if (typeof candidate !== "string")
+    return false;
+  const match = RESOURCE_KEY_PATTERN.exec(candidate);
+  if (!match)
+    return false;
+  const encodedResourceId = match[1];
+  const resourceIdBytes = Buffer.from(encodedResourceId, "base64url");
+  if (resourceIdBytes.byteLength < 1 || resourceIdBytes.byteLength > MAX_RESOURCE_ID_BYTES || resourceIdBytes.toString("base64url") !== encodedResourceId)
+    return false;
+  let resourceId;
+  try {
+    resourceId = FATAL_UTF8_DECODER.decode(resourceIdBytes);
+  } catch (decodeError) {
+    if (decodeError instanceof TypeError)
+      return false;
+    throw decodeError;
+  }
+  return resourceId.trim() === resourceId && !RESOURCE_ID_CONTROL_PATTERN.test(resourceId) && Buffer.from(resourceId, "utf8").equals(resourceIdBytes);
+}
+function validMutationIdentity(mutation) {
+  if (!isMutationId(mutation["mutation_id"]) || typeof mutation["project_ref"] !== "string")
+    return false;
+  if (typeof mutation["operation"] !== "string" || !OPERATION_PATTERN.test(mutation["operation"]))
+    return false;
+  if (mutation["resource_key"] !== null && !canonicalMutationResourceKey(mutation["resource_key"]))
+    return false;
+  return typeof mutation["request_fingerprint"] === "string" && FINGERPRINT_PATTERN.test(mutation["request_fingerprint"]);
+}
+function validMutationTerminalFields(mutation) {
+  if (typeof mutation["status"] !== "string" || !MUTATION_STATUSES.has(mutation["status"]))
+    return false;
+  if (mutation["failure_code"] !== null && (typeof mutation["failure_code"] !== "string" || !FAILURE_CODE_PATTERN.test(mutation["failure_code"])))
+    return false;
+  return nullableTimestamp(mutation["completed_at"]) && canonicalTimestamp2(mutation["created_at"]) && canonicalTimestamp2(mutation["updated_at"]);
+}
+function safeMutationStatus(candidate) {
+  const mutation = exactRecord(candidate, MUTATION_KEYS);
+  if (!mutation || !validMutationIdentity(mutation) || !validMutationTerminalFields(mutation))
+    return null;
+  const principal = safePrincipal(mutation["principal"]);
+  const checkpoint = emptyProjection(mutation["checkpoint"]);
+  const receipt = mutation["receipt"] === null ? null : emptyProjection(mutation["receipt"]);
+  const responseStatus = safeResponseStatus(mutation["response_status"]);
+  const lease = safeLease(mutation["lease"]);
+  if (!principal || !checkpoint || mutation["receipt"] !== null && !receipt || responseStatus === undefined || !lease || !validLeaseState(String(mutation["status"]), lease) || !validMutationLifecycle(mutation, receipt, responseStatus))
+    return null;
+  return {
+    project_ref: mutation["project_ref"],
+    mutation_id: mutation["mutation_id"],
+    operation: mutation["operation"],
+    resource_key: mutation["resource_key"],
+    request_fingerprint: mutation["request_fingerprint"],
+    principal,
+    status: mutation["status"],
+    checkpoint,
+    receipt,
+    response_status: responseStatus,
+    failure_code: mutation["failure_code"],
+    lease,
+    completed_at: mutation["completed_at"],
+    created_at: mutation["created_at"],
+    updated_at: mutation["updated_at"]
+  };
+}
+function mutationStatusPath(ref, mutationId) {
+  if (!isMutationId(mutationId))
+    throw new Error("'mutation_id' must be a UUIDv4");
+  return `/v1/projects/${projectRefPathSegment(ref, "Mutations")}/mutations/${encodeURIComponent(mutationId)}`;
+}
+function mutationStatusResponse(ref, mutationId, payload) {
+  const response = exactRecord(payload, MUTATION_RESPONSE_KEYS);
+  const mutation = safeMutationStatus(response?.["mutation"]);
+  return response?.["project_ref"] === ref && mutation?.project_ref === ref && mutation.mutation_id === mutationId ? mutation : null;
+}
+async function fetchMutationStatus(http, ref, mutationId) {
+  const response = await http.get(mutationStatusPath(ref, mutationId), {
+    maxResponseBytes: MAX_STATUS_RESPONSE_BYTES
+  });
+  if (!response.ok) {
+    return { kind: "unavailable", httpStatus: response.transportError ? null : response.status };
+  }
+  const mutation = mutationStatusResponse(ref, mutationId, response.data);
+  return mutation ? { kind: "available", mutation } : { kind: "invalid" };
+}
+
+// src/shared/tools/application-workflow-schemas.ts
+var closed5 = { additionalProperties: false };
+var ref5 = String2({ pattern: "^[A-Za-z0-9_-]{1,20}$" });
+var uuid = ApplicationActivationIdSchema2;
+var nullableUuid = Union([uuid, Null()]);
+var nullableDigest2 = Union([ApplicationReleaseIdSchema2, Null()]);
+var timestamp2 = String2({ pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" });
+var scope2 = { project_ref: ref5, application_id: ApplicationIdSchema2, environment_id: ApplicationIdSchema2 };
+var ApplicationPromotionResultSchema = _Object_({
+  ...scope2,
+  mutation_id: uuid,
+  activation_id: uuid,
+  plan_sha256: ApplicationReleaseIdSchema2,
+  action: Literal("promote"),
+  replayed: Boolean2()
+}, closed5);
+var ApplicationPromotionStatusSchema = _Object_({
+  ...scope2,
+  mutation: Unknown(),
+  promotion: _Object_({
+    phase: Union([
+      Literal("prepared"),
+      Literal("transferring"),
+      Literal("migrating"),
+      Literal("activating"),
+      Literal("verifying"),
+      Null()
+    ]),
+    plan_sha256: nullableDigest2,
+    activation_id: nullableUuid,
+    release_id: nullableDigest2,
+    configuration_id: Union([ApplicationConfigurationIdSchema2, Null()]),
+    backup_id: Union([String2({ pattern: "^logical-full_[a-z0-9-]{1,20}_[a-f0-9]{32}$" }), Null()]),
+    data_recovery: Literal("separate-required")
+  }, closed5)
+}, closed5);
+var phase = Union([Literal("pending"), Literal("ready"), Literal("failed"), Literal("cleaned")]);
+var previewId = String2({ pattern: "^[a-f0-9-]{8,64}$" });
+var name = String2({ minLength: 1, maxLength: 256 });
+var checks = _Array_(String2({ minLength: 1, maxLength: 128 }), { maxItems: 64, uniqueItems: true });
+var ApplicationPreviewReceiptSchema = _Object_({
+  schema: Literal("supacloud.application-preview.v1"),
+  ...scope2,
+  preview_id: previewId,
+  release_id: ApplicationReleaseIdSchema2,
+  expires_at: Union([timestamp2, Null()]),
+  status: Union([
+    Literal("planned"),
+    Literal("provisioning"),
+    Literal("ready"),
+    Literal("failed"),
+    Literal("cleaned")
+  ]),
+  resources: _Object_({
+    build_artifact: _Object_({ status: phase, release_id: ApplicationReleaseIdSchema2 }, closed5),
+    database_branch: _Object_({
+      status: phase,
+      branch_ref: ref5,
+      data_mode: Union([Literal("schema_only"), Literal("full_clone")])
+    }, closed5),
+    queue_namespace: _Object_({ status: phase, namespace: name }, closed5),
+    storage_namespace: _Object_({ status: phase, namespace: name }, closed5),
+    test_secret: _Object_({ status: phase, name, value_issued: Literal(false) }, closed5),
+    configuration_revision: _Object_({ status: phase, configuration_id: Union([ApplicationConfigurationIdSchema2, Null()]) }, closed5),
+    application_activation: _Object_({ status: phase, activation_id: nullableUuid }, closed5),
+    smoke_test: _Object_({ status: phase, checks, passed: checks, failed: checks }, closed5)
+  }, closed5),
+  cleanup: _Object_({
+    required: Boolean2(),
+    completed: Boolean2(),
+    error: Union([String2({ pattern: "^[A-Z][A-Z0-9_]{0,63}$" }), Null()])
+  }, closed5),
+  branch_name: Optional(String2({ minLength: 1, maxLength: 80 })),
+  queue_name: Optional(name),
+  test_secret_name: Optional(name),
+  source_configuration_id: Optional(Union([ApplicationConfigurationIdSchema2, Null()])),
+  created_at: Optional(timestamp2),
+  updated_at: Optional(timestamp2)
+}, closed5);
+var previewListSchema = _Object_({
+  ...scope2,
+  previews: _Array_(ApplicationPreviewReceiptSchema, { maxItems: 1000 })
+}, closed5);
+function assertScope(value, identity) {
+  if (value.project_ref !== identity.project_ref || value.application_id !== identity.application_id || value.environment_id !== identity.environment_id)
+    throw new Error("Application workflow scope mismatch");
+}
+function parsePromotionStatus(value, identity) {
+  if (!Check2(ApplicationPromotionStatusSchema, value))
+    throw new Error("Invalid promotion status");
+  assertScope(value, identity);
+  const mutation = safeMutationStatus(value.mutation);
+  const resourceId = mutationRequestFingerprint({
+    applicationId: identity.application_id,
+    environmentId: identity.environment_id
+  });
+  const resourceKey = `v1/application_release/${Buffer.from(resourceId).toString("base64url")}`;
+  if (!mutation || mutation.project_ref !== identity.project_ref || mutation.mutation_id !== identity.mutation_id || mutation.operation !== "application.release.promote" || mutation.resource_key !== resourceKey || value.promotion.activation_id === identity.mutation_id) {
+    throw new Error("Invalid promotion mutation identity");
+  }
+  if (mutation.status === "succeeded" && (mutation.response_status !== 200 || mutation.receipt === null || value.promotion.phase !== "verifying" || value.promotion.activation_id === null || value.promotion.plan_sha256 === null || value.promotion.release_id === null || value.promotion.configuration_id === null || value.promotion.backup_id === null)) {
+    throw new Error("Invalid promotion success state");
+  }
+  if (value.promotion.backup_id !== null && !value.promotion.backup_id.startsWith(`logical-full_${identity.project_ref}_`)) {
+    throw new Error("Invalid promotion backup identity");
+  }
+  return structuredClone({ ...value, mutation });
+}
+function parsePreviewReceipt(value, identity) {
+  if (!Check2(ApplicationPreviewReceiptSchema, value))
+    throw new Error("Invalid preview receipt");
+  assertScope(value, identity);
+  if (identity.preview_id !== undefined && value.preview_id !== identity.preview_id || identity.release_id !== undefined && value.release_id !== identity.release_id || identity.branch_ref !== undefined && value.resources.database_branch.branch_ref !== identity.branch_ref || identity.data_mode !== undefined && value.resources.database_branch.data_mode !== identity.data_mode || identity.configuration_id !== undefined && value.source_configuration_id !== identity.configuration_id || value.resources.build_artifact.release_id !== value.release_id)
+    throw new Error("Invalid preview identity");
+  return structuredClone(value);
+}
+function parsePreviewList(value, identity) {
+  if (!Check2(previewListSchema, value))
+    throw new Error("Invalid preview list");
+  assertScope(value, identity);
+  const ids = new Set;
+  for (const item of value.previews) {
+    parsePreviewReceipt(item, identity);
+    if (ids.has(item.preview_id))
+      throw new Error("Duplicate preview identity");
+    ids.add(item.preview_id);
+  }
+  return structuredClone(value);
+}
 
 // src/shared/tools/application-release-transfer.ts
 async function applicationReleaseTransfer(http, input, project) {
@@ -187635,9 +188000,9 @@ var APPLICATION_PREVIEW_FIELDS = {
   timeout_seconds: optional(waitSecondsSchema, "[create_preview/get_preview] Observation budget with wait, from 1 to 3600 seconds (default 300)")
 };
 var strict = { additionalProperties: false };
-var phase = stringEnum(["pending", "ready", "failed", "cleaned"]);
+var phase2 = stringEnum(["pending", "ready", "failed", "cleaned"]);
 var check5 = String2({ pattern: "^[a-z][a-z0-9_]{0,63}$" });
-var checks = _Array_(check5, { maxItems: 64, uniqueItems: true });
+var checks2 = _Array_(check5, { maxItems: 64, uniqueItems: true });
 var revision = Union([ApplicationConfigurationIdSchema2, Null()]);
 var receiptSchema = _Object_({
   schema: Literal("supacloud.application-preview.v1"),
@@ -187649,14 +188014,14 @@ var receiptSchema = _Object_({
   expires_at: Union([timestampSchema, Null()]),
   status: stringEnum(["planned", "provisioning", "ready", "failed", "cleaned"]),
   resources: _Object_({
-    build_artifact: _Object_({ status: phase, release_id: ApplicationReleaseIdSchema2 }, strict),
-    database_branch: _Object_({ status: phase, branch_ref: branchRefSchema, data_mode: stringEnum(["schema_only", "full_clone"]) }, strict),
-    queue_namespace: _Object_({ status: phase, namespace: String2({ minLength: 1, maxLength: 128 }) }, strict),
-    storage_namespace: _Object_({ status: phase, namespace: branchRefSchema }, strict),
-    test_secret: _Object_({ status: phase, name: String2({ pattern: "^[A-Z0-9_-]{1,128}$" }), value_issued: Literal(false) }, strict),
-    configuration_revision: _Object_({ status: phase, configuration_id: revision }, strict),
-    application_activation: _Object_({ status: phase, activation_id: Union([previewIdSchema, Null()]) }, strict),
-    smoke_test: _Object_({ status: phase, checks, passed: checks, failed: checks }, strict)
+    build_artifact: _Object_({ status: phase2, release_id: ApplicationReleaseIdSchema2 }, strict),
+    database_branch: _Object_({ status: phase2, branch_ref: branchRefSchema, data_mode: stringEnum(["schema_only", "full_clone"]) }, strict),
+    queue_namespace: _Object_({ status: phase2, namespace: String2({ minLength: 1, maxLength: 128 }) }, strict),
+    storage_namespace: _Object_({ status: phase2, namespace: branchRefSchema }, strict),
+    test_secret: _Object_({ status: phase2, name: String2({ pattern: "^[A-Z0-9_-]{1,128}$" }), value_issued: Literal(false) }, strict),
+    configuration_revision: _Object_({ status: phase2, configuration_id: revision }, strict),
+    application_activation: _Object_({ status: phase2, activation_id: Union([previewIdSchema, Null()]) }, strict),
+    smoke_test: _Object_({ status: phase2, checks: checks2, passed: checks2, failed: checks2 }, strict)
   }, strict),
   cleanup: _Object_({
     required: Boolean2(),
@@ -187694,14 +188059,14 @@ var actionFields = {
   get_preview: ["preview_id", "wait", "timeout_seconds"],
   cleanup_preview: ["preview_id"]
 };
-function timestamp2(value) {
+function timestamp3(value) {
   return Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
 }
 function receipt(value, identity) {
   if (!Check2(receiptSchema, value) || value.project_ref !== identity.ref || value.application_id !== identity.id || value.environment_id !== identity.environment || identity.previewId && value.preview_id !== identity.previewId || value.resources.build_artifact.release_id !== value.release_id || value.resources.storage_namespace.namespace !== value.resources.database_branch.branch_ref) {
     throw new Error("Invalid preview receipt");
   }
-  if (value.expires_at !== null && !timestamp2(value.expires_at) || value.created_at !== undefined && !timestamp2(value.created_at) || value.updated_at !== undefined && !timestamp2(value.updated_at) || value.expires_at !== null && value.created_at !== undefined && !Check2(ttlSecondsSchema, (Date.parse(value.expires_at) - Date.parse(value.created_at)) / 1000)) {
+  if (value.expires_at !== null && !timestamp3(value.expires_at) || value.created_at !== undefined && !timestamp3(value.created_at) || value.updated_at !== undefined && !timestamp3(value.updated_at) || value.expires_at !== null && value.created_at !== undefined && !Check2(ttlSecondsSchema, (Date.parse(value.expires_at) - Date.parse(value.created_at)) / 1000)) {
     throw new Error("Invalid preview expiry");
   }
   if (value.status === "ready") {
@@ -187925,7 +188290,11 @@ async function applicationPreviewAction(http, args, project) {
         throw new Error;
     }
     if (preview.status === "failed" || action === "cleanup_preview" && preview.status !== "cleaned") {
-      return releaseControlFailure(operation, "MUTATION_NOT_SUCCEEDED", result.status, { ...identity, preview });
+      return releaseControlFailure(operation, "MUTATION_NOT_SUCCEEDED", result.status, {
+        ...identity,
+        preview_id: preview.preview_id,
+        preview
+      });
     }
     if (timeoutSeconds !== undefined)
       return await waitForPreview(http, path, operation, identity, preview, timeoutSeconds, startedAt);
@@ -187950,12 +188319,20 @@ var APPLICATION_TOOL_SCHEMA = {
     "get_release_transfer_plan",
     "transfer_release",
     "get_promotion_plan",
+    "promote_application",
+    "get_promotion_status",
+    "reconcile_promotion",
+    "get_preview_plan",
+    "list_previews",
+    "create_preview",
+    "get_preview",
+    "cleanup_preview",
     "activate_release",
+    "reconcile_activation",
+    "retire_activation",
     "rollback_release",
     "get_rollback_snapshot",
     "get_history",
-    "reconcile_activation",
-    "retire_activation",
     ...APPLICATION_PREVIEW_ACTIONS,
     "logs"
   ]), "Action"),
@@ -187971,6 +188348,9 @@ var APPLICATION_TOOL_SCHEMA = {
   source_ref: optional(String2({ pattern: "^[A-Za-z0-9_-]{1,20}$" }), "[get_release_transfer_plan/transfer_release] Source project ref"),
   source_release_id: optional(ApplicationReleaseIdSchema2, "[get_release_transfer_plan/transfer_release] Source immutable release ID"),
   source_environment_id: optional(ApplicationIdSchema2, "[get_promotion_plan] Source environment"),
+  mutation_id: optional(ApplicationActivationIdSchema2, "[promote_application/get_promotion_status/reconcile_promotion] Stable promotion mutation ID"),
+  approved_migration_digest: optional(ApplicationReleaseIdSchema2, "[promote_application] Exact reviewed migration execution-plan digest"),
+  plan: optional(ApplicationPromotionPlanSchema2, "[promote_application] Immutable plan returned by get_promotion_plan"),
   cursor: optional(Union([ApplicationReleaseIdSchema2, ApplicationActivationHistoryCursorSchema2]), "[list_releases/get_history] Returned page cursor"),
   limit: optional(Integer({ minimum: 1, maximum: 100 }), "[list_releases/get_history] Page size, default 50/20"),
   offset: optional(Integer({ minimum: 0, maximum: 1e6 }), "[logs] Result offset"),
@@ -187991,6 +188371,12 @@ var inventorySchema = _Object_({
   releases: _Array_(ApplicationReleaseRecordSchema2, { maxItems: 100 }),
   next_cursor: Union([ApplicationReleaseIdSchema2, Null()])
 });
+function promotionPath(project, id, environmentId) {
+  return `/v1/projects/${project}/applications/${encodeURIComponent(id)}/environments/${encodeURIComponent(environmentId)}/promotions`;
+}
+function previewPath(project, id, environmentId) {
+  return `/v1/projects/${project}/applications/${encodeURIComponent(id)}/environments/${encodeURIComponent(environmentId)}`;
+}
 function text(args, field) {
   const value = args[field];
   if (typeof value !== "string" || !value.trim())
@@ -188383,6 +188769,166 @@ function registerApplicationTools(server2, http) {
         return releaseControlFailure(operation, "INVALID_RESPONSE", result.status);
       }
     }
+    if (action === "promote_application") {
+      const environmentId = text(args, "environment_id");
+      const sourceRef = text(args, "source_ref"), sourceEnvironmentId = text(args, "source_environment_id");
+      const sourceReleaseId = text(args, "source_release_id");
+      const mutationId = text(args, "mutation_id");
+      if (!Check2(ApplicationIdSchema2, environmentId) || !/^[a-z0-9-]{1,20}$/.test(sourceRef) || !Check2(ApplicationIdSchema2, sourceEnvironmentId) || !Check2(ApplicationReleaseIdSchema2, sourceReleaseId) || !Check2(ApplicationActivationIdSchema2, mutationId)) {
+        throw new Error("Invalid promotion identity");
+      }
+      const plan = parseApplicationPromotionPlan(args["plan"]);
+      if (plan.project_ref !== ref || plan.application_id !== id || plan.environment_id !== environmentId || plan.source.project_ref !== sourceRef || plan.source.environment_id !== sourceEnvironmentId || plan.source.release_id !== sourceReleaseId || plan.action === "no-op" || plan.blockers.some((code) => !["MIGRATION_PENDING", "BACKUP_REQUIRED"].includes(code)) || plan.target.configuration_id === null) {
+        throw new Error("Promotion plan does not match the request");
+      }
+      const configurationId = text(args, "configuration_id");
+      if (configurationId !== plan.target.configuration_id)
+        throw new Error("Promotion configuration does not match the plan");
+      const identity = {
+        project_ref: ref,
+        application_id: id,
+        environment_id: environmentId,
+        mutation_id: mutationId,
+        plan_sha256: plan.plan_sha256
+      };
+      const result = await http.post(`${promotionPath(project, id, environmentId)}`, {
+        mutation_id: mutationId,
+        source_ref: sourceRef,
+        source_environment_id: sourceEnvironmentId,
+        source_release_id: sourceReleaseId,
+        configuration_id: configurationId,
+        plan,
+        ...typeof args["approved_migration_digest"] === "string" ? { approved_migration_digest: args["approved_migration_digest"] } : {}
+      }, { timeoutMs: 120000, maxJsonBytes: 65536, responseTimeoutMs: 30000 });
+      if (!result.ok)
+        return releaseControlMutationFailure(operation, result, identity);
+      try {
+        const body = result.data;
+        if (result.status !== 200 || !Check2(ApplicationPromotionResultSchema, body))
+          throw new Error;
+        if (body.project_ref !== ref || body.application_id !== id || body.environment_id !== environmentId || body.mutation_id !== mutationId || body.plan_sha256 !== plan.plan_sha256 || body.activation_id === mutationId || body.activation_id === plan.target.activation_id) {
+          throw new Error;
+        }
+        return releaseControlSuccess(operation, { ...identity, result: body });
+      } catch {
+        return releaseControlFailure(operation, "OUTCOME_UNKNOWN", result.status, identity);
+      }
+    }
+    if (action === "get_promotion_status" || action === "reconcile_promotion") {
+      const environmentId = text(args, "environment_id"), mutationId = text(args, "mutation_id");
+      if (!Check2(ApplicationIdSchema2, environmentId) || !Check2(ApplicationActivationIdSchema2, mutationId)) {
+        throw new Error("Invalid promotion identity");
+      }
+      const identity = {
+        project_ref: ref,
+        application_id: id,
+        environment_id: environmentId,
+        mutation_id: mutationId
+      };
+      const endpoint = `${promotionPath(project, id, environmentId)}/${mutationId}`;
+      const result = action === "get_promotion_status" ? await http.get(endpoint, { maxJsonBytes: 65536, responseTimeoutMs: 30000 }) : await http.post(`${endpoint}/reconcile`, {}, { timeoutMs: 120000, maxJsonBytes: 65536, responseTimeoutMs: 30000 });
+      if (!result.ok)
+        return action === "reconcile_promotion" ? releaseControlMutationFailure(operation, result, identity) : releaseControlFailure(operation, "HTTP_ERROR", result.status, identity);
+      try {
+        if (result.status !== 200)
+          throw new Error;
+        const status = parsePromotionStatus(result.data, identity);
+        if (action === "reconcile_promotion" && status.mutation.status !== "succeeded") {
+          return releaseControlFailure(operation, status.mutation.status === "outcome_unknown" ? "OUTCOME_UNKNOWN" : "MUTATION_NOT_SUCCEEDED", result.status, { ...identity, ...status });
+        }
+        return releaseControlSuccess(operation, status);
+      } catch {
+        return releaseControlFailure(operation, action === "reconcile_promotion" ? "OUTCOME_UNKNOWN" : "INVALID_RESPONSE", result.status, identity);
+      }
+    }
+    if (action === "get_preview_plan" || action === "list_previews" || action === "create_preview" || action === "get_preview" || action === "cleanup_preview") {
+      const environmentId = text(args, "environment_id");
+      if (!Check2(ApplicationIdSchema2, environmentId))
+        throw new Error("Invalid preview environment");
+      const previewId = action === "get_preview" || action === "cleanup_preview" ? text(args, "preview_id") : undefined;
+      const identity = {
+        project_ref: ref,
+        application_id: id,
+        environment_id: environmentId,
+        ...previewId === undefined ? {} : { preview_id: previewId }
+      };
+      const base = previewPath(project, id, environmentId);
+      let result;
+      let sourceRelease;
+      if (action === "get_preview_plan") {
+        if (args["configuration_id"] !== undefined) {
+          throw new Error("preview-plan only plans resource isolation; configuration_id applies to preview-create");
+        }
+        const releaseId = text(args, "release_id"), branchRef = text(args, "branch_ref");
+        if (!Check2(ApplicationReleaseIdSchema2, releaseId) || !/^[A-Za-z0-9_-]{1,20}$/.test(branchRef))
+          throw new Error("Invalid preview plan identity");
+        const query = new URLSearchParams({ release_id: releaseId, branch_ref: branchRef });
+        if (typeof args["data_mode"] === "string")
+          query.set("data_mode", args["data_mode"]);
+        result = await http.get(`${base}/preview-plan?${query}`, { maxJsonBytes: 65536, responseTimeoutMs: 30000 });
+      } else if (action === "list_previews") {
+        result = await http.get(`${base}/previews`, { maxJsonBytes: 262144, responseTimeoutMs: 30000 });
+      } else {
+        if (previewId !== undefined && !/^[a-f0-9-]{8,64}$/.test(previewId))
+          throw new Error("Invalid preview ID");
+        const endpoint = previewId === undefined ? `${base}/previews` : `${base}/previews/${previewId}`;
+        if (action === "create_preview") {
+          const releaseId = text(args, "release_id");
+          if (!Check2(ApplicationReleaseIdSchema2, releaseId))
+            throw new Error("Invalid preview release ID");
+          const source = await http.get(`${path}/${releaseId}`, { maxJsonBytes: 196608, responseTimeoutMs: 30000 });
+          if (!source.ok)
+            return releaseControlFailure(operation, "HTTP_ERROR", source.status, identity);
+          try {
+            if (source.status !== 200 || !Check2(responseSchema, source.data) || source.data.project_ref !== ref || source.data.application_id !== id)
+              throw new Error;
+            sourceRelease = boundRelease(source.data.release, ref, id);
+            if (sourceRelease.release_id !== releaseId)
+              throw new Error;
+          } catch {
+            return releaseControlFailure(operation, "INVALID_RESPONSE", source.status, identity);
+          }
+          result = await http.post(endpoint, {
+            release_id: releaseId,
+            ...typeof args["branch_name"] === "string" ? { branch_name: args["branch_name"] } : {},
+            ...typeof args["data_mode"] === "string" ? { data_mode: args["data_mode"] } : {},
+            ...typeof args["configuration_id"] === "string" ? { configuration_id: args["configuration_id"] } : {}
+          }, { timeoutMs: 120000, maxJsonBytes: 131072, responseTimeoutMs: 30000 });
+        } else if (action === "cleanup_preview") {
+          result = await http.deleteReleaseMutation(endpoint);
+        } else {
+          result = await http.get(endpoint, { maxJsonBytes: 131072, responseTimeoutMs: 30000 });
+        }
+      }
+      if (!result.ok)
+        return action === "create_preview" || action === "cleanup_preview" ? releaseControlMutationFailure(operation, result, identity) : releaseControlFailure(operation, "HTTP_ERROR", result.status, identity);
+      try {
+        if (result.status !== (action === "create_preview" ? 202 : 200))
+          throw new Error;
+        if (action === "list_previews") {
+          const list = parsePreviewList(result.data, identity);
+          return releaseControlSuccess(operation, { ...identity, previews: list.previews });
+        }
+        const preview = parsePreviewReceipt(result.data, {
+          ...identity,
+          ...typeof args["preview_id"] === "string" ? { preview_id: args["preview_id"] } : {},
+          ...action === "get_preview_plan" && typeof args["release_id"] === "string" ? { release_id: args["release_id"] } : {},
+          ...action === "get_preview_plan" && typeof args["branch_ref"] === "string" ? { branch_ref: args["branch_ref"] } : {},
+          ...action === "get_preview_plan" || action === "create_preview" ? { data_mode: String(args["data_mode"] ?? "schema_only") } : {},
+          ...action === "create_preview" && typeof args["configuration_id"] === "string" ? { configuration_id: args["configuration_id"] } : {}
+        });
+        if (action === "get_preview_plan" && preview.status !== "planned" || action === "create_preview" && preview.status !== "provisioning")
+          throw new Error;
+        if (action === "create_preview" && (!sourceRelease || preview.resources.database_branch.branch_ref !== `pv${preview.preview_id.replaceAll("-", "").slice(0, 18)}` || preview.resources.database_branch.branch_ref === ref || preview.release_id !== applicationReleaseId(preview.resources.database_branch.branch_ref, id, sourceRelease.manifest_sha256)))
+          throw new Error;
+        if (action === "cleanup_preview" && (preview.status !== "cleaned" || !preview.cleanup.completed || preview.cleanup.required)) {
+          return releaseControlFailure(operation, "MUTATION_NOT_SUCCEEDED", result.status, { ...identity, preview });
+        }
+        return releaseControlSuccess(operation, { ...identity, preview });
+      } catch {
+        return releaseControlFailure(operation, action === "create_preview" || action === "cleanup_preview" ? "OUTCOME_UNKNOWN" : "INVALID_RESPONSE", result.status, identity);
+      }
+    }
     if (action === "logs") {
       const environmentId = text(args, "environment_id");
       if (!Check2(ApplicationIdSchema2, environmentId))
@@ -188559,7 +189105,7 @@ function matchingText(candidate, maxLength, pattern) {
   const candidateText = boundedText2(candidate, maxLength);
   return candidateText && pattern.test(candidateText) ? candidateText : null;
 }
-function canonicalTimestamp2(candidate) {
+function canonicalTimestamp3(candidate) {
   const timestamp = boundedText2(candidate, 64);
   if (!timestamp)
     return null;
@@ -188574,7 +189120,7 @@ function projectedSummary(project) {
     organization_slug: matchingText(project.organization_slug, 128, SAFE_IDENTIFIER_PATTERN),
     name: boundedText2(project.name, 100),
     region: matchingText(project.region, 64, REGION_PATTERN),
-    created_at: canonicalTimestamp2(project.created_at),
+    created_at: canonicalTimestamp3(project.created_at),
     status: matchingText(project.status, 64, STATUS_PATTERN)
   };
   return Object.values(summary).every((field) => field !== null) ? summary : null;
@@ -194568,6 +195114,13 @@ var REMOTE_APP_ACTIONS = {
   upload: "upload_release",
   "transfer-plan": "get_release_transfer_plan",
   "promote-plan": "get_promotion_plan",
+  "promote-status": "get_promotion_status",
+  "promote-reconcile": "reconcile_promotion",
+  "preview-plan": "get_preview_plan",
+  "preview-list": "list_previews",
+  "preview-create": "create_preview",
+  "preview-status": "get_preview",
+  "preview-cleanup": "cleanup_preview",
   transfer: "transfer_release",
   configure: "put_configuration",
   deploy: "deploy_release",
@@ -194580,36 +195133,35 @@ var REMOTE_APP_ACTIONS = {
   reconcile: "reconcile_activation",
   retire: "retire_activation",
   logs: "logs",
-  "preview-plan": "get_preview_plan",
   preview: "create_preview",
-  previews: "list_previews",
-  "preview-status": "get_preview",
-  "preview-cleanup": "cleanup_preview"
+  previews: "list_previews"
 };
 var REMOTE_APP_DESCRIPTIONS = {
-  ref: "[upload/configure/transfer-plan/transfer/promote-plan/deploy/deploy-plan/diff/status/rollback/rollback-plan/history/reconcile/retire/preview-plan/preview/previews/preview-status/preview-cleanup] Project ref (defaults to context)",
-  id: "[upload/configure/transfer-plan/transfer/promote-plan/deploy/deploy-plan/diff/status/rollback/rollback-plan/history/reconcile/retire/preview-plan/preview/previews/preview-status/preview-cleanup] Application ID",
-  environment_id: "[configure/promote-plan/deploy/deploy-plan/diff/status/rollback/rollback-plan/history/reconcile/retire/preview-plan/preview/previews/preview-status/preview-cleanup] Target environment ID",
-  configuration_id: "[promote-plan/deploy/deploy-plan/diff/rollback/preview] Immutable target configuration revision; required for deployment/preview; platform selects for default rollback",
-  activation_id: "[deploy/rollback/reconcile/retire] Stable activation ID; auto-generated for deploy/rollback if omitted",
-  expected_activation_id: "[deploy/rollback] Auto-selected from verified state; supply with activation_id for an exact retry",
+  ref: "[upload/configure/transfer-plan/transfer/promote-plan/diff/promote/promote-status/promote-reconcile/preview-plan/preview/previews/preview-list/preview-create/preview-status/preview-cleanup/deploy/deploy-plan/status/rollback/rollback-plan/history/reconcile/retire] Project ref (defaults to context)",
+  id: "[upload/configure/transfer-plan/transfer/promote-plan/diff/promote/promote-status/promote-reconcile/preview-plan/preview/previews/preview-list/preview-create/preview-status/preview-cleanup/deploy/deploy-plan/status/rollback/rollback-plan/history/reconcile/retire] Application ID",
+  environment_id: "[configure/promote-plan/diff/promote/promote-status/promote-reconcile/preview-plan/preview/previews/preview-list/preview-create/preview-status/preview-cleanup/deploy/deploy-plan/status/rollback/rollback-plan/history/reconcile/retire] Target environment ID",
+  configuration_id: "[promote-plan/diff/promote/preview-plan/preview/preview-create/deploy/deploy-plan/rollback] Immutable target configuration revision",
+  activation_id: "[deploy/rollback/reconcile/retire] Required explicit activation ID",
+  expected_activation_id: "[deploy/rollback] Required current activation ID, or absent for first activation",
   configuration_path: "[configure] Configuration write JSON including revision and expected revision",
   manifest_path: "[upload] Local delivery.manifest.json",
-  release_id: "[deploy/deploy-plan/diff/rollback/reconcile/preview-plan/preview] Required for deployment/preview; defaults to journal-selected previous for rollback",
-  source_ref: "[transfer-plan/transfer/promote-plan] Source project ref",
-  source_release_id: "[transfer-plan/transfer/promote-plan] Source immutable release ID",
-  source_environment_id: "[promote-plan] Source environment ID",
-  preview_id: "[preview-status/preview-cleanup] Preview receipt ID",
-  branch_ref: "[preview-plan] Proposed branch ref; preview assigns its own",
-  branch_name: "[preview] Branch display name",
-  data_mode: "[preview-plan/preview] Default schema_only; full_clone copies rows",
-  ttl_seconds: "[preview-plan/preview] Lifetime from 300 to 604800 seconds; creation defaults to the platform TTL",
-  wait: "[preview/preview-status] Wait for verified readiness of the selected preview",
-  timeout_seconds: "[preview/preview-status] Observation budget with --wait, from 1 to 3600 seconds (default 300)",
+  release_id: "[preview-plan/preview/preview-create/deploy/deploy-plan/diff/rollback/reconcile] Required immutable application release ID",
+  source_ref: "[transfer-plan/transfer/promote-plan/diff/promote] Source project ref",
+  source_release_id: "[transfer-plan/transfer/promote-plan/diff/promote] Source immutable release ID",
+  source_environment_id: "[promote-plan/diff/promote] Source environment ID",
+  mutation_id: "[promote-status/promote-reconcile] Stable promotion mutation ID",
+  approved_migration_digest: "[promote] Exact reviewed migration execution-plan digest",
+  branch_ref: "[preview-plan] Preview branch identity",
+  branch_name: "[preview/preview-create] Human-readable preview branch name",
+  data_mode: "[preview-plan/preview/preview-create] schema_only or full_clone",
+  ttl_seconds: "[preview-plan/preview/preview-create] Lifetime from 300 to 604800 seconds; creation defaults to the platform TTL",
+  wait: "[preview/preview-create/preview-status] Wait for verified readiness of the selected preview",
+  timeout_seconds: "[preview/preview-create/preview-status] Observation budget with --wait, from 1 to 3600 seconds (default 300)",
+  preview_id: "[preview-status/preview-cleanup] Preview ID",
   cursor: "[history] Returned page cursor",
   limit: "[history] Page size, default 20 (1-100)"
 };
-var { action: _remoteAction, ...remoteFields } = APPLICATION_TOOL_SCHEMA;
+var { action: _remoteAction, plan: _remotePlan, ...remoteFields } = APPLICATION_TOOL_SCHEMA;
 var REMOTE_APP_SCHEMA = Partial(_Object_(remoteFields)).properties;
 for (const [name, schema] of Object.entries(REMOTE_APP_SCHEMA)) {
   const description = REMOTE_APP_DESCRIPTIONS[name];
@@ -195599,6 +196151,167 @@ function formatRemoteDeployPlan(result) {
     return result;
   }
 }
+function formatPromotionPlan2(result) {
+  if (result.isError)
+    return result;
+  try {
+    const payload = JSON.parse(result.content[0]?.text ?? "");
+    if (!payload || typeof payload !== "object" || !("plan" in payload))
+      return result;
+    const plan = parseApplicationPromotionPlan(payload.plan);
+    return textResult([
+      `${plan.project_ref}/${plan.application_id}/${plan.environment_id}: ${plan.action}`,
+      `Source: ${plan.source.project_ref}/${plan.source.environment_id}`,
+      ...plan.blockers.length ? [`Blocked: ${plan.blockers.join(", ")}`] : [],
+      ...plan.steps.length ? [`Next: ${plan.steps.join(" -> ")}`] : [],
+      "Execution: not performed"
+    ].join(`
+`));
+  } catch {
+    return result;
+  }
+}
+function formatPromotionExecution(result) {
+  if (result.isError)
+    return result;
+  try {
+    const payload = JSON.parse(result.content[0]?.text ?? "");
+    if (!payload || typeof payload !== "object")
+      return result;
+    const operation = "operation" in payload && typeof payload.operation === "string" ? payload.operation : "";
+    if (operation !== "applications.promote_application")
+      return result;
+    if ("result" in payload && Check2(ApplicationPromotionResultSchema, payload.result)) {
+      const envelope = payload;
+      const receipt = payload.result;
+      if (receipt.project_ref !== envelope.project_ref || receipt.application_id !== envelope.application_id || receipt.environment_id !== envelope.environment_id || receipt.mutation_id !== envelope.mutation_id || receipt.plan_sha256 !== envelope.plan_sha256)
+        return result;
+      return textResult([
+        `${String(envelope.project_ref)}/${String(envelope.application_id)}/${String(envelope.environment_id)}: promoted`,
+        `Mutation: ${String(envelope.mutation_id)}`,
+        `Activation: ${String(receipt.activation_id)}`,
+        `Replayed: ${String(receipt.replayed)}`
+      ].join(`
+`));
+    }
+  } catch {}
+  return result;
+}
+function formatWorkflowObservation(result, action) {
+  if (result.isError)
+    return result;
+  try {
+    const payload = JSON.parse(result.content[0]?.text ?? "");
+    if (!payload || typeof payload !== "object")
+      return result;
+    const data = payload;
+    if (typeof data.project_ref !== "string" || typeof data.application_id !== "string" || typeof data.environment_id !== "string")
+      return result;
+    const identity = {
+      project_ref: data.project_ref,
+      application_id: data.application_id,
+      environment_id: data.environment_id
+    };
+    const label = `${identity.project_ref}/${identity.application_id}/${identity.environment_id}`;
+    if (action === "promote-status" || action === "promote-reconcile") {
+      if (!data.mutation || typeof data.mutation !== "object" || !("mutation_id" in data.mutation) || typeof data.mutation.mutation_id !== "string")
+        return result;
+      const status = parsePromotionStatus({ ...identity, mutation: data.mutation, promotion: data.promotion }, { ...identity, mutation_id: data.mutation.mutation_id });
+      return textResult([
+        `${label}: ${status.mutation.status}`,
+        `Mutation: ${status.mutation.mutation_id}`,
+        `Phase: ${status.promotion.phase ?? "not recorded"}`,
+        ...status.promotion.backup_id ? [`Backup: ${status.promotion.backup_id}`] : []
+      ].join(`
+`));
+    }
+    if (action === "preview-list") {
+      const list = parsePreviewList({ ...identity, previews: data.previews }, identity);
+      return textResult([
+        `${label}: ${list.previews.length} preview(s)`,
+        ...list.previews.map((preview) => `${preview.preview_id}  ${preview.status}  ${preview.resources.database_branch.branch_ref}`)
+      ].join(`
+`));
+    }
+    if (["preview-create", "preview-status", "preview-cleanup"].includes(action)) {
+      const preview = parsePreviewReceipt(data.preview, identity);
+      return textResult([
+        `${label}: ${preview.status}`,
+        `Preview: ${preview.preview_id}`,
+        `Branch: ${preview.resources.database_branch.branch_ref} (${preview.resources.database_branch.data_mode})`,
+        `Cleanup: ${preview.cleanup.completed ? "completed" : preview.cleanup.required ? "required" : "not required"}`
+      ].join(`
+`));
+    }
+  } catch {}
+  return result;
+}
+async function runPromotion(request, options, delegate) {
+  const ref = request.ref ?? options.projectRef;
+  if (request.mutation_id !== undefined)
+    throw new Error("app promote generates a new mutation ID; use promote-status or promote-reconcile to inspect an existing mutation");
+  const { format, json, ...remoteRequest } = request;
+  const planArgs = {
+    ...remoteRequest,
+    action: "get_promotion_plan",
+    ref
+  };
+  validateToolArguments(APPLICATION_TOOL_SCHEMA, planArgs);
+  const planned = await delegate(planArgs);
+  if (planned.isError)
+    return planned;
+  let payload;
+  try {
+    payload = JSON.parse(planned.content[0]?.text ?? "");
+  } catch {
+    return textResult("Promotion plan response was not valid JSON.", true);
+  }
+  if (!payload || typeof payload !== "object" || !("plan" in payload)) {
+    return textResult("Promotion plan response was invalid.", true);
+  }
+  let plan;
+  try {
+    plan = parseApplicationPromotionPlan(payload.plan);
+  } catch {
+    return textResult("Promotion plan failed immutable validation.", true);
+  }
+  const identity = { project_ref: ref, application_id: request.id, environment_id: request.environment_id };
+  if (plan.project_ref !== ref || plan.application_id !== request.id || plan.environment_id !== request.environment_id || plan.source.project_ref !== request.source_ref || plan.source.environment_id !== request.source_environment_id || plan.source.release_id !== request.source_release_id || request.configuration_id !== undefined && plan.target.configuration_id !== request.configuration_id) {
+    return releaseControlFailure("applications.promote_application", "INVALID_RESPONSE", null, identity);
+  }
+  if (plan.action === "no-op") {
+    const noOp = releaseControlSuccess("applications.promote_application", {
+      project_ref: plan.project_ref,
+      application_id: plan.application_id,
+      environment_id: plan.environment_id,
+      plan,
+      no_op: true,
+      execution_performed: false
+    });
+    return format === "json" || json ? noOp : textResult(`${plan.project_ref}/${plan.application_id}/${plan.environment_id}: no-op
+Execution: skipped`);
+  }
+  if (plan.blockers.some((code) => !["MIGRATION_PENDING", "BACKUP_REQUIRED"].includes(code))) {
+    return releaseControlFailure("applications.promote_application", "MUTATION_NOT_SUCCEEDED", null, { ...identity, plan, execution_performed: false });
+  }
+  if (!plan.target.configuration_id)
+    return textResult("Promotion plan has no target configuration revision.", true);
+  const mutationId = crypto.randomUUID();
+  const executeArgs = {
+    ...remoteRequest,
+    action: "promote_application",
+    ref,
+    mutation_id: mutationId,
+    source_ref: plan.source.project_ref,
+    source_environment_id: plan.source.environment_id,
+    source_release_id: plan.source.release_id,
+    configuration_id: plan.target.configuration_id,
+    plan
+  };
+  validateToolArguments(APPLICATION_TOOL_SCHEMA, executeArgs);
+  const result = await delegate(executeArgs);
+  return format === "json" || json ? result : formatPromotionExecution(result);
+}
 async function runAppTool(request, options = {}) {
   if (request.dry_run !== undefined && request["dry-run"] !== undefined || request.register_in !== undefined && request["register-in"] !== undefined || request.database_url !== undefined && request["database-url"] !== undefined) {
     throw new ScaffoldError("SCAFFOLD_OPTION_INVALID", "Do not combine hyphenated and underscored aliases of the same flag");
@@ -195615,16 +196328,22 @@ async function runAppTool(request, options = {}) {
   if (request.database_url !== undefined && request.action !== "dev" && request.action !== "watch") {
     throw new ScaffoldError("SCAFFOLD_OPTION_INVALID", "--database-url applies only to app dev --profile integration");
   }
-  if (request.json !== undefined && request.action !== "history" && request.action !== "transfer-plan" && request.action !== "transfer" && request.action !== "promote-plan") {
-    throw new Error("--json applies only to app history, transfer-plan, transfer or promote-plan");
-  }
-  if (request.json !== undefined && request.format === "text")
+  if (request.json !== undefined && !Object.hasOwn(REMOTE_APP_ACTIONS, request.action) && request.action !== "promote")
+    throw new Error("--json applies only to remote app actions");
+  if (request.json && request.format === "text")
     throw new Error("--json and --format text cannot be combined");
+  if (request.action === "promote") {
+    const delegate = options.getApplications?.();
+    if (!delegate)
+      return textResult("App remote actions require a Management API context.", true);
+    return runPromotion(request, options, delegate);
+  }
   if (Object.hasOwn(REMOTE_APP_ACTIONS, request.action)) {
     const delegate = options.getApplications?.();
     if (!delegate)
       return textResult("App remote actions require a Management API context.", true);
-    const action = REMOTE_APP_ACTIONS[request.action];
+    const promotionDiff = request.action === "diff" && request.source_ref !== undefined && request.source_environment_id !== undefined && request.source_release_id !== undefined;
+    const action = promotionDiff ? "get_promotion_plan" : REMOTE_APP_ACTIONS[request.action];
     const { format, json, ...remoteRequest } = request;
     const args = {
       ...remoteRequest,
@@ -195636,24 +196355,14 @@ async function runAppTool(request, options = {}) {
     if (request.action === "history" && format !== "json" && json !== true) {
       return historyText(result, request, args.ref);
     }
-    if ((request.action === "deploy-plan" || request.action === "diff") && format !== "json") {
+    if ((request.action === "deploy-plan" || request.action === "diff") && format !== "json" && (request.action === "deploy-plan" || request.source_ref === undefined || request.source_environment_id === undefined || request.source_release_id === undefined)) {
       return formatRemoteDeployPlan(result);
     }
-    if (request.action === "promote-plan" && !result.isError && format !== "json" && !json) {
-      const payload = JSON.parse(result.content[0]?.text ?? "");
-      if (!payload || typeof payload !== "object" || !("plan" in payload))
-        return result;
-      const plan = parseApplicationPromotionPlan(payload.plan);
-      return textResult([
-        `${plan.project_ref}/${plan.application_id}/${plan.environment_id}: ${plan.action}`,
-        `Source: ${plan.source.project_ref}/${plan.source.environment_id}`,
-        ...plan.blockers.length ? [`Blocked: ${plan.blockers.join(", ")}`] : [],
-        ...plan.steps.length ? [`Next: ${plan.steps.join(" -> ")}`] : [],
-        "Execution: not performed"
-      ].join(`
-`));
+    if (request.action === "promote-plan" || request.action === "diff" && request.source_ref !== undefined && request.source_environment_id !== undefined && request.source_release_id !== undefined) {
+      if (!result.isError && format !== "json" && !json)
+        return formatPromotionPlan2(result);
     }
-    return (request.action === "transfer-plan" || request.action === "transfer") && format !== "json" && !json ? formatReleaseTransfer(result) : result;
+    return (request.action === "transfer-plan" || request.action === "transfer") && format !== "json" && !json ? formatReleaseTransfer(result) : format !== "json" && !json ? formatWorkflowObservation(result, request.action) : result;
   }
   switch (request.action) {
     case "verify-plan": {
@@ -195743,9 +196452,14 @@ function registerAppTools(server2, options = {}) {
       "preview-plan",
       "preview",
       "previews",
+      "preview-list",
+      "preview-create",
       "preview-status",
-      "preview-cleanup"
-    ]), "App action; transfer reuses a verified release without build or activation; local plan is topology-only, deploy-plan/diff observe remote state, deploy skips verified no-op, rollback never downgrades schema"),
+      "preview-cleanup",
+      "promote",
+      "promote-status",
+      "promote-reconcile"
+    ]), "App action; promote obtains and verifies its plan before one mutation request"),
     kind: optional(stringEnum(["module", "command", "query", "controller", "job", "contract", "resource"]), "[generate] Scaffold kind"),
     template: optional(stringEnum(["minimal", "http", "command", "edge"]), "[init] Minimal application by default; explicit http/command/edge recipes"),
     name: optional(String2(), "[init/generate] Project or object name"),
@@ -195803,7 +196517,7 @@ import { existsSync as existsSync13 } from "node:fs";
 import { join as join17, resolve as resolve21 } from "node:path";
 
 // src/shared/tools/db-workflow.ts
-import { createHash as createHash6 } from "node:crypto";
+import { createHash as createHash7 } from "node:crypto";
 import { lstat as lstat4, mkdir as mkdir7, mkdtemp, readFile as readFile6, readdir as readdir7, rename as rename3, rm as rm2, writeFile as writeFile6 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
 import { dirname as dirname10, isAbsolute as isAbsolute7, join as join16, relative as relative9, resolve as resolve20 } from "node:path";
@@ -195869,7 +196583,7 @@ function parseDatabaseSourcesConfig(value) {
 }
 
 // src/shared/tools/db-workflow.ts
-var hash3 = (content) => createHash6("sha256").update(content).digest("hex");
+var hash3 = (content) => createHash7("sha256").update(content).digest("hex");
 var result = (value, isError = false) => ({
   isError,
   content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -196558,7 +197272,7 @@ function parseHeaderEnvironment(input) {
   }
 }
 var headerEnvironmentSchema = Optional(decodedSchema(Union([String2(), headerEnvironmentRecord]), headerEnvironmentRecord, parseHeaderEnvironment));
-function objectRecord3(candidate) {
+function objectRecord4(candidate) {
   return candidate && typeof candidate === "object" && !Array.isArray(candidate) ? candidate : null;
 }
 function boundedCronInteger(input, minimum, maximum) {
@@ -196603,7 +197317,7 @@ function readScheduleBodyFile(bodyPathInput) {
       throw error;
     throw new Error("Scheduled Function body file must contain exact JSON");
   }
-  const body = objectRecord3(payload);
+  const body = objectRecord4(payload);
   if (!body)
     throw new Error("Scheduled Function body file must contain a JSON object");
   return body;
@@ -196644,7 +197358,7 @@ function headerValueIsStable(name, value) {
 function scheduleHeaders(mapping, environment) {
   if (mapping === undefined)
     return;
-  const headerEnvironment = objectRecord3(mapping);
+  const headerEnvironment = objectRecord4(mapping);
   if (!headerEnvironment)
     throw new Error("'header_env' must be a JSON object");
   const entries = Object.entries(headerEnvironment).map(([headerName, environmentName]) => resolvedHeaderEntry(headerName, environmentName, environment));
@@ -196685,8 +197399,8 @@ function safeSchedulePayload(schedule) {
   return { body_empty: schedule.body_empty, header_names: headerNames };
 }
 function legacySchedulePayload(schedule) {
-  const body = objectRecord3(schedule.body);
-  const headers = objectRecord3(schedule.headers);
+  const body = objectRecord4(schedule.body);
+  const headers = objectRecord4(schedule.headers);
   if (!body || !headers)
     return null;
   const headerNames = safeHeaderNames(Object.keys(headers));
@@ -196703,7 +197417,7 @@ function safeHeaderNames(candidate) {
   return valid && new Set(names).size === names.length ? names.sort() : null;
 }
 function safeSchedule(candidate) {
-  const schedule = objectRecord3(candidate);
+  const schedule = objectRecord4(candidate);
   if (!schedule || !validSafeSchedule(schedule))
     return null;
   const safePayload = safeSchedulePayload(schedule);
@@ -196749,7 +197463,7 @@ function listResponse(ref, response) {
   const operation = "scheduled_functions.list";
   if (!response.ok)
     return scheduleFailure(operation, response);
-  const payload = objectRecord3(response.data);
+  const payload = objectRecord4(response.data);
   const rawSchedules = payload?.schedules;
   const schedules = Array.isArray(rawSchedules) ? rawSchedules.map(safeSchedule) : null;
   if (payload?.project_ref !== ref || !schedules || schedules.some((schedule) => !schedule)) {
@@ -196764,7 +197478,7 @@ function getResponse(ref, scheduleId, response) {
   const operation = "scheduled_functions.get";
   if (!response.ok)
     return scheduleFailure(operation, response);
-  const payload = objectRecord3(response.data);
+  const payload = objectRecord4(response.data);
   const schedule = safeSchedule(payload?.schedule);
   if (payload?.project_ref !== ref || !schedule || schedule.id !== scheduleId) {
     return releaseControlFailure(operation, "INVALID_RESPONSE", null);
@@ -196777,7 +197491,7 @@ function mutationResponse(expectation, response) {
   const operation = `scheduled_functions.${action}`;
   if (!response.ok)
     return releaseControlMutationFailure(operation, response);
-  const payload = objectRecord3(response.data);
+  const payload = objectRecord4(response.data);
   const schedule = safeSchedule(payload?.schedule);
   const confirmsRequest = schedule && Object.entries(expectedFields).every(([field, expected]) => isDeepStrictEqual(schedule[field], expected));
   const confirmsRevision = action === "create" || payload?.previous_updated_at === expectation.expectedUpdatedAt && schedule !== null && schedule.updated_at > expectation.expectedUpdatedAt;
@@ -196795,7 +197509,7 @@ function deleteResponse(ref, scheduleId, expectedUpdatedAt, response) {
   const operation = "scheduled_functions.delete";
   if (!response.ok)
     return releaseControlMutationFailure(operation, response);
-  const payload = objectRecord3(response.data);
+  const payload = objectRecord4(response.data);
   if (payload?.deleted !== true || payload.project_ref !== ref || payload.schedule_id !== scheduleId || payload.deleted_updated_at !== expectedUpdatedAt) {
     return releaseControlFailure(operation, "OUTCOME_UNKNOWN", response.status);
   }
@@ -196935,204 +197649,6 @@ var SCHEDULE_TOOL_SCHEMA = {
   header_env: withDescription(headerEnvironmentSchema, "[create/update] JSON map of HTTP header names to environment variable names")
 };
 
-// src/shared/mutation-protocol.ts
-var MUTATION_ID_PATTERN2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-var FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
-var OPERATION_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,127}$/;
-var RESOURCE_KEY_PATTERN = /^v1\/(?:[a-z0-9][a-z0-9._-]{0,63})\/([A-Za-z0-9_-]{2,171})$/;
-var RESOURCE_ID_CONTROL_PATTERN = /[\u0000-\u001f\u007f-\u009f]/u;
-var FAILURE_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
-var LEASE_OWNER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,254}$/;
-var TIMESTAMP_PATTERN2 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
-var MAX_STATUS_RESPONSE_BYTES = 196608;
-var MAX_RESOURCE_ID_BYTES = 128;
-var FATAL_UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
-var MUTATION_STATUSES = new Set([
-  "pending",
-  "running",
-  "succeeded",
-  "failed_retryable",
-  "failed_terminal",
-  "outcome_unknown"
-]);
-var MUTATION_RESPONSE_KEYS = ["project_ref", "mutation"];
-var MUTATION_KEYS = [
-  "project_ref",
-  "mutation_id",
-  "operation",
-  "resource_key",
-  "request_fingerprint",
-  "principal",
-  "status",
-  "checkpoint",
-  "receipt",
-  "response_status",
-  "failure_code",
-  "lease",
-  "completed_at",
-  "created_at",
-  "updated_at"
-];
-var PRINCIPAL_KEYS = ["type", "id"];
-var LEASE_KEYS = ["owner", "expires_at", "fencing_epoch"];
-function isMutationId(candidate) {
-  return typeof candidate === "string" && MUTATION_ID_PATTERN2.test(candidate);
-}
-function objectRecord4(candidate) {
-  return candidate && typeof candidate === "object" && !Array.isArray(candidate) ? candidate : null;
-}
-function exactRecord(candidate, keys) {
-  const record = objectRecord4(candidate);
-  if (!record || Object.keys(record).length !== keys.length)
-    return null;
-  return keys.every((key) => Object.hasOwn(record, key)) ? record : null;
-}
-function emptyProjection(candidate) {
-  const record = objectRecord4(candidate);
-  return record && Object.keys(record).length === 0 ? record : null;
-}
-function canonicalTimestamp3(candidate) {
-  if (typeof candidate !== "string" || !TIMESTAMP_PATTERN2.test(candidate))
-    return false;
-  const milliseconds = Date.parse(candidate);
-  return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === candidate;
-}
-function nullableTimestamp(candidate) {
-  return candidate === null || canonicalTimestamp3(candidate);
-}
-function safePrincipal(candidate) {
-  const principal = exactRecord(candidate, PRINCIPAL_KEYS);
-  if (!principal || !["master", "admin", "project"].includes(String(principal.type)))
-    return null;
-  if (typeof principal.id !== "string" || !principal.id || principal.id.length > 320 || principal.id.trim() !== principal.id || /[\u0000-\u001f\u007f]/u.test(principal.id))
-    return null;
-  return { type: principal.type, id: principal.id };
-}
-function safeLease(candidate) {
-  const lease = exactRecord(candidate, LEASE_KEYS);
-  if (!lease || lease.owner !== null && (typeof lease.owner !== "string" || !LEASE_OWNER_PATTERN.test(lease.owner)))
-    return null;
-  if (!nullableTimestamp(lease.expires_at) || !Number.isSafeInteger(lease.fencing_epoch) || Number(lease.fencing_epoch) < 0)
-    return null;
-  return {
-    owner: lease.owner,
-    expires_at: lease.expires_at,
-    fencing_epoch: Number(lease.fencing_epoch)
-  };
-}
-function safeResponseStatus(candidate) {
-  if (candidate === null)
-    return null;
-  return Number.isInteger(candidate) && Number(candidate) >= 100 && Number(candidate) <= 599 ? Number(candidate) : undefined;
-}
-function validLeaseState(status, lease) {
-  const running = status === "running";
-  return running ? lease.owner !== null && lease.expires_at !== null && lease.fencing_epoch > 0 : lease.owner === null && lease.expires_at === null;
-}
-function validMutationLifecycle(mutation, receipt, responseStatus) {
-  const terminal = ["succeeded", "failed_terminal", "outcome_unknown"].includes(String(mutation.status));
-  if (mutation.completed_at !== null !== terminal)
-    return false;
-  if (mutation.status === "succeeded") {
-    return receipt !== null && responseStatus !== null && responseStatus >= 200 && responseStatus < 300 && mutation.failure_code === null;
-  }
-  if (mutation.status === "failed_terminal") {
-    return receipt !== null && typeof mutation.failure_code === "string";
-  }
-  if (mutation.status === "failed_retryable" || mutation.status === "outcome_unknown") {
-    return receipt !== null && typeof mutation.failure_code === "string";
-  }
-  if (mutation.status === "pending") {
-    return receipt === null && responseStatus === null && mutation.failure_code === null;
-  }
-  return true;
-}
-function canonicalMutationResourceKey(candidate) {
-  if (typeof candidate !== "string")
-    return false;
-  const match = RESOURCE_KEY_PATTERN.exec(candidate);
-  if (!match)
-    return false;
-  const encodedResourceId = match[1];
-  const resourceIdBytes = Buffer.from(encodedResourceId, "base64url");
-  if (resourceIdBytes.byteLength < 1 || resourceIdBytes.byteLength > MAX_RESOURCE_ID_BYTES || resourceIdBytes.toString("base64url") !== encodedResourceId)
-    return false;
-  let resourceId;
-  try {
-    resourceId = FATAL_UTF8_DECODER.decode(resourceIdBytes);
-  } catch (decodeError) {
-    if (decodeError instanceof TypeError)
-      return false;
-    throw decodeError;
-  }
-  return resourceId.trim() === resourceId && !RESOURCE_ID_CONTROL_PATTERN.test(resourceId) && Buffer.from(resourceId, "utf8").equals(resourceIdBytes);
-}
-function validMutationIdentity(mutation) {
-  if (!isMutationId(mutation.mutation_id) || typeof mutation.project_ref !== "string")
-    return false;
-  if (typeof mutation.operation !== "string" || !OPERATION_PATTERN.test(mutation.operation))
-    return false;
-  if (mutation.resource_key !== null && !canonicalMutationResourceKey(mutation.resource_key))
-    return false;
-  return typeof mutation.request_fingerprint === "string" && FINGERPRINT_PATTERN.test(mutation.request_fingerprint);
-}
-function validMutationTerminalFields(mutation) {
-  if (typeof mutation.status !== "string" || !MUTATION_STATUSES.has(mutation.status))
-    return false;
-  if (mutation.failure_code !== null && (typeof mutation.failure_code !== "string" || !FAILURE_CODE_PATTERN.test(mutation.failure_code)))
-    return false;
-  return nullableTimestamp(mutation.completed_at) && canonicalTimestamp3(mutation.created_at) && canonicalTimestamp3(mutation.updated_at);
-}
-function safeMutationStatus(candidate) {
-  const mutation = exactRecord(candidate, MUTATION_KEYS);
-  if (!mutation || !validMutationIdentity(mutation) || !validMutationTerminalFields(mutation))
-    return null;
-  const principal = safePrincipal(mutation.principal);
-  const checkpoint = emptyProjection(mutation.checkpoint);
-  const receipt = mutation.receipt === null ? null : emptyProjection(mutation.receipt);
-  const responseStatus = safeResponseStatus(mutation.response_status);
-  const lease = safeLease(mutation.lease);
-  if (!principal || !checkpoint || mutation.receipt !== null && !receipt || responseStatus === undefined || !lease || !validLeaseState(String(mutation.status), lease) || !validMutationLifecycle(mutation, receipt, responseStatus))
-    return null;
-  return {
-    project_ref: mutation.project_ref,
-    mutation_id: mutation.mutation_id,
-    operation: mutation.operation,
-    resource_key: mutation.resource_key,
-    request_fingerprint: mutation.request_fingerprint,
-    principal,
-    status: mutation.status,
-    checkpoint,
-    receipt,
-    response_status: responseStatus,
-    failure_code: mutation.failure_code,
-    lease,
-    completed_at: mutation.completed_at,
-    created_at: mutation.created_at,
-    updated_at: mutation.updated_at
-  };
-}
-function mutationStatusPath(ref, mutationId) {
-  if (!isMutationId(mutationId))
-    throw new Error("'mutation_id' must be a UUIDv4");
-  return `/v1/projects/${projectRefPathSegment(ref, "Mutations")}/mutations/${encodeURIComponent(mutationId)}`;
-}
-function mutationStatusResponse(ref, mutationId, payload) {
-  const response = exactRecord(payload, MUTATION_RESPONSE_KEYS);
-  const mutation = safeMutationStatus(response?.mutation);
-  return response?.project_ref === ref && mutation?.project_ref === ref && mutation.mutation_id === mutationId ? mutation : null;
-}
-async function fetchMutationStatus(http, ref, mutationId) {
-  const response = await http.get(mutationStatusPath(ref, mutationId), {
-    maxResponseBytes: MAX_STATUS_RESPONSE_BYTES
-  });
-  if (!response.ok) {
-    return { kind: "unavailable", httpStatus: response.transportError ? null : response.status };
-  }
-  const mutation = mutationStatusResponse(ref, mutationId, response.data);
-  return mutation ? { kind: "available", mutation } : { kind: "invalid" };
-}
-
 // src/shared/tools/mutation-tools.ts
 function requiredText3(args, name) {
   const candidate = args[name];
@@ -197171,7 +197687,7 @@ var MUTATION_TOOL_SCHEMA = {
 };
 
 // src/shared/tools/release-tools.ts
-import { createHash as createHash7 } from "node:crypto";
+import { createHash as createHash8 } from "node:crypto";
 import { existsSync as existsSync14, mkdirSync as mkdirSync4, readdirSync as readdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname11, join as join18, relative as relative10, resolve as resolve23 } from "node:path";
 var SAFE_PROJECT_REF = /^[A-Za-z0-9_-]{1,64}$/;
@@ -197413,7 +197929,7 @@ function genericScopedReleaseScopeJson(scope) {
   return JSON.stringify(canonicalValue(scope));
 }
 function genericScopedReleaseScopeSha256(scope) {
-  return createHash7("sha256").update(genericScopedReleaseScopeJson(scope)).digest("hex");
+  return createHash8("sha256").update(genericScopedReleaseScopeJson(scope)).digest("hex");
 }
 function runGitRevParse(cwd, args) {
   const res = Bun.spawnSync(["git", ...args], { cwd });
@@ -197919,7 +198435,7 @@ function registerReleaseTools(server2, http, options = {}) {
 
 // src/shared/tools/deploy-tools.ts
 import { access, lstat as lstat5, mkdtemp as mkdtemp2, opendir, readFile as readFile7, rm as rm3, writeFile as writeFile7 } from "node:fs/promises";
-import { createHash as createHash8 } from "node:crypto";
+import { createHash as createHash9 } from "node:crypto";
 import { tmpdir as tmpdir3 } from "node:os";
 import { basename as basename10, dirname as dirname12, join as join19, relative as relative11, resolve as resolve24, sep as sep5 } from "node:path";
 
@@ -198854,7 +199370,7 @@ async function createFrontendArchive(outputDirectory) {
   try {
     const archiveBytes = zipSync(collected.files, { level: 6, mtime: FIXED_ZIP_MTIME });
     await writeFile7(archivePath, archiveBytes);
-    const sha256 = createHash8("sha256").update(archiveBytes).digest("hex");
+    const sha256 = createHash9("sha256").update(archiveBytes).digest("hex");
     return {
       archivePath,
       sha256,
@@ -199077,7 +199593,7 @@ function registerDeployTools(server2, http, options = {}) {
 import { existsSync as existsSync15 } from "node:fs";
 import { readFile as readFile8 } from "node:fs/promises";
 import { readdir as readdir8 } from "node:fs/promises";
-import { createHash as createHash9 } from "node:crypto";
+import { createHash as createHash10 } from "node:crypto";
 import { join as join20, resolve as resolve25 } from "node:path";
 import { compileProject as compileProject2 } from "@supacloud/compiler";
 var SAFE_TOKEN = /^[A-Za-z0-9._:@/+,-]+$/;
@@ -199176,7 +199692,7 @@ async function sourceFingerprint(root) {
     }
   };
   await visit(root);
-  const hash = createHash9("sha256");
+  const hash = createHash10("sha256");
   for (const file of files) {
     hash.update(file.slice(root.length).replace(/\\/g, "/"));
     hash.update(await readFile8(file));
@@ -199345,7 +199861,7 @@ function registerRemoteDevTools(server2, options = {}) {
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.81.0",
+  version: "0.82.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -199670,12 +200186,19 @@ EXAMPLES
   ${preferredCommand} app diff --ref abc123 --id orders --environment_id test --release_id <sha256> --configuration_id <uuid>
   ${preferredCommand} app deploy --ref abc123 --id orders --environment_id test --release_id <sha256> --configuration_id <uuid>
   ${preferredCommand} app status --ref abc123 --id orders --environment_id test
+  ${preferredCommand} app diff --ref abc123 --id orders --environment_id production --source_ref staging --source_environment_id staging --source_release_id <sha256>
   ${preferredCommand} --env production app promote-plan --id orders --environment_id production --source_ref staging --source_environment_id staging --source_release_id <sha256>
   ${preferredCommand} app preview-plan --ref abc123 --id orders --environment_id test --release_id <sha256> --branch_ref preview-orders
   ${preferredCommand} app preview --ref abc123 --id orders --environment_id test --release_id <sha256> --configuration_id <uuid> --ttl_seconds 3600 --wait
   ${preferredCommand} app previews --ref abc123 --id orders --environment_id test
   ${preferredCommand} app preview-status --ref abc123 --id orders --environment_id test --preview_id <uuid> --wait --timeout_seconds 300
   ${preferredCommand} app preview-cleanup --ref abc123 --id orders --environment_id test --preview_id <uuid>
+  ${preferredCommand} --env production app promote --id orders --environment_id production --source_ref staging --source_environment_id staging --source_release_id <sha256> --confirm-production abc123
+  ${preferredCommand} app promote-status --ref abc123 --id orders --environment_id production --mutation_id <uuid>
+  ${preferredCommand} app promote-reconcile --ref abc123 --id orders --environment_id production --mutation_id <uuid>
+  ${preferredCommand} app preview-create --ref abc123 --id orders --environment_id test --release_id <sha256> --data_mode schema_only
+  ${preferredCommand} app preview-list --ref abc123 --id orders --environment_id test
+  ${preferredCommand} app preview-cleanup --ref abc123 --id orders --environment_id test --preview_id <preview-id>
   ${preferredCommand} app logs --ref abc123 --id orders --environment_id test
   ${preferredCommand} app rollback --ref abc123 --id orders --environment_id test --release_id <old-sha256> --configuration_id <uuid> --activation_id <new-uuid> --expected_activation_id <current-uuid>
   ${preferredCommand} app check --root . --strict