@supacloud/cli 0.80.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,20 +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_rollback_snapshot", "get_history", "get_deploy_plan", "logs", "get_preview_plan"],
-    write: [
-      "upload_release",
-      "put_configuration",
-      "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"],
@@ -179178,7 +179176,7 @@ var ACTION_POLICY = {
   scheduled_functions: { read: ["list", "get"], write: ["create", "update", "delete"] },
   mutations: { read: ["status"] },
   release: {
-    read: ["logical_backup_list", "postgrest_status"],
+    read: ["logical_backup_list", "logical_backup_status", "postgrest_status"],
     local: ["scope_inspect", "scope_rebind", "scope_create"],
     write: ["logical_backup_create", "logical_backup_restore", "postgrest_restart", "release_canary_fixture_stage_replay", "release_canary_fixture_disable_replay"]
   },
@@ -179201,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", "rollback-plan", "history", "deploy-plan", "diff", "preview-plan"],
-    write: ["upload", "configure", "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"],
@@ -180419,6 +180417,52 @@ function parseApplicationActivationHistory(value) {
   }
   return structuredClone(value);
 }
+// node_modules/@supacloud/delivery/src/application-release-transfer.ts
+var projectRef = String2({ pattern: "^[A-Za-z0-9_-]{1,20}$" });
+var source = _Object_({
+  project_ref: projectRef,
+  release_id: ApplicationReleaseIdSchema,
+  manifest_sha256: ApplicationReleaseIdSchema
+}, { additionalProperties: false });
+var identity = {
+  project_ref: projectRef,
+  application_id: ApplicationIdSchema,
+  source,
+  candidate_release_id: ApplicationReleaseIdSchema
+};
+var ApplicationReleaseTransferPlanSchema = _Object_({
+  schema: Literal("supacloud.application-release-transfer-plan.v1"),
+  ...identity,
+  action: Union([Literal("materialize"), Literal("no-op")]),
+  execution_performed: Literal(false)
+}, { additionalProperties: false });
+var ApplicationReleaseTransferResultSchema = _Object_({
+  schema: Literal("supacloud.application-release-transfer-result.v1"),
+  ...identity,
+  release: ApplicationReleaseRecordSchema,
+  activation_performed: Literal(false)
+}, { additionalProperties: false });
+function assertIdentity(value) {
+  if (value.source.release_id !== applicationReleaseId(value.source.project_ref, value.application_id, value.source.manifest_sha256) || value.candidate_release_id !== applicationReleaseId(value.project_ref, value.application_id, value.source.manifest_sha256)) {
+    throw new Error("Invalid application release transfer identity");
+  }
+}
+function parseApplicationReleaseTransferPlan(candidate) {
+  if (!Check2(ApplicationReleaseTransferPlanSchema, candidate))
+    throw new Error("Invalid application release transfer plan");
+  assertIdentity(candidate);
+  return candidate;
+}
+function parseApplicationReleaseTransferResult(candidate) {
+  if (!Check2(ApplicationReleaseTransferResultSchema, candidate))
+    throw new Error("Invalid application release transfer result");
+  assertIdentity(candidate);
+  const release = parseApplicationReleaseRecord(candidate.release);
+  if (release.project_ref !== candidate.project_ref || release.application_id !== candidate.application_id || release.release_id !== candidate.candidate_release_id || release.manifest_sha256 !== candidate.source.manifest_sha256) {
+    throw new Error("Invalid application release transfer result");
+  }
+  return candidate;
+}
 // node_modules/@supacloud/delivery/src/deployment-evidence.ts
 var closed3 = { additionalProperties: false };
 var sha256 = String2({ pattern: "^[a-f0-9]{64}$" });
@@ -180544,6 +180588,116 @@ function parseDeploymentEvidence(value) {
   }
   return structuredClone(value);
 }
+// node_modules/@supacloud/delivery/src/application-promotion.ts
+var closed4 = { additionalProperties: false };
+var projectRef2 = String2({ pattern: "^[a-z0-9-]{1,20}$" });
+var sha2562 = ApplicationReleaseIdSchema;
+var nullableActivation = Union([ApplicationActivationIdSchema, Null()]);
+var nullableDigest = Union([sha2562, Null()]);
+var observation = {
+  activation_id: nullableActivation,
+  receipt_confirmed: Boolean2(),
+  ready: Boolean2(),
+  smoke_verified: Boolean2(),
+  evidence_sha256: nullableDigest,
+  migration_ledger_digest: nullableDigest
+};
+var blocker = [
+  "SOURCE_NOT_ACTIVE",
+  "SOURCE_RECEIPT_UNCONFIRMED",
+  "SOURCE_NOT_READY",
+  "SOURCE_SMOKE_UNVERIFIED",
+  "TARGET_CONFIGURATION_MISSING",
+  "TARGET_CONFIGURATION_MISMATCH",
+  "MIGRATION_PENDING",
+  "MIGRATION_CONFLICT",
+  "OPERATOR_PROVISIONING_REQUIRED",
+  "BACKUP_REQUIRED"
+];
+var ApplicationPromotionPlanSchema = _Object_({
+  schema: Literal("supacloud.application-promotion-plan.v1"),
+  project_ref: projectRef2,
+  application_id: ApplicationIdSchema,
+  environment_id: ApplicationIdSchema,
+  manifest_sha256: sha2562,
+  plan_sha256: sha2562,
+  source: _Object_({
+    project_ref: projectRef2,
+    environment_id: ApplicationIdSchema,
+    release_id: sha2562,
+    ...observation
+  }, closed4),
+  target: _Object_({
+    candidate_release_id: sha2562,
+    current_release_id: Union([sha2562, Null()]),
+    artifact_action: Union([Literal("materialize"), Literal("reuse")]),
+    configuration_id: Union([ApplicationConfigurationIdSchema, Null()]),
+    configuration: Union([ApplicationConfigurationViewSchema, Null()]),
+    ...observation
+  }, closed4),
+  migrations: _Object_({
+    ledger_digest: sha2562,
+    ledger_compatible: Boolean2(),
+    project_migrations_applied: Boolean2(),
+    pending_versions: _Array_(String2({ pattern: "^\\d{1,20}$" }), { maxItems: 4096, uniqueItems: true }),
+    operator_provisioning_required: Boolean2()
+  }, closed4),
+  backup: _Object_({
+    required: Boolean2(),
+    confirmed: Literal(false)
+  }, closed4),
+  action: Union([Literal("promote"), Literal("no-op"), Literal("blocked")]),
+  blockers: _Array_(Enum([...blocker]), {
+    maxItems: blocker.length,
+    uniqueItems: true
+  }),
+  steps: _Array_(String2({ minLength: 1, maxLength: 64 }), { maxItems: 8, uniqueItems: true }),
+  execution_performed: Literal(false),
+  data_recovery: Literal("separate-required")
+}, closed4);
+function applicationPromotionPlanDigest(value) {
+  return digest(canonical(value));
+}
+function applicationPromotionAction(value) {
+  if (value.blockers.length > 0)
+    return "blocked";
+  return value.target.artifact_action === "reuse" && value.target.current_release_id === value.target.candidate_release_id && value.target.configuration !== null && value.target.activation_id !== null && value.target.receipt_confirmed && value.target.ready && value.target.smoke_verified && value.migrations.project_migrations_applied && !value.migrations.operator_provisioning_required && (!value.backup.required || value.backup.confirmed) ? "no-op" : "promote";
+}
+function applicationPromotionSteps(value) {
+  if (value.action === "no-op")
+    return [];
+  return [
+    ...value.blockers.some((code) => code.startsWith("SOURCE_")) ? ["verify-source"] : [],
+    ...value.blockers.some((code) => code.startsWith("TARGET_CONFIGURATION_")) ? ["bind-target-configuration"] : [],
+    ...value.blockers.includes("MIGRATION_CONFLICT") ? ["resolve-migration-conflicts"] : [],
+    ...!value.backup.required || value.backup.confirmed ? [] : ["backup"],
+    ...value.migrations.project_migrations_applied ? [] : ["review-and-apply-migrations"],
+    ...value.migrations.operator_provisioning_required ? ["verify-operator-provisioning"] : [],
+    ...value.action === "promote" ? [
+      ...value.target.artifact_action === "materialize" ? ["transfer"] : [],
+      "activate-with-cas",
+      "verify-runtime-and-smoke"
+    ] : []
+  ];
+}
+function parseApplicationPromotionPlan(value) {
+  if (!Check2(ApplicationPromotionPlanSchema, value))
+    throw new Error("Invalid application promotion plan");
+  const { plan_sha256: _planSha256, ...content } = value;
+  if (value.migrations.project_migrations_applied && (!value.migrations.ledger_compatible || value.migrations.pending_versions.length > 0) || !value.source.activation_id && (value.source.ready || value.source.receipt_confirmed || value.source.smoke_verified) || !value.target.activation_id && (value.target.ready || value.target.receipt_confirmed || value.target.smoke_verified) || !value.blockers.length && (!value.source.ready || !value.source.receipt_confirmed || !value.source.smoke_verified || !value.source.activation_id || !value.target.configuration || !value.migrations.ledger_compatible)) {
+    throw new Error("Invalid application promotion prerequisites");
+  }
+  if (value.backup.required !== !value.migrations.project_migrations_applied || [value.source, value.target].some((observation) => observation.smoke_verified && (observation.evidence_sha256 === null || observation.migration_ledger_digest === null)) || value.target.smoke_verified && value.target.migration_ledger_digest !== value.migrations.ledger_digest) {
+    throw new Error("Invalid application promotion migration binding");
+  }
+  if (value.source.release_id !== applicationReleaseId(value.source.project_ref, value.application_id, value.manifest_sha256) || value.target.candidate_release_id !== applicationReleaseId(value.project_ref, value.application_id, value.manifest_sha256) || value.action !== applicationPromotionAction(content) || canonical(value.steps) !== canonical(applicationPromotionSteps(content)) || value.plan_sha256 !== applicationPromotionPlanDigest(content) || value.target.configuration !== null && (() => {
+    const configuration = parseApplicationConfigurationView(value.target.configuration);
+    return configuration.project_ref !== value.project_ref || configuration.application_id !== value.application_id || configuration.environment_id !== value.environment_id || configuration.configuration_id !== value.target.configuration_id;
+  })()) {
+    throw new Error("Invalid application promotion plan identity");
+  }
+  return structuredClone(value);
+}
 // node_modules/@supacloud/delivery/src/application-runtime-identity.ts
 var ApplicationRuntimeIdentitySchema = _Object_({
   schema: Literal("supacloud.application-runtime.v1"),
@@ -181551,7 +181705,7 @@ ALTER TABLE supacloud_commands.execution_receipts
   DROP COLUMN IF EXISTS recovery_attempts;
 `;
 var MAX_MIGRATION_VERSION = 9223372036854775807n;
-function sha2562(value) {
+function sha2563(value) {
   return createHash22("sha256").update(value).digest("hex");
 }
 function normalizedSql(value) {
@@ -181620,7 +181774,7 @@ function planMigrationRebase(migrations, options, baselineSql) {
     file: migration.file,
     version: migration.version,
     name: migration.name,
-    sha256: sha2562(normalizedSql(migration.sql))
+    sha256: sha2563(normalizedSql(migration.sql))
   }));
   return {
     version: 1,
@@ -181630,8 +181784,8 @@ function planMigrationRebase(migrations, options, baselineSql) {
     baselineMigration,
     retainedMigrations: retained.map((migration) => migration.file),
     archivedMigrations: archived.map((migration) => migration.file),
-    sourceHistorySha256: sha2562(JSON.stringify(sourceHistory)),
-    baselineSha256: sha2562(normalizedBaseline),
+    sourceHistorySha256: sha2563(JSON.stringify(sourceHistory)),
+    baselineSha256: sha2563(normalizedBaseline),
     warnings: [
       "The baseline must come from a schema-only snapshot of the verified target database.",
       "Data backfills, reference data and non-replayable side effects need a separate review.",
@@ -181667,7 +181821,7 @@ async function rebaseMigrations(options) {
       file: migration.file,
       version: migration.version,
       name: migration.name,
-      sha256: sha2562(normalizedSql(migration.sql))
+      sha256: sha2563(normalizedSql(migration.sql))
     }))
   }, null, 2) + `
 `);
@@ -184569,7 +184723,7 @@ function clientId(value) {
   }
   return value;
 }
-function projectRef(value) {
+function projectRef3(value) {
   if (typeof value !== "string" || !value.trim())
     throw new Error("'ref' is required");
   return projectRefPathSegment(value.trim(), "OAuth client");
@@ -184721,7 +184875,7 @@ function registerOAuthClientTools(server2, http) {
     client_id: optional(String2(), "[get/delete] Exact release-canary public OAuth client ID"),
     redirect_uri: optional(String2(), "[create/delete] Exact HTTPS or port-bound RFC 8252 loopback callback")
   }, async ({ action, ref, client_id, redirect_uri }) => {
-    const targetRef = projectRef(ref);
+    const targetRef = projectRef3(ref);
     if (action === "list")
       return listReleaseCanaryClients(http, targetRef);
     if (action === "get")
@@ -187393,6 +187547,432 @@ 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) {
+  const operation = `applications.${input.action}`;
+  const identity = {
+    project_ref: input.ref,
+    application_id: input.id,
+    source_ref: input.sourceRef,
+    source_release_id: input.sourceReleaseId
+  };
+  const path = `/v1/projects/${project}/applications/${encodeURIComponent(input.id)}`;
+  const query = new URLSearchParams({ source_ref: input.sourceRef, source_release_id: input.sourceReleaseId });
+  const response = await http.get(`${path}/release-transfer-plan?${query}`, { maxJsonBytes: 65536, responseTimeoutMs: 30000 });
+  if (!response.ok)
+    return releaseControlFailure(operation, "HTTP_ERROR", response.transportError ? null : response.status, identity);
+  let plan;
+  try {
+    if (response.status !== 200)
+      throw new Error;
+    plan = parseApplicationReleaseTransferPlan(response.data);
+    if (plan.project_ref !== input.ref || plan.application_id !== input.id || plan.source.project_ref !== input.sourceRef || plan.source.release_id !== input.sourceReleaseId)
+      throw new Error;
+  } catch {
+    return releaseControlFailure(operation, "INVALID_RESPONSE", response.status, identity);
+  }
+  if (input.action === "get_release_transfer_plan")
+    return releaseControlSuccess(operation, { ...identity, plan });
+  const safeIdentity = {
+    ...identity,
+    release_id: plan.candidate_release_id,
+    manifest_sha256: plan.source.manifest_sha256
+  };
+  if (plan.action === "no-op")
+    return releaseControlSuccess(operation, {
+      ...safeIdentity,
+      no_op: true,
+      execution_performed: false,
+      activation_performed: false,
+      plan
+    });
+  const result = await http.postReleaseMutation(`${path}/release-transfers`, {
+    source_ref: input.sourceRef,
+    source_release_id: input.sourceReleaseId,
+    expected_manifest_sha256: plan.source.manifest_sha256
+  }, { timeoutMs: 120000 });
+  if (!result.ok)
+    return releaseControlMutationFailure(operation, result, safeIdentity);
+  try {
+    if (result.status !== 200)
+      throw new Error;
+    const receipt = parseApplicationReleaseTransferResult(result.data);
+    if (receipt.project_ref !== input.ref || receipt.application_id !== input.id || receipt.source.project_ref !== input.sourceRef || receipt.source.release_id !== input.sourceReleaseId || receipt.candidate_release_id !== plan.candidate_release_id || receipt.source.manifest_sha256 !== plan.source.manifest_sha256)
+      throw new Error;
+    return releaseControlSuccess(operation, { ...safeIdentity, no_op: false, transfer: receipt });
+  } catch {
+    return releaseControlFailure(operation, "OUTCOME_UNKNOWN", result.status, safeIdentity);
+  }
+}
 
 // src/shared/tools/application-preview-tools.ts
 var APPLICATION_PREVIEW_ACTIONS = [
@@ -187420,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"),
@@ -187434,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(),
@@ -187479,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") {
@@ -187710,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);
@@ -187732,12 +188316,23 @@ var APPLICATION_TOOL_SCHEMA = {
     "put_configuration",
     "get_deploy_plan",
     "deploy_release",
+    "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"),
@@ -187750,6 +188345,12 @@ var APPLICATION_TOOL_SCHEMA = {
   configuration_path: optional(String2(), "[put_configuration] Local configuration write JSON including revision and expected revision"),
   manifest_path: optional(String2(), "[upload_release] Local delivery.manifest.json"),
   release_id: optional(ApplicationReleaseIdSchema2, "[get_release/get_deploy_plan/deploy_release/activate_release/reconcile_activation/rollback_release] Immutable application release ID; platform selects previous for default rollback"),
+  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"),
@@ -187770,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())
@@ -188045,13 +188652,59 @@ function registerApplicationTools(server2, http) {
       throw new Error("Invalid application ID");
     const path = `/v1/projects/${project}/applications/${encodeURIComponent(id)}/releases`;
     const operation = `applications.${action}`;
-    if (action === "get_deploy_plan") {
-      const observed = await readDeployPlan(http, args, project);
-      return observed.failure ?? releaseControlSuccess(operation, { ...observed.identity, plan: observed.plan });
-    }
-    if (action === "deploy_release")
-      return deployAction(http, args, project);
-    if (action === "rollback_release" || action === "get_rollback_snapshot") {
+    if (action === "get_promotion_plan") {
+      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");
+      if (!/^[a-z0-9-]{1,20}$/.test(sourceRef) || !Check2(ApplicationReleaseIdSchema2, sourceReleaseId) || !Check2(ApplicationIdSchema2, environmentId) || !Check2(ApplicationIdSchema2, sourceEnvironmentId)) {
+        throw new Error("Invalid promotion environment");
+      }
+      const query = new URLSearchParams({
+        source_ref: sourceRef,
+        source_environment_id: sourceEnvironmentId,
+        source_release_id: sourceReleaseId
+      });
+      if (typeof args["configuration_id"] === "string")
+        query.set("configuration_id", args["configuration_id"]);
+      const result = await http.get(`/v1/projects/${project}/applications/${encodeURIComponent(id)}/environments/${encodeURIComponent(environmentId)}/promotion-plan?${query}`, { maxJsonBytes: 262144, responseTimeoutMs: 30000 });
+      const identity = {
+        project_ref: ref,
+        application_id: id,
+        environment_id: environmentId,
+        source_ref: sourceRef,
+        source_environment_id: sourceEnvironmentId,
+        source_release_id: sourceReleaseId
+      };
+      if (!result.ok)
+        return releaseControlFailure(operation, "HTTP_ERROR", result.status, identity);
+      try {
+        if (result.status !== 200)
+          throw new Error;
+        const plan = parseApplicationPromotionPlan(result.data);
+        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 || args["configuration_id"] !== undefined && plan.target.configuration_id !== args["configuration_id"]) {
+          throw new Error;
+        }
+        return releaseControlSuccess(operation, { ...identity, plan });
+      } catch {
+        return releaseControlFailure(operation, "INVALID_RESPONSE", result.status, identity);
+      }
+    }
+    if (action === "get_release_transfer_plan" || action === "transfer_release") {
+      return applicationReleaseTransfer(http, {
+        action,
+        ref,
+        id,
+        sourceRef: text(args, "source_ref"),
+        sourceReleaseId: text(args, "source_release_id")
+      }, project);
+    }
+    if (action === "get_deploy_plan") {
+      const observed = await readDeployPlan(http, args, project);
+      return observed.failure ?? releaseControlSuccess(operation, { ...observed.identity, plan: observed.plan });
+    }
+    if (action === "deploy_release")
+      return deployAction(http, args, project);
+    if (action === "rollback_release" || action === "get_rollback_snapshot") {
       return rollbackAction(http, args, project);
     }
     if (action === "get_history")
@@ -188116,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))
@@ -188292,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;
@@ -188307,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;
@@ -194299,6 +195112,16 @@ async function applyScaffoldWrites(plan) {
 // src/shared/tools/app-tools.ts
 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",
   "deploy-plan": "get_deploy_plan",
@@ -194310,33 +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/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/deploy/deploy-plan/diff/status/rollback/rollback-plan/history/reconcile/retire/preview-plan/preview/previews/preview-status/preview-cleanup] Application ID",
-  environment_id: "[configure/deploy/deploy-plan/diff/status/rollback/rollback-plan/history/reconcile/retire/preview-plan/preview/previews/preview-status/preview-cleanup] Environment ID",
-  configuration_id: "[deploy/deploy-plan/diff/rollback/preview] 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",
-  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];
@@ -195233,6 +196058,30 @@ async function runDelivery(args) {
   const result = await buildDeliveryProject(options, loaded.delivery);
   return textResult(JSON.stringify(result, null, 2), !result.ok);
 }
+function formatReleaseTransfer(result) {
+  if (result.isError)
+    return result;
+  try {
+    const payload = JSON.parse(result.content[0]?.text ?? "");
+    if (!payload || typeof payload !== "object" || !("ok" in payload) || payload.ok !== true)
+      return result;
+    const plan = "plan" in payload ? parseApplicationReleaseTransferPlan(payload.plan) : null;
+    const receipt = !plan && "transfer" in payload ? parseApplicationReleaseTransferResult(payload.transfer) : null;
+    const data = plan ?? receipt;
+    if (!data)
+      return result;
+    return textResult([
+      `${data.project_ref}/${data.application_id}: ${plan ? plan.action === "no-op" ? "No changes" : "Transfer required" : "Artifact transferred"}`,
+      `Source: ${data.source.project_ref} / ${data.source.release_id}`,
+      `Target release: ${data.candidate_release_id}`,
+      `Manifest: ${data.source.manifest_sha256}`,
+      "Activation: not performed"
+    ].join(`
+`));
+  } catch {
+    return result;
+  }
+}
 var historyReceiptSchema = _Object_({
   schema: Literal(RELEASE_CONTROL_RESPONSE_SCHEMA),
   ok: Literal(true),
@@ -195302,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");
@@ -195318,14 +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.json !== true || request.format === "text")) {
-    throw new Error("--json applies only to app history and cannot be combined with --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,
@@ -195337,7 +196355,14 @@ async function runAppTool(request, options = {}) {
     if (request.action === "history" && format !== "json" && json !== true) {
       return historyText(result, request, args.ref);
     }
-    return (request.action === "deploy-plan" || request.action === "diff") && format !== "json" ? formatRemoteDeployPlan(result) : result;
+    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" || 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) : format !== "json" && !json ? formatWorkflowObservation(result, request.action) : result;
   }
   switch (request.action) {
     case "verify-plan": {
@@ -195411,6 +196436,9 @@ function registerAppTools(server2, options = {}) {
       "build",
       "upload",
       "configure",
+      "transfer-plan",
+      "transfer",
+      "promote-plan",
       "deploy",
       "deploy-plan",
       "diff",
@@ -195424,9 +196452,14 @@ function registerAppTools(server2, options = {}) {
       "preview-plan",
       "preview",
       "previews",
+      "preview-list",
+      "preview-create",
       "preview-status",
-      "preview-cleanup"
-    ]), "App action; 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"),
@@ -195441,8 +196474,8 @@ function registerAppTools(server2, options = {}) {
     include: optional(String2(), "[dev/compile/check] Comma-separated glob patterns for source files"),
     out_dir: optional(String2(), "[dev/compile/plan/build/export-tools] Output directory (default: configured outDir)"),
     strict: optional(Boolean2(), "[dev/compile/check] Promote warnings to errors"),
-    format: optional(stringEnum(["text", "json"]), "[dev/generate/compile/check/plan/deploy-plan/diff/history/graph/export-tools] Output format (default: text)"),
-    json: optional(Literal(true), "[history] Return the validated JSON receipt"),
+    format: optional(stringEnum(["text", "json"]), "[dev/generate/compile/check/plan/deploy-plan/diff/history/promote-plan/graph/export-tools] Output format (default: text)"),
+    json: optional(Boolean2(), "[history/transfer-plan/transfer/promote-plan] Preserve or return the full machine-readable receipt"),
     profile: optional(stringEnum(["fast", "integration"]), "[dev] Run dev or dev:integration; integration verifies an explicit loopback database"),
     once: optional(Boolean2(), "[dev] Validate and report once without watching"),
     watch: optional(Boolean2(), "[dev] Watch for changes (default: true; --once disables)"),
@@ -195484,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";
@@ -195550,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) }]
@@ -196239,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) {
@@ -196284,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;
@@ -196325,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));
@@ -196366,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));
@@ -196384,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);
@@ -196430,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)) {
@@ -196445,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);
@@ -196458,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;
@@ -196476,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);
   }
@@ -196616,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];
@@ -196852,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}$/;
@@ -196883,7 +197718,8 @@ function validProjectRef(ref) {
   return SAFE_PROJECT_REF.test(ref);
 }
 function backupBelongsToProject(backupId, projectRef) {
-  return BACKUP_ID.test(backupId) && backupId.startsWith(`logical-full_${projectRef}_`);
+  const prefix = `logical-full_${projectRef}_`;
+  return BACKUP_ID.test(backupId) && backupId.startsWith(prefix) && /^[a-f0-9]{32}$/.test(backupId.slice(prefix.length));
 }
 function verifiedBackup(value, projectRef) {
   if (!isRecord6(value) || typeof value.backup_id !== "string" || !backupBelongsToProject(value.backup_id, projectRef) || value.project_ref !== projectRef || typeof value.database !== "string" || !SAFE_DATABASE.test(value.database) || value.kind !== "logical-full" || !canonicalTimestamp4(value.created_at) || !canonicalTimestamp4(value.completed_at) || new Date(value.completed_at).valueOf() < new Date(value.created_at).valueOf() || typeof value.bytes !== "number" || !Number.isSafeInteger(value.bytes) || value.bytes <= 0 || typeof value.sha256 !== "string" || !SHA256.test(value.sha256))
@@ -196922,16 +197758,11 @@ function publicBackup(backup) {
 function equalBackup(left, right) {
   return left.backup_id === right.backup_id && left.project_ref === right.project_ref && left.database === right.database && left.kind === right.kind && left.created_at === right.created_at && left.completed_at === right.completed_at && left.bytes === right.bytes && left.sha256 === right.sha256;
 }
-function newlyCreatedBackup(before, after) {
-  const afterById = new Map(after.map((backup) => [backup.backup_id, backup]));
-  for (const previous of before) {
-    const current = afterById.get(previous.backup_id);
-    if (!current || !equalBackup(previous, current))
-      return null;
+function requiredBackupId(value, projectRef) {
+  if (typeof value !== "string" || !backupBelongsToProject(value, projectRef)) {
+    throw new Error("'backup_id' must identify a logical-full backup for 'ref'");
   }
-  const known = new Set(before.map((backup) => backup.backup_id));
-  const additions = after.filter((backup) => !known.has(backup.backup_id));
-  return additions.length === 1 ? additions[0] : null;
+  return value;
 }
 function restoreRequest(projectRef, backupId, expectedSha256, restoreConfirmation) {
   if (typeof backupId !== "string" || !backupBelongsToProject(backupId, projectRef)) {
@@ -196957,11 +197788,27 @@ function httpFailure(operation, response) {
   }
   return releaseControlFailure(operation, "HTTP_ERROR", response.transportError ? null : response.status);
 }
-function mutationFailure(operation, response) {
-  if (response.responseReadError || response.transportError || response.status === 408 || response.status >= 500) {
-    return releaseControlFailure(operation, "OUTCOME_UNKNOWN", response.transportError ? null : response.status);
+function mutationOutcomeUnknown(response) {
+  return Boolean(response.responseReadError || response.transportError || response.status === 408 || response.status >= 500 || response.status >= 200 && response.status < 300 && response.status !== 200);
+}
+function mutationFailure(operation, response, safeState = {}) {
+  if (mutationOutcomeUnknown(response)) {
+    return releaseControlFailure(operation, "OUTCOME_UNKNOWN", response.transportError ? null : response.status, safeState);
   }
-  return releaseControlFailure(operation, "HTTP_ERROR", response.status);
+  return releaseControlFailure(operation, "HTTP_ERROR", response.status, safeState);
+}
+async function readBackup(http, projectRef, backupId) {
+  let response;
+  try {
+    response = await http.get(`${endpoint(projectRef)}/database/backups/logical/${backupId}`, {
+      maxJsonBytes: MUTATION_MAX_BYTES,
+      responseTimeoutMs: RELEASE_READ_RESPONSE_TIMEOUT_MS
+    });
+  } catch {
+    response = { ok: false, status: 0, data: null, transportError: true };
+  }
+  const candidate = response.ok && response.status === 200 && isRecord6(response.data) ? verifiedBackup(response.data.backup, projectRef) : null;
+  return { response, backup: candidate?.backup_id === backupId ? candidate : null };
 }
 async function readInventory(http, projectRef) {
   const response = await http.get(`${endpoint(projectRef)}/database/backups/logical`, {
@@ -197082,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 });
@@ -197374,6 +198221,7 @@ function registerReleaseTools(server2, http, options = {}) {
   const localActions = ["scope_inspect", "scope_rebind", "scope_create"];
   const remoteActions = [
     "logical_backup_list",
+    "logical_backup_status",
     "logical_backup_create",
     "logical_backup_restore",
     "postgrest_status",
@@ -197396,7 +198244,7 @@ function registerReleaseTools(server2, http, options = {}) {
     web: optional(Boolean2(), "[scope_create] Whether web assets are included in release scope"),
     dry_run: optional(Boolean2(), "[scope_rebind] Perform calculation and validation without writing files"),
     cwd: optional(String2(), "[scope_inspect/scope_rebind/scope_create] Base directory for relative file and git resolution"),
-    backup_id: optional(String2(), "[logical_backup_restore] Exact verified logical-full backup ID from the selected project inventory"),
+    backup_id: optional(String2(), "[logical_backup_create/status/restore] Stable project-bound backup ID; create generates one when omitted"),
     expected_sha256: optional(String2(), "[logical_backup_restore] Exact lowercase SHA-256 from the selected project inventory"),
     restore_confirmation: optional(String2(), "[logical_backup_restore] Exact RESTORE_PROJECT:<ref>:<backup_id>:<sha256> confirmation"),
     subject: optional(String2(), "[release_canary_fixture_stage_replay/disable_replay] Exact central subject UUID"),
@@ -197441,28 +198289,47 @@ function registerReleaseTools(server2, http, options = {}) {
       });
     }
     if (action === "logical_backup_create") {
-      const before = await readInventory(http, projectRef);
-      const beforeFailure = readInventoryFailure("release.logical_backup.create", before);
-      if (beforeFailure)
-        return beforeFailure;
-      const mutation = await http.postReleaseMutation(`${endpoint(projectRef)}/database/backups/logical`, {}, {
-        timeoutMs: BACKUP_TIMEOUT_MS
-      });
-      const after = await readInventory(http, projectRef);
+      const backupId = requiredBackupId(backup_id ?? `logical-full_${projectRef}_${crypto.randomUUID().replaceAll("-", "")}`, projectRef);
+      const state = { project_ref: projectRef, backup_id: backupId };
+      let mutation;
+      try {
+        mutation = await http.postReleaseMutation(`${endpoint(projectRef)}/database/backups/logical`, { backup_id: backupId }, { timeoutMs: BACKUP_TIMEOUT_MS });
+      } catch {
+        mutation = { ok: false, status: 0, data: null, transportError: true };
+      }
       if (!mutation.ok || mutation.status !== 200) {
-        return mutationFailure("release.logical_backup.create", mutation);
+        if (mutationOutcomeUnknown(mutation)) {
+          const observed = await readBackup(http, projectRef, backupId);
+          if (observed.backup)
+            return releaseControlFailure("release.logical_backup.create", "OUTCOME_UNKNOWN", mutation.transportError ? null : mutation.status, {
+              ...state,
+              backup: publicBackup(observed.backup),
+              backup_verified: true,
+              creation_confirmed: false
+            });
+        }
+        return mutationFailure("release.logical_backup.create", mutation, state);
       }
       const responseBackup = isRecord6(mutation.data) ? verifiedBackup(mutation.data.backup, projectRef) : null;
-      const afterFailure = readInventoryFailure("release.logical_backup.create", after);
-      const addedBackup = after.inventory && newlyCreatedBackup(before.inventory, after.inventory);
-      if (!responseBackup || afterFailure || !addedBackup || !equalBackup(responseBackup, addedBackup)) {
-        return releaseControlFailure("release.logical_backup.create", "OUTCOME_UNKNOWN", mutation.status);
+      const after = await readBackup(http, projectRef, backupId);
+      if (!responseBackup || responseBackup.backup_id !== backupId || !after.backup || !equalBackup(responseBackup, after.backup)) {
+        return releaseControlFailure("release.logical_backup.create", "OUTCOME_UNKNOWN", mutation.status, state);
       }
       return releaseControlSuccess("release.logical_backup.create", {
-        project_ref: projectRef,
-        backup: publicBackup(addedBackup)
+        ...state,
+        backup: publicBackup(after.backup)
       });
     }
+    if (action === "logical_backup_status") {
+      const backupId = requiredBackupId(backup_id, projectRef);
+      const read = await readBackup(http, projectRef, backupId);
+      const state = { project_ref: projectRef, backup_id: backupId };
+      if (!read.response.ok || read.response.status !== 200) {
+        const code = read.response.responseReadError || read.response.status >= 200 && read.response.status < 300 ? "INVALID_RESPONSE" : "HTTP_ERROR";
+        return releaseControlFailure("release.logical_backup.status", code, read.response.transportError ? null : read.response.status, state);
+      }
+      return read.backup ? releaseControlSuccess("release.logical_backup.status", { ...state, backup: publicBackup(read.backup) }) : releaseControlFailure("release.logical_backup.status", "INVALID_RESPONSE", read.response.status, state);
+    }
     if (action === "logical_backup_restore") {
       const request = restoreRequest(projectRef, backup_id, expected_sha256, restore_confirmation);
       const before = await readInventory(http, projectRef);
@@ -197568,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";
 
@@ -198503,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,
@@ -198726,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._:@/+,-]+$/;
@@ -198825,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));
@@ -198994,7 +199861,7 @@ function registerRemoteDevTools(server2, options = {}) {
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.80.0",
+  version: "0.82.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -199046,14 +199913,14 @@ var package_default = {
   },
   dependencies: {
     "@supacloud/compiler": "^0.43.0",
-    "@supacloud/delivery": "0.10.0",
+    "@supacloud/delivery": "0.11.0",
     "@supacloud/db": "0.16.0",
     fflate: "^0.8.3",
     typebox: "1.3.34"
   },
   overrides: {
     "@supacloud/contracts": "0.8.0",
-    "@supacloud/delivery": "0.10.0",
+    "@supacloud/delivery": "0.11.0",
     "@graphql-tools/utils": "^12.0.3"
   },
   devDependencies: {
@@ -199274,6 +200141,7 @@ EXAMPLES
   ${preferredCommand} project logs --log_type database
   ${preferredCommand} project task_stats
   ${preferredCommand} release logical_backup_create --ref abc123
+  ${preferredCommand} release logical_backup_status --ref abc123 --backup_id <backup_id>
   ${preferredCommand} release logical_backup_restore --ref abc123 --backup_id <backup_id> --expected_sha256 <sha256> --restore_confirmation RESTORE_PROJECT:abc123:<backup_id>:<sha256>
   ${preferredCommand} release postgrest_status --ref abc123
   ${preferredCommand} release postgrest_restart --ref abc123
@@ -199318,11 +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