@treeseed/sdk 0.12.60 → 0.12.61

package/dist/operations/services/railway-api.js

@@ -1,7 +1,28 @@
-import { request as httpsRequest } from "node:https";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { IacClient } from "railway";
+import { connectRailwayServiceSourceWithCli, runRailwayCliJson } from "./railway-cli.js";
 import { resolveTreeseedRailwayApiToken } from "../../service-credentials.js";
 const DEFAULT_RAILWAY_API_URL = "https://backboard.railway.com/graphql/v2";
 const DEFAULT_RAILWAY_WORKSPACE = "knowledge-coop";
+let railwayReadActive = false;
+const railwayReadWaiters = [];
+let railwayReadCooldownUntil = 0;
+async function acquireRailwayReadSlot() {
+  if (railwayReadActive) await new Promise((resolve2) => railwayReadWaiters.push(resolve2));
+  railwayReadActive = true;
+  const cooldownMs = Math.max(0, railwayReadCooldownUntil - Date.now());
+  if (cooldownMs > 0) await new Promise((resolve2) => setTimeout(resolve2, cooldownMs));
+  return () => {
+    const next = railwayReadWaiters.shift();
+    if (next) next();
+    else railwayReadActive = false;
+  };
+}
+function extendRailwayReadCooldown(delayMs) {
+  railwayReadCooldownUntil = Math.max(railwayReadCooldownUntil, Date.now() + Math.max(0, delayMs));
+}
 function normalizeRailwayEnvironmentName(value) {
   const normalized = typeof value === "string" ? value.trim() : "";
   if (!normalized) {
@@ -9,6 +30,20 @@ function normalizeRailwayEnvironmentName(value) {
   }
   return normalized === "prod" ? "production" : normalized;
 }
+function createRailwayEnvironmentPatchClient({
+  env,
+  fetchImpl
+}) {
+  const token = resolveRailwayApiToken(env);
+  if (!token) {
+    throw new Error("Railway API token is required for environment reconciliation.");
+  }
+  return new IacClient({
+    token,
+    endpoint: resolveRailwayApiUrl(env),
+    fetch: fetchImpl
+  });
+}
 function configuredEnvValue(env, name) {
   const value = env?.[name];
   return typeof value === "string" && value.trim() ? value.trim() : "";
@@ -55,6 +90,7 @@ function parseRetryAfterMs(value) {
 function markRailwayTransientError(error, options = {}) {
   const tagged = error;
   tagged.treeseedTransient = true;
+  if (options.rateLimited) tagged.treeseedRateLimited = true;
   if (typeof options.retryAfterMs === "number" && Number.isFinite(options.retryAfterMs) && options.retryAfterMs >= 0) {
     tagged.treeseedRetryAfterMs = options.retryAfterMs;
   }
@@ -270,6 +306,24 @@ function normalizeVolumeInstances(value) {
   }
   return normalizeConnectionNodes(value, normalizeRailwayVolumeInstance);
 }
+function mergeRailwayVolumeInstances(instances) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const instance of instances) {
+    const existing = byId.get(instance.id);
+    byId.set(instance.id, existing ? {
+      ...existing,
+      serviceId: existing.serviceId || instance.serviceId,
+      environmentId: existing.environmentId || instance.environmentId,
+      mountPath: existing.mountPath || instance.mountPath,
+      state: [existing.state, instance.state].find((state) => /^(?:DELETED|DELETING)$/u.test(String(state ?? "").toUpperCase())) ?? existing.state ?? instance.state,
+      isPendingDeletion: existing.isPendingDeletion || instance.isPendingDeletion,
+      deletedAt: existing.deletedAt || instance.deletedAt,
+      sizeGb: existing.sizeGb ?? instance.sizeGb,
+      usedGb: existing.usedGb ?? instance.usedGb
+    } : instance);
+  }
+  return [...byId.values()];
+}
 function normalizeRailwayVolume(node) {
   const id = railwayConnectionLabel(node.id);
   if (!id) {
@@ -279,11 +333,11 @@ function normalizeRailwayVolume(node) {
     id,
     name: railwayConnectionLabel(node.name),
     projectId: railwayConnectionLabel(node.projectId) || null,
-    instances: [
+    instances: mergeRailwayVolumeInstances([
       ...normalizeVolumeInstances(node.instances),
       ...normalizeVolumeInstances(node.volumeInstances),
       ...normalizeVolumeInstances(node.volume_instances)
-    ]
+    ])
   };
 }
 function collectRailwayVolumes(value, seen = /* @__PURE__ */ new Set()) {
@@ -319,7 +373,7 @@ function collectRailwayVolumes(value, seen = /* @__PURE__ */ new Set()) {
       ...existing,
       name: existing.name || volume.name,
       projectId: existing.projectId || volume.projectId,
-      instances: [...existing.instances, ...volume.instances]
+      instances: mergeRailwayVolumeInstances([...existing.instances, ...volume.instances])
     } : volume);
   }
   return [...byId.values()];
@@ -329,7 +383,13 @@ function railwayApiTimeoutMs(env, explicitTimeoutMs) {
     return explicitTimeoutMs;
   }
   const configured = Number.parseInt(String(env.TREESEED_RAILWAY_API_TIMEOUT_MS ?? "").trim(), 10);
-  return Number.isFinite(configured) && configured > 0 ? configured : 12e4;
+  return Number.isFinite(configured) && configured > 0 ? Math.min(configured, 15e3) : 15e3;
+}
+function assertRailwayGraphqlReadOnly(document) {
+  const operation = document.replace(/^\uFEFF/u, "").replace(/#[^\r\n]*/gu, "").trimStart();
+  if (!operation.startsWith("query ") && !operation.startsWith("query\n") && !operation.startsWith("{")) {
+    throw new Error("Direct Railway GraphQL is read-only. Use the official Railway SDK/IaC client, or the managed Railway CLI when the public SDK lacks the operation.");
+  }
 }
 async function railwayGraphqlRequest({
   query,
@@ -339,19 +399,26 @@ async function railwayGraphqlRequest({
   apiUrl,
   fetchImpl = fetch,
   timeoutMs,
-  retries = 4
+  retries = 3
 }) {
+  assertRailwayGraphqlReadOnly(query);
   const token = apiToken || resolveRailwayApiToken(env);
   if (!token) {
     throw new Error("Configure TREESEED_RAILWAY_API_TOKEN before invoking Railway APIs.");
   }
   const requestTimeoutMs = railwayApiTimeoutMs(env, timeoutMs);
+  if (env.TREESEED_RECONCILE_TRACE === "1") {
+    process.stderr.write(`[trsd][railway][api:request] timeoutMs=${requestTimeoutMs} retries=${retries}
+`);
+  }
   let attempt = 0;
   for (; ; ) {
     const controller = new AbortController();
     let timer = null;
+    let releaseReadSlot = null;
     try {
-      const response = fetchImpl === fetch ? await railwayGraphqlHttpsRequest(apiUrl || resolveRailwayApiUrl(env), token, { query, variables }, requestTimeoutMs) : await Promise.race([
+      releaseReadSlot = await acquireRailwayReadSlot();
+      const response = await Promise.race([
         fetchImpl(apiUrl || resolveRailwayApiUrl(env), {
           method: "POST",
           headers: {
@@ -381,7 +448,9 @@ async function railwayGraphqlRequest({
         const shouldRetry = isRetryableRailwayStatus(response.status) || /rate limit|too many requests/iu.test(message);
         const error = new Error(message);
         if (shouldRetry || hasGraphqlErrors && /rate limit|too many requests/iu.test(message)) {
-          throw markRailwayTransientError(error, { retryAfterMs });
+          const rateLimited = response.status === 429 || /rate limit|too many requests/iu.test(message);
+          if (rateLimited) extendRailwayReadCooldown(retryAfterMs ?? 15e3);
+          throw markRailwayTransientError(error, { retryAfterMs, rateLimited });
         }
         throw error;
       }
@@ -392,76 +461,28 @@ async function railwayGraphqlRequest({
       }
       attempt += 1;
       const retryAfterMs = error && typeof error === "object" && typeof error.treeseedRetryAfterMs === "number" ? Math.max(0, Number(error.treeseedRetryAfterMs)) : null;
-      const backoffMs = retryAfterMs ?? Math.min(500 * 2 ** (attempt - 1), 4e3);
-      await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      const rateLimited = error && typeof error === "object" && error.treeseedRateLimited === true;
+      const backoffMs = retryAfterMs !== null ? Math.min(retryAfterMs, 18e4) : rateLimited ? [15e3, 45e3, 9e4][attempt - 1] ?? 9e4 : Math.min(500 * 2 ** (attempt - 1), 4e3);
+      if (rateLimited) process.stderr.write(`[trsd][railway][api:rate-limit] attempt=${attempt + 1} waitMs=${backoffMs}
+`);
+      let remainingMs = backoffMs;
+      while (remainingMs > 0) {
+        const sliceMs = Math.min(15e3, remainingMs);
+        await new Promise((resolve2) => setTimeout(resolve2, sliceMs));
+        remainingMs -= sliceMs;
+        if (rateLimited && remainingMs > 0) {
+          process.stderr.write(`[trsd][railway][api:rate-limit] cooldownRemainingMs=${remainingMs}
+`);
+        }
+      }
     } finally {
+      releaseReadSlot?.();
       if (timer) {
         clearTimeout(timer);
       }
     }
   }
 }
-async function railwayGraphqlHttpsRequest(url, token, body, timeoutMs) {
-  const rawBody = JSON.stringify(body);
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    let req = null;
-    const hardTimeout = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      const error = markRailwayTransientError(new Error(`Railway API request timed out after ${timeoutMs}ms.`));
-      if (req) {
-        req.destroy(error);
-      }
-      reject(error);
-    }, timeoutMs);
-    const finish = (callback) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(hardTimeout);
-      callback();
-    };
-    req = httpsRequest(url, {
-      method: "POST",
-      headers: {
-        authorization: `Bearer ${token}`,
-        "content-type": "application/json",
-        "content-length": Buffer.byteLength(rawBody)
-      },
-      timeout: timeoutMs
-    }, (res) => {
-      const chunks = [];
-      res.setEncoding("utf8");
-      res.on("data", (chunk) => chunks.push(chunk));
-      res.on("end", () => {
-        const text = chunks.join("");
-        let payload = {};
-        try {
-          payload = text ? JSON.parse(text) : {};
-        } catch {
-          payload = {};
-        }
-        const status = res.statusCode ?? 0;
-        const retryAfterHeader = res.headers["retry-after"];
-        finish(() => resolve({
-          ok: status >= 200 && status < 300,
-          status,
-          payload,
-          retryAfter: Array.isArray(retryAfterHeader) ? retryAfterHeader[0] ?? null : retryAfterHeader ?? null
-        }));
-      });
-    });
-    req.on("timeout", () => {
-      const error = markRailwayTransientError(new Error(`Railway API request timed out after ${timeoutMs}ms.`));
-      if (!settled) {
-        req?.destroy(error);
-      }
-    });
-    req.on("error", (error) => finish(() => reject(error)));
-    req.write(rawBody);
-    req.end();
-  });
-}
 async function getRailwayAuthProfile({
   env = process.env,
   fetchImpl = fetch
@@ -606,44 +627,14 @@ async function ensureRailwayProject({
   if (!desiredProjectName) {
     throw new Error("Railway project creation requires a project name.");
   }
-  const created = await railwayGraphqlRequest({
-    query: `
-mutation TreeseedRailwayProjectCreate($input: ProjectCreateInput!) {
-	projectCreate(input: $input) {
-		id
-		name
-		workspaceId
-		deletedAt
-		environments(first: 50) {
-			edges {
-				node {
-					id
-					name
-				}
-			}
-		}
-		services(first: 50) {
-			edges {
-				node {
-					id
-					name
-				}
-			}
-		}
-	}
-}
-`.trim(),
-    variables: {
-      input: {
-        name: desiredProjectName,
-        workspaceId: workspaceContext.id,
-        defaultEnvironmentName
-      }
-    },
-    env,
-    fetchImpl
-  });
-  const project = created.data?.projectCreate ? normalizeProject(created.data.projectCreate) : null;
+  void defaultEnvironmentName;
+  const tempRoot = mkdtempSync(resolve(tmpdir(), "treeseed-railway-init-"));
+  try {
+    await runRailwayCliJson({ args: ["init", "--name", desiredProjectName, "--workspace", workspaceContext.id, "--json"], env, cwd: tempRoot });
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+  const project = (await listRailwayProjects({ env, workspaceId: workspaceContext.id, fetchImpl })).find((entry) => entry.name === desiredProjectName && !entry.deletedAt) ?? null;
   if (!project) {
     throw new Error(`Railway project create did not return a usable project for ${desiredProjectName}.`);
   }
@@ -660,26 +651,14 @@ async function ensureRailwayEnvironment({
   if (existing) {
     return { environment: existing, created: false };
   }
-  const created = await railwayGraphqlRequest({
-    query: `
-mutation TreeseedRailwayEnvironmentCreate($input: EnvironmentCreateInput!) {
-	environmentCreate(input: $input) {
-		id
-		name
-	}
-}
-`.trim(),
-    variables: {
-      input: {
-        projectId,
-        name: environmentName,
-        skipInitialDeploys: true
-      }
-    },
-    env,
-    fetchImpl
-  });
-  const environment = created.data?.environmentCreate ? normalizeEnvironment(created.data.environmentCreate) : null;
+  const tempRoot = mkdtempSync(resolve(tmpdir(), "treeseed-railway-environment-"));
+  try {
+    await runRailwayCliJson({ args: ["link", projectId, "--json"], env, cwd: tempRoot });
+    await runRailwayCliJson({ args: ["environment", "new", environmentName, "--json"], env, cwd: tempRoot });
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+  const environment = (await listRailwayEnvironments({ projectId, env, fetchImpl })).find((entry) => entry.name === environmentName) ?? null;
   if (!environment) {
     throw new Error(`Railway environment create did not return a usable environment for ${environmentName}.`);
   }
@@ -774,7 +753,9 @@ async function ensureRailwayService({
     if (desiredSourceRepo) {
       try {
         await updateRailwayServiceGitSource({
+          projectId,
           serviceId: existing.id,
+          environmentId,
           sourceRepo: desiredSourceRepo,
           sourceBranch,
           env,
@@ -793,7 +774,9 @@ async function ensureRailwayService({
     if (desiredImageRef) {
       try {
         await updateRailwayServiceImageSource({
+          projectId,
           serviceId: existing.id,
+          environmentId,
           imageRef: desiredImageRef,
           env,
           fetchImpl
@@ -836,36 +819,27 @@ async function createRailwayImageService({
 }) {
   const desiredSourceRepo = railwayConnectionLabel(sourceRepo);
   const desiredImageRef = railwayConnectionLabel(imageRef);
-  const created = await railwayGraphqlRequest({
-    query: `
-mutation TreeseedRailwayServiceCreate($input: ServiceCreateInput!) {
-	serviceCreate(input: $input) {
-		id
-		name
-	}
-}
-`.trim(),
-    variables: {
-      input: {
-        projectId,
-        name: serviceName,
-        ...railwayConnectionLabel(environmentId) ? { environmentId: railwayConnectionLabel(environmentId) } : {},
-        ...desiredSourceRepo ? {
-          source: {
-            repo: desiredSourceRepo
-          },
-          ...railwayConnectionLabel(sourceBranch) ? { branch: railwayConnectionLabel(sourceBranch) } : {}
-        } : desiredImageRef ? {
-          source: {
-            image: desiredImageRef
-          }
-        } : {}
+  const targetEnvironmentId = railwayConnectionLabel(environmentId);
+  if (!targetEnvironmentId) throw new Error(`Railway service creation requires an environment id for ${serviceName}.`);
+  const client = createRailwayEnvironmentPatchClient({ env, fetchImpl });
+  await client.stageEnvironmentChanges({
+    environmentId: targetEnvironmentId,
+    merge: true,
+    patch: {
+      services: {
+        [serviceName]: {
+          isCreated: true,
+          source: desiredSourceRepo ? { repo: desiredSourceRepo, branch: railwayConnectionLabel(sourceBranch) || null, image: null } : desiredImageRef ? { image: desiredImageRef, repo: null, branch: null } : null
+        }
       }
-    },
-    env,
-    fetchImpl
+    }
+  });
+  await client.commitStagedPatch({
+    environmentId: targetEnvironmentId,
+    message: `Treeseed create service ${serviceName}`,
+    skipDeploys: true
   });
-  const service = created.data?.serviceCreate ? normalizeService(created.data.serviceCreate) : null;
+  const service = (await listRailwayServices({ projectId, env, fetchImpl })).find((entry) => entry.name === serviceName) ?? null;
   if (!service) {
     throw new Error(`Railway service create did not return a usable service for ${serviceName}.`);
   }
@@ -876,87 +850,50 @@ function looksLikeRailwayImageSourceUpdateUnsupported(error) {
   return /Problem processing request|source|image|ServiceUpdateInput/iu.test(message);
 }
 async function updateRailwayServiceImageSource({
+  projectId,
   serviceId,
+  environmentId,
   imageRef,
-  env = process.env,
-  fetchImpl = fetch
+  env = process.env
 }) {
   const desiredImage = railwayConnectionLabel(imageRef);
   if (!serviceId || !desiredImage) {
     throw new Error("Railway service image source update requires a service id and image reference.");
   }
-  const payload = await railwayGraphqlRequest({
-    query: `
-mutation TreeseedRailwayServiceImageSourceUpdate($id: String!, $input: ServiceConnectInput!) {
-	serviceConnect(id: $id, input: $input) {
-		id
-		name
-	}
-}
-`.trim(),
-    variables: {
-      id: serviceId,
-      input: {
-        image: desiredImage
-      }
-    },
-    env,
-    fetchImpl
+  const targetEnvironmentId = railwayConnectionLabel(environmentId);
+  if (!targetEnvironmentId) throw new Error(`Railway service image source update requires an environment id for ${serviceId}.`);
+  await connectRailwayServiceSourceWithCli({
+    projectId,
+    environmentId: targetEnvironmentId,
+    serviceId,
+    image: desiredImage,
+    env
   });
-  const service = payload.data?.serviceConnect ? normalizeService(payload.data.serviceConnect) : null;
-  if (!service) {
-    throw new Error(`Railway service image source update did not return a usable service for ${serviceId}.`);
-  }
-  return service;
+  return { id: serviceId, name: serviceId };
 }
 async function updateRailwayServiceGitSource({
+  projectId,
   serviceId,
+  environmentId,
   sourceRepo,
   sourceBranch,
-  env = process.env,
-  fetchImpl = fetch
+  env = process.env
 }) {
   const desiredRepo = railwayConnectionLabel(sourceRepo);
   if (!serviceId || !desiredRepo) {
     throw new Error("Railway service Git source update requires a service id and repository slug.");
   }
-  const connect = async (repo) => {
-    const payload2 = await railwayGraphqlRequest({
-      query: `
-mutation TreeseedRailwayServiceGitSourceUpdate($id: String!, $input: ServiceConnectInput!) {
-	serviceConnect(id: $id, input: $input) {
-		id
-		name
-	}
-}
-`.trim(),
-      variables: {
-        id: serviceId,
-        input: {
-          repo,
-          ...railwayConnectionLabel(sourceBranch) ? { branch: railwayConnectionLabel(sourceBranch) } : {}
-        }
-      },
-      env,
-      fetchImpl
-    });
-    return payload2;
-  };
-  let payload;
-  try {
-    payload = await connect(desiredRepo);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error ?? "");
-    if (!/User does not have access to the repo/iu.test(message) || /^https?:\/\//iu.test(desiredRepo)) {
-      throw error;
-    }
-    payload = await connect(`https://github.com/${desiredRepo}`);
-  }
-  const service = payload.data?.serviceConnect ? normalizeService(payload.data.serviceConnect) : null;
-  if (!service) {
-    throw new Error(`Railway service Git source update did not return a usable service for ${serviceId}.`);
-  }
-  return service;
+  const targetEnvironmentId = railwayConnectionLabel(environmentId);
+  if (!targetEnvironmentId) throw new Error(`Railway service Git source update requires an environment id for ${serviceId}.`);
+  await connectRailwayServiceSourceWithCli({
+    projectId,
+    environmentId: targetEnvironmentId,
+    serviceId,
+    repo: desiredRepo,
+    branch: railwayConnectionLabel(sourceBranch) || null,
+    env
+  });
+  return { id: serviceId, name: serviceId };
 }
 async function ensureRailwayGeneratedServiceDomain({
   projectId,
@@ -971,48 +908,21 @@ async function ensureRailwayGeneratedServiceDomain({
   if (existing) {
     return { domain: existing, created: false };
   }
-  const query = `
-mutation TreeseedRailwayServiceDomainCreate($input: ServiceDomainCreateInput!) {
-	serviceDomainCreate(input: $input) {
-		id
-		domain
-		serviceId
-		environmentId
-		targetPort
-	}
-}
-`.trim();
-  const inputWithProject = {
-    projectId,
-    environmentId,
-    serviceId,
-    ...Number.isFinite(Number(targetPort)) ? { targetPort: Number(targetPort) } : {}
-  };
-  const createPayload = async (input) => railwayGraphqlRequest({
-    query,
-    variables: {
-      input: {
-        ...input
-      }
-    },
-    env,
-    fetchImpl
-  });
-  let payload;
-  try {
-    payload = await createPayload(inputWithProject);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error ?? "");
-    if (!/Problem processing request|projectId|not defined by type/iu.test(message)) {
-      throw error;
-    }
-    payload = await createPayload({
+  await runRailwayCliJson({
+    args: [
+      "domain",
+      "--project",
+      projectId,
+      "--environment",
       environmentId,
+      "--service",
       serviceId,
-      ...Number.isFinite(Number(targetPort)) ? { targetPort: Number(targetPort) } : {}
-    });
-  }
-  const domain = normalizeRailwayDomain(payload.data?.serviceDomainCreate);
+      ...Number.isFinite(Number(targetPort)) ? ["--port", String(Number(targetPort))] : [],
+      "--json"
+    ],
+    env
+  });
+  const domain = (await listRailwayServiceDomains({ projectId, environmentId, serviceId, env, fetchImpl })).find((entry) => entry.kind === "service" || entry.domain.endsWith(".railway.app")) ?? null;
   if (!domain) {
     throw new Error("Railway service domain create did not return a usable domain.");
   }
@@ -1057,29 +967,20 @@ query TreeseedRailwayServiceDomains($projectId: String!, $environmentId: String!
   ];
 }
 async function deployRailwayServiceInstance({
+  projectId,
   serviceId,
   environmentId,
   env = process.env,
   fetchImpl = fetch
 }) {
-  const payload = await railwayGraphqlRequest({
-    query: `
-mutation TreeseedRailwayServiceInstanceDeploy($serviceId: String!, $environmentId: String!) {
-	serviceInstanceDeployV2(serviceId: $serviceId, environmentId: $environmentId)
-}
-`.trim(),
-    variables: { serviceId, environmentId },
-    env,
-    fetchImpl
+  void fetchImpl;
+  const targetProjectId = railwayConnectionLabel(projectId) || configuredEnvValue(env, "TREESEED_RAILWAY_PROJECT_ID");
+  if (!targetProjectId) throw new Error(`Railway CLI redeploy requires a project id for service ${serviceId}.`);
+  const result = await runRailwayCliJson({
+    args: ["service", "redeploy", "--project", targetProjectId, "--environment", environmentId, "--service", serviceId, "--from-source", "--yes", "--json"],
+    env
   });
-  const value = payload.data?.serviceInstanceDeployV2;
-  if (typeof value === "string" && value.trim()) {
-    return { deploymentId: value.trim() };
-  }
-  if (value && typeof value === "object") {
-    return { deploymentId: railwayConnectionLabel(value.id) || null };
-  }
-  return { deploymentId: null };
+  return { deploymentId: railwayConnectionLabel(result.deploymentId ?? result.id) || null };
 }
 async function updateRailwayServiceName({
   serviceId,
@@ -1091,27 +992,9 @@ async function updateRailwayServiceName({
   if (!serviceId || !desiredName) {
     throw new Error("Railway service rename requires a service id and name.");
   }
-  const payload = await railwayGraphqlRequest({
-    query: `
-mutation TreeseedRailwayServiceUpdate($id: String!, $input: ServiceUpdateInput!) {
-	serviceUpdate(id: $id, input: $input) {
-		id
-		name
-	}
-}
-`.trim(),
-    variables: {
-      id: serviceId,
-      input: { name: desiredName }
-    },
-    env,
-    fetchImpl
-  });
-  const service = payload.data?.serviceUpdate ? normalizeService(payload.data.serviceUpdate) : null;
-  if (!service) {
-    throw new Error(`Railway service rename did not return a usable service for ${desiredName}.`);
-  }
-  return service;
+  void env;
+  void fetchImpl;
+  throw new Error(`Railway service rename ${serviceId} -> ${desiredName} is not exposed by the official SDK or CLI; direct GraphQL mutation is prohibited.`);
 }
 async function ensureRailwayPostgresService({
   projectId,
@@ -1208,34 +1091,10 @@ async function deployRailwayTemplate({
   env = process.env,
   fetchImpl = fetch
 }) {
-  const workspace = await resolveRailwayWorkspaceContext({ env, fetchImpl });
-  const payload = await railwayGraphqlRequest({
-    query: `
-mutation TreeseedRailwayTemplateDeploy($input: TemplateDeployV2Input!) {
-	templateDeployV2(input: $input) {
-		projectId
-		workflowId
-	}
-}
-`.trim(),
-    variables: {
-      input: {
-        templateId,
-        serializedConfig,
-        projectId,
-        environmentId,
-        workspaceId: workspace.id
-      }
-    },
-    env,
-    fetchImpl,
-    timeoutMs: 2e4,
-    retries: 1
-  });
-  if (!payload.data?.templateDeployV2?.projectId) {
-    throw new Error("Railway Postgres template deployment did not return a project id.");
-  }
-  return payload.data.templateDeployV2;
+  void serializedConfig;
+  void env;
+  void fetchImpl;
+  throw new Error(`Railway template deployment ${templateId} into ${projectId}/${environmentId} is not exposed non-interactively by the official SDK or CLI; direct GraphQL mutation is prohibited.`);
 }
 async function waitForRailwayPostgresTemplateService({
   projectId,
@@ -1262,7 +1121,7 @@ async function waitForRailwayPostgresTemplateService({
       }
       lastProof = proof;
     }
-    await new Promise((resolve) => setTimeout(resolve, 3e3));
+    await new Promise((resolve2) => setTimeout(resolve2, 3e3));
   }
   throw new Error(`Railway Postgres template deployment did not produce a managed PostgreSQL service named ${desiredServiceName}. Last proof: ${lastProof?.message ?? "no candidate service observed"}`);
 }
@@ -1325,10 +1184,13 @@ query TreeseedRailwayServiceDeploymentHealth($serviceId: String!, $environmentId
   return {
     ok,
     status,
+    deploymentStopped: stopped,
+    instanceStatuses,
     branch: railwayConnectionLabel(deployment?.meta?.branch) || null,
     repo: railwayConnectionLabel(deployment?.meta?.repo) || null,
     rootDirectory: railwayConnectionLabel(deployment?.meta?.rootDirectory) || null,
     commitHash: railwayConnectionLabel(deployment?.meta?.commitHash) || null,
+    image: railwayConnectionLabel(deployment?.meta?.image) || null,
     requiredMountPath: railwayConnectionLabel(deployment?.meta?.serviceManifest?.deploy?.requiredMountPath) || null,
     volumeMounts: Array.isArray(deployment?.meta?.volumeMounts) ? deployment.meta.volumeMounts.map((entry) => railwayConnectionLabel(entry)).filter(Boolean) : [],
     message: ok ? "Deployment is healthy." : `Latest deployment status is ${status ?? "unknown"}${stopped ? " and stopped" : ""}${instanceStatuses.length ? `; instances=${instanceStatuses.join(",")}` : ""}.`
@@ -1485,7 +1347,7 @@ async function ensureRailwayServiceInstanceConfiguration({
   let current = await getRailwayServiceInstance({ serviceId, environmentId, env, fetchImpl });
   if (!current.id) {
     for (let attempt = 0; attempt < settleAttempts && !current.id; attempt += 1) {
-      await new Promise((resolve) => setTimeout(resolve, settleDelayMs));
+      await new Promise((resolve2) => setTimeout(resolve2, settleDelayMs));
       current = await getRailwayServiceInstance({ serviceId, environmentId, env, fetchImpl });
     }
   }
@@ -1523,48 +1385,40 @@ async function ensureRailwayServiceInstanceConfiguration({
   if (!drifted) {
     return { instance: current, updated: false };
   }
-  const mutationQuery = needsRuntimeConfig ? `
-mutation TreeseedRailwayServiceInstanceUpdate($serviceId: String!, $environmentId: String!, $input: ServiceInstanceUpdateInput!) {
-	serviceInstanceUpdate(serviceId: $serviceId, environmentId: $environmentId, input: $input)
-}
-`.trim() : `
-mutation TreeseedRailwayServiceInstanceUpdateLegacy($serviceId: String!, $environmentId: String!, $input: ServiceInstanceUpdateInput!) {
-	serviceInstanceUpdate(serviceId: $serviceId, environmentId: $environmentId, input: $input)
-}
-`.trim();
-  try {
-    await railwayGraphqlRequest({
-      query: mutationQuery,
-      variables: {
-        serviceId,
-        environmentId,
-        input: {
-          ...desired.buildCommand !== null || clearSourceConfiguration && current.buildCommand !== null ? { buildCommand: desired.buildCommand } : {},
-          ...desired.dockerfilePath !== null || clearSourceConfiguration && current.dockerfilePath !== null ? { dockerfilePath: desired.dockerfilePath } : {},
-          ...desired.railwayConfigFile !== null || clearSourceConfiguration && current.railwayConfigFile !== null ? { railwayConfigFile: desired.railwayConfigFile } : {},
-          ...desired.startCommand !== null || clearSourceConfiguration && current.startCommand !== null ? { startCommand: desired.startCommand } : {},
-          ...desired.cronSchedule !== null ? { cronSchedule: desired.cronSchedule } : {},
-          ...desired.rootDirectory !== null || clearSourceConfiguration && current.rootDirectory !== null ? { rootDirectory: desired.rootDirectory } : {},
-          ...desired.healthcheckPath !== null ? { healthcheckPath: desired.healthcheckPath } : {},
-          ...desired.healthcheckTimeoutSeconds !== null ? { healthcheckTimeout: desired.healthcheckTimeoutSeconds } : {},
-          ...desired.sleepApplication !== null ? { sleepApplication: desired.sleepApplication } : {},
-          ...desired.deploymentRegion !== null ? {
-            multiRegionConfig: {
-              [desired.deploymentRegion]: { numReplicas: 1 }
-            }
-          } : {}
+  const client = createRailwayEnvironmentPatchClient({ env, fetchImpl });
+  await client.stageEnvironmentChanges({
+    environmentId,
+    merge: true,
+    patch: {
+      services: {
+        [serviceId]: {
+          build: {
+            ...desired.buildCommand !== null || clearSourceConfiguration ? { buildCommand: desired.buildCommand } : {},
+            ...desired.dockerfilePath !== null || clearSourceConfiguration ? { dockerfilePath: desired.dockerfilePath } : {}
+          },
+          ...desired.railwayConfigFile !== null || clearSourceConfiguration ? { configFile: desired.railwayConfigFile } : {},
+          ...desired.rootDirectory !== null || clearSourceConfiguration ? { source: { rootDirectory: desired.rootDirectory } } : {},
+          deploy: {
+            ...desired.startCommand !== null || clearSourceConfiguration ? { startCommand: desired.startCommand } : {},
+            ...desired.cronSchedule !== null ? { cronSchedule: desired.cronSchedule } : {},
+            ...desired.healthcheckPath !== null ? { healthcheckPath: desired.healthcheckPath } : {},
+            ...desired.healthcheckTimeoutSeconds !== null ? { healthcheckTimeout: desired.healthcheckTimeoutSeconds } : {},
+            ...desired.sleepApplication !== null ? { sleepApplication: desired.sleepApplication } : {},
+            ...desired.runtimeMode !== null ? { runtime: desired.runtimeMode } : {},
+            ...desired.deploymentRegion !== null ? {
+              region: desired.deploymentRegion,
+              multiRegionConfig: { [desired.deploymentRegion]: { numReplicas: 1 } }
+            } : {}
+          }
         }
-      },
-      env,
-      fetchImpl
-    });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error ?? "");
-    if (needsRuntimeConfig && /Field .* is not defined by type .*ServiceInstanceUpdateInput|Unknown argument|Cannot query field/iu.test(message)) {
-      throw new Error("Railway service instance runtime settings are unsupported by the current Railway API schema.");
+      }
     }
-    throw error;
-  }
+  });
+  await client.commitStagedPatch({
+    environmentId,
+    message: `Treeseed reconcile service configuration ${serviceId}`,
+    skipDeploys: true
+  });
   let instance = current;
   for (let attempt = 0; attempt <= settleAttempts; attempt += 1) {
     instance = await getRailwayServiceInstance({
@@ -1576,7 +1430,7 @@ mutation TreeseedRailwayServiceInstanceUpdateLegacy($serviceId: String!, $enviro
     if (!serviceInstanceDrifted(instance, desired, clearSourceConfiguration) || attempt >= settleAttempts) {
       break;
     }
-    await new Promise((resolve) => setTimeout(resolve, settleDelayMs));
+    await new Promise((resolve2) => setTimeout(resolve2, settleDelayMs));
   }
   return {
     instance: {
@@ -1635,67 +1489,34 @@ async function upsertRailwayVariables({
   if (Object.keys(variables).length === 0) {
     return;
   }
-  const query = `
-mutation TreeseedRailwayVariableCollectionUpsert($input: VariableCollectionUpsertInput!) {
-	variableCollectionUpsert(input: $input)
-}
-`.trim();
-  const input = {
-    projectId,
-    environmentId,
-    serviceId: serviceId || null,
-    variables,
-    replace: false,
-    skipDeploys: true
-  };
-  const upsertOne = (key, value) => railwayGraphqlRequest({
-    query,
-    variables: {
-      input: {
-        projectId,
-        environmentId,
-        serviceId: serviceId || null,
-        variables: { [key]: value },
-        replace: false,
-        skipDeploys: true
-      }
-    },
-    env,
-    fetchImpl
-  });
-  try {
-    await railwayGraphqlRequest({
-      query,
-      variables: { input },
-      env,
-      fetchImpl
+  const client = createRailwayEnvironmentPatchClient({ env, fetchImpl });
+  const applyVariablePatch = async (keys) => {
+    const variablePatch = Object.fromEntries(keys.map((key) => [key, { value: variables[key] }]));
+    await client.stageEnvironmentChanges({
+      environmentId,
+      merge: true,
+      patch: serviceId ? { services: { [serviceId]: { variables: variablePatch } } } : { sharedVariables: variablePatch }
     });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error ?? "");
-    if (!/Problem processing request/iu.test(message) || Object.keys(variables).length <= 1) {
-      throw error;
-    }
-    for (const [key, value] of Object.entries(variables)) {
-      await upsertOne(key, value);
-    }
-  }
+    await client.commitStagedPatch({
+      environmentId,
+      message: `Treeseed update ${keys.length} Railway variable${keys.length === 1 ? "" : "s"}`,
+      skipDeploys: true
+    });
+  };
+  await applyVariablePatch(Object.keys(variables));
   const expectedKeys = Object.keys(variables);
   const mismatchedKeys = (observed2) => expectedKeys.filter((key) => observed2[key] !== variables[key]);
   const observed = await listRailwayVariables({ projectId, environmentId, serviceId, env, fetchImpl }).catch(() => ({}));
   const missingOrMismatched = mismatchedKeys(observed);
-  for (const key of missingOrMismatched) {
-    await upsertOne(key, variables[key]);
-  }
+  if (missingOrMismatched.length > 0) await applyVariablePatch(missingOrMismatched);
   let retried = missingOrMismatched.length > 0 ? await listRailwayVariables({ projectId, environmentId, serviceId, env, fetchImpl }).catch(() => ({})) : observed;
   let stillMismatched = mismatchedKeys(retried);
   for (let attempt = 0; stillMismatched.length > 0 && attempt < 12; attempt += 1) {
-    await new Promise((resolve) => setTimeout(resolve, 2500));
+    await new Promise((resolve2) => setTimeout(resolve2, 2500));
     retried = await listRailwayVariables({ projectId, environmentId, serviceId, env, fetchImpl }).catch(() => ({}));
     stillMismatched = mismatchedKeys(retried);
     if (stillMismatched.length > 0 && attempt === 5) {
-      for (const key of stillMismatched) {
-        await upsertOne(key, variables[key]);
-      }
+      await applyVariablePatch(stillMismatched);
     }
   }
   if (stillMismatched.length > 0) {
@@ -1744,145 +1565,13 @@ query TreeseedRailwayVolumeList($projectId: String!) {
   });
   return collectRailwayVolumes(payload.data);
 }
-async function createRailwayVolume({
-  projectId,
-  environmentId,
-  serviceId,
-  name,
-  mountPath,
-  env = process.env,
-  fetchImpl = fetch
-}) {
-  const mutation = configuredEnvValue(env, "TREESEED_RAILWAY_VOLUME_CREATE_MUTATION") || `
-mutation TreeseedRailwayVolumeCreate($input: VolumeCreateInput!) {
-	volumeCreate(input: $input) {
-		id
-		name
-		projectId
-		volumeInstances {
-			edges {
-					node {
-						id
-						serviceId
-						environmentId
-						mountPath
-						state
-						isPendingDeletion
-						deletedAt
-					}
-				}
-			}
-	}
-}
-`.trim();
-  const payload = await railwayGraphqlRequest({
-    query: mutation,
-    variables: {
-      input: {
-        projectId,
-        environmentId,
-        serviceId,
-        mountPath
-      }
-    },
-    env,
-    fetchImpl
-  });
-  const volume = collectRailwayVolumes(payload.data)[0] ?? null;
-  if (!volume) {
-    throw new Error(`Railway volume create did not return a usable volume for ${name}.`);
-  }
-  if (name && volume.name !== name) {
-    try {
-      const renamed = await updateRailwayVolumeName({
-        volumeId: volume.id,
-        name,
-        env,
-        fetchImpl
-      });
-      return {
-        ...volume,
-        name: renamed.name || name
-      };
-    } catch {
-      return {
-        ...volume,
-        name: volume.name || name
-      };
-    }
-  }
-  return volume;
-}
-async function updateRailwayVolumeName({
-  volumeId,
-  name,
-  env = process.env,
-  fetchImpl = fetch
-}) {
-  const mutation = configuredEnvValue(env, "TREESEED_RAILWAY_VOLUME_UPDATE_MUTATION") || `
-mutation TreeseedRailwayVolumeUpdate($volumeId: String!, $input: VolumeUpdateInput!) {
-	volumeUpdate(volumeId: $volumeId, input: $input) {
-		id
-		name
-		projectId
-		volumeInstances {
-			edges {
-					node {
-						id
-						serviceId
-						environmentId
-						mountPath
-						state
-						isPendingDeletion
-						deletedAt
-					}
-				}
-			}
-	}
-}
-`.trim();
-  const payload = await railwayGraphqlRequest({
-    query: mutation,
-    variables: {
-      volumeId,
-      input: { name }
-    },
-    env,
-    fetchImpl
-  });
-  return collectRailwayVolumes(payload.data)[0] ?? null;
-}
-async function updateRailwayVolumeInstanceMountPath({
-  volumeId,
-  serviceId,
-  mountPath,
-  env = process.env,
-  fetchImpl = fetch
-}) {
-  const mutation = configuredEnvValue(env, "TREESEED_RAILWAY_VOLUME_INSTANCE_UPDATE_MUTATION") || `
-mutation TreeseedRailwayVolumeInstanceUpdate($volumeId: String!, $input: VolumeInstanceUpdateInput!) {
-	volumeInstanceUpdate(volumeId: $volumeId, input: $input)
-}
-`.trim();
-  await railwayGraphqlRequest({
-    query: mutation,
-    variables: {
-      volumeId,
-      input: {
-        ...serviceId !== void 0 ? { serviceId } : {},
-        mountPath
-      }
-    },
-    env,
-    fetchImpl
-  });
-}
 async function ensureRailwayServiceVolume({
   projectId,
   environmentId,
   serviceId,
   name,
   mountPath,
+  adoptVolumeId,
   env = process.env,
   fetchImpl = fetch,
   settleAttempts = 24,
@@ -1891,189 +1580,52 @@ async function ensureRailwayServiceVolume({
   if (!mountPath.startsWith("/")) {
     throw new Error(`Railway volume mount path must be absolute: ${mountPath}`);
   }
-  const volumes = await listRailwayVolumes({ projectId, env, fetchImpl });
-  const activeVolumes = volumes.map((candidate) => ({
-    ...candidate,
-    instances: candidate.instances.filter(isActiveRailwayVolumeInstance)
-  })).filter((candidate) => candidate.instances.length > 0);
-  const exactVolume = activeVolumes.find(
-    (candidate) => candidate.name === name && candidate.instances.some(
-      (instance2) => instance2.serviceId === serviceId && instance2.environmentId === environmentId && instance2.mountPath === mountPath
-    )
-  ) ?? null;
-  if (exactVolume) {
-    return {
-      volume: exactVolume,
-      instance: exactVolume.instances.find(
-        (instance2) => instance2.serviceId === serviceId && instance2.environmentId === environmentId && instance2.mountPath === mountPath
-      ) ?? null,
-      created: false,
-      updated: false
-    };
-  }
-  let volume = findRailwayVolumeForService(volumes, serviceId, environmentId) ?? findRailwayVolumeForService(volumes, serviceId) ?? activeVolumes.find(
-    (candidate) => candidate.name === name && candidate.instances.some((instance2) => instance2.environmentId === environmentId)
-  ) ?? activeVolumes.find(
-    (candidate) => candidate.name === name && (candidate.instances.length === 0 || candidate.instances.some((instance2) => instance2.environmentId === environmentId))
-  ) ?? null;
-  let created = false;
-  let updated = false;
-  const createReplacementVolume = async () => {
-    let replacement;
-    try {
-      replacement = await createRailwayVolume({
-        projectId,
-        environmentId,
-        serviceId,
-        name,
-        mountPath,
-        env,
-        fetchImpl
-      });
-    } catch (error) {
-      if (!looksLikeRailwayVolumeCreateRace(error)) {
-        throw error;
-      }
-      for (let attempt = 0; attempt < 8; attempt += 1) {
-        await new Promise((resolve) => setTimeout(resolve, 1500));
-        const refreshed = await listRailwayVolumes({ projectId, env, fetchImpl });
-        const activeRefreshed = refreshed.map((candidate) => ({
-          ...candidate,
-          instances: candidate.instances.filter(isActiveRailwayVolumeInstance)
-        })).filter((candidate) => candidate.instances.length > 0);
-        const existing = findRailwayVolumeForService(refreshed, serviceId, environmentId) ?? findRailwayVolumeForService(refreshed, serviceId) ?? activeRefreshed.find(
-          (candidate) => candidate.name === name && (candidate.instances.length === 0 || candidate.instances.some((instance2) => instance2.environmentId === environmentId))
-        ) ?? findSoleActiveRailwayVolumeForEnvironment(refreshed, environmentId);
-        if (existing) {
-          return existing;
-        }
-      }
-      throw error;
-    }
-    created = true;
-    return replacement;
-  };
-  if (!volume) {
-    volume = await createReplacementVolume();
-  }
-  const desiredNameInUse = volumes.some(
-    (candidate) => candidate.id !== volume?.id && candidate.name === name && candidate.instances.some(isActiveRailwayVolumeInstance)
-  );
-  if (volume.name && volume.name !== name && !desiredNameInUse) {
-    try {
-      volume = await updateRailwayVolumeName({ volumeId: volume.id, name, env, fetchImpl }) ?? { ...volume, name };
-    } catch (error) {
-      if (!looksLikeRailwayMissingResource(error)) {
-        throw error;
-      }
-      volume = await createReplacementVolume();
-    }
-    updated = true;
-  }
-  let instance = volume.instances.find((entry) => entry.serviceId === serviceId && entry.environmentId === environmentId) ?? null;
-  if (!instance && volume.instances.some((entry) => entry.environmentId === environmentId)) {
-    try {
-      await updateRailwayVolumeInstanceMountPath({ volumeId: volume.id, serviceId, mountPath, env, fetchImpl });
-      volume = await listRailwayVolumes({ projectId, env, fetchImpl }).then((refreshed) => refreshed.find((candidate) => candidate.id === volume?.id) ?? volume);
-    } catch (error) {
-      if (looksLikeRailwayVolumeCreateRace(error)) {
-        volume = await listRailwayVolumes({ projectId, env, fetchImpl }).then(
-          (refreshed) => findRailwayVolumeForService(refreshed, serviceId, environmentId) ?? volume
-        );
-      } else if (!looksLikeRailwayMissingResource(error)) {
-        throw error;
-      } else {
-        volume = await createReplacementVolume();
-      }
-    }
-    instance = volume.instances.find((entry) => entry.serviceId === serviceId && entry.environmentId === environmentId) ?? null;
-    updated = true;
-  }
-  if (!instance) {
-    try {
-      await updateRailwayVolumeInstanceMountPath({ volumeId: volume.id, serviceId, mountPath, env, fetchImpl });
-      volume = await listRailwayVolumes({ projectId, env, fetchImpl }).then((refreshed) => refreshed.find((candidate) => candidate.id === volume?.id) ?? volume);
-    } catch (error) {
-      if (looksLikeRailwayVolumeCreateRace(error)) {
-        volume = await listRailwayVolumes({ projectId, env, fetchImpl }).then(
-          (refreshed) => findRailwayVolumeForService(refreshed, serviceId, environmentId) ?? volume
-        );
-      } else if (!looksLikeRailwayMissingResource(error)) {
-        throw error;
-      } else {
-        volume = await createReplacementVolume();
-      }
-    }
-    instance = volume.instances.find((entry) => entry.serviceId === serviceId && entry.environmentId === environmentId) ?? null;
-    updated = true;
-  }
-  if (instance && instance.mountPath !== mountPath) {
-    try {
-      await updateRailwayVolumeInstanceMountPath({ volumeId: volume.id, mountPath, env, fetchImpl });
-      volume = {
-        ...volume,
-        instances: volume.instances.map((entry) => entry.id === instance.id ? { ...entry, mountPath } : entry)
+  {
+    const observed = await listRailwayVolumes({ projectId, env, fetchImpl });
+    const exact = observed.find(
+      (candidate) => candidate.name === name && candidate.instances.some(
+        (instance) => instance.serviceId === serviceId && instance.environmentId === environmentId && instance.mountPath === mountPath && isActiveRailwayVolumeInstance(instance)
+      )
+    ) ?? null;
+    if (exact) {
+      return {
+        volume: exact,
+        instance: exact.instances.find((instance) => instance.serviceId === serviceId && instance.environmentId === environmentId) ?? null,
+        created: false,
+        updated: false
       };
-    } catch (error) {
-      if (!looksLikeRailwayMissingResource(error)) {
-        throw error;
-      }
-      volume = await createReplacementVolume();
-      instance = volume.instances.find((entry) => entry.serviceId === serviceId && entry.environmentId === environmentId) ?? null;
     }
-    updated = true;
-  }
-  const settled = await waitForRailwayVolumeMount({
-    projectId,
-    volume,
-    serviceId,
-    environmentId,
-    mountPath,
-    env,
-    fetchImpl,
-    settleAttempts,
-    settleDelayMs
-  });
-  if (settled) {
-    volume = settled.volume;
-    instance = settled.instance;
-  }
-  if (!instance || instance.serviceId !== serviceId || instance.environmentId !== environmentId || instance.mountPath !== mountPath) {
-    throw new Error(`Railway API volume reconciliation did not observe ${name} mounted on service ${serviceId} at ${mountPath}.`);
-  }
-  return { volume, instance, created, updated };
-}
-async function waitForRailwayVolumeMount({
-  projectId,
-  volume,
-  serviceId,
-  environmentId,
-  mountPath,
-  env,
-  fetchImpl,
-  settleAttempts,
-  settleDelayMs
-}) {
-  const mountedInstance = (candidate) => candidate.instances.find(
-    (entry) => entry.serviceId === serviceId && entry.environmentId === environmentId && entry.mountPath === mountPath && isActiveRailwayVolumeInstance(entry)
-  ) ?? null;
-  let instance = mountedInstance(volume);
-  if (instance) {
-    return { volume, instance };
-  }
-  for (let attempt = 0; attempt < settleAttempts; attempt += 1) {
-    await new Promise((resolve) => setTimeout(resolve, settleDelayMs));
-    const refreshed = await listRailwayVolumes({ projectId, env, fetchImpl });
-    const refreshedVolume = refreshed.find((candidate) => candidate.id === volume.id) ?? findRailwayVolumeForService(refreshed, serviceId, environmentId) ?? null;
-    if (!refreshedVolume) {
-      continue;
+    const requestedAdoption = railwayConnectionLabel(adoptVolumeId);
+    const adoptable = requestedAdoption ? observed.find((candidate) => candidate.id === requestedAdoption) ?? null : observed.find((candidate) => candidate.name === name) ?? findRailwayVolumeForService(observed, serviceId, environmentId) ?? null;
+    if (requestedAdoption && !adoptable) {
+      throw new Error(`Railway volume ${requestedAdoption} cannot be adopted because it was not found; refusing to create an empty replacement volume.`);
     }
-    instance = mountedInstance(refreshedVolume);
-    if (instance) {
-      return { volume: refreshedVolume, instance };
+    const volumeKey = adoptable?.id ?? name;
+    const client = createRailwayEnvironmentPatchClient({ env, fetchImpl });
+    await client.stageEnvironmentChanges({
+      environmentId,
+      merge: true,
+      patch: {
+        volumes: { [volumeKey]: adoptable ? { isDeleted: false } : { isCreated: true } },
+        services: { [serviceId]: { volumeMounts: { [volumeKey]: { mountPath } } } }
+      }
+    });
+    await client.commitStagedPatch({
+      environmentId,
+      message: `Treeseed reconcile volume ${name}`,
+      skipDeploys: true
+    });
+    for (let attempt = 0; attempt <= settleAttempts; attempt += 1) {
+      if (attempt > 0) await new Promise((resolve2) => setTimeout(resolve2, settleDelayMs));
+      const refreshed = await listRailwayVolumes({ projectId, env, fetchImpl });
+      const volume = refreshed.find((candidate) => candidate.id === adoptable?.id || candidate.name === name) ?? null;
+      const instance = volume?.instances.find(
+        (entry) => entry.serviceId === serviceId && entry.environmentId === environmentId && entry.mountPath === mountPath && isActiveRailwayVolumeInstance(entry)
+      ) ?? null;
+      if (volume && instance) return { volume, instance, created: !adoptable, updated: Boolean(adoptable) };
     }
+    throw new Error(`Railway SDK volume reconciliation did not observe ${name} mounted on service ${serviceId} at ${mountPath}.`);
   }
-  return null;
 }
 function findRailwayVolumeForService(volumes, serviceId, environmentId) {
   return volumes.find(
@@ -2082,19 +1634,6 @@ function findRailwayVolumeForService(volumes, serviceId, environmentId) {
     )
   ) ?? null;
 }
-function findSoleActiveRailwayVolumeForEnvironment(volumes, environmentId) {
-  const active = volumes.map((candidate) => ({
-    ...candidate,
-    instances: candidate.instances.filter(
-      (instance) => instance.environmentId === environmentId && isActiveRailwayVolumeInstance(instance)
-    )
-  })).filter((candidate) => candidate.instances.length > 0);
-  return active.length === 1 ? active[0] : null;
-}
-function looksLikeRailwayVolumeCreateRace(error) {
-  const message = error instanceof Error ? error.message : String(error ?? "");
-  return /already has a volume attached|would have \d+ volumes attached|can only have one volume|volume named .* already exists|already exists in this project|not authorized/iu.test(message);
-}
 async function listRailwayCustomDomains({
   projectId,
   environmentId,
@@ -2159,46 +1698,11 @@ async function ensureRailwayCustomDomain({
   if (matched) {
     return { domain: matched, created: false };
   }
-  const payload = await railwayGraphqlRequest({
-    query: `
-mutation TreeseedRailwayCustomDomainCreate($input: CustomDomainCreateInput!) {
-	customDomainCreate(input: $input) {
-		id
-		domain
-		environmentId
-		serviceId
-		targetPort
-		status {
-			verified
-			certificateStatus
-			verificationDnsHost
-			verificationToken
-			dnsRecords {
-				fqdn
-				hostlabel
-				recordType
-				requiredValue
-				currentValue
-				status
-				zone
-				purpose
-			}
-		}
-	}
-}
-`.trim(),
-    variables: {
-      input: {
-        projectId,
-        environmentId,
-        serviceId,
-        domain: normalizedDomain
-      }
-    },
-    env,
-    fetchImpl
+  await runRailwayCliJson({
+    args: ["domain", normalizedDomain, "--project", projectId, "--environment", environmentId, "--service", serviceId, "--json"],
+    env
   });
-  const created = payload.data?.customDomainCreate ? normalizeRailwayCustomDomain(payload.data.customDomainCreate) : null;
+  const created = (await listRailwayCustomDomains({ projectId, environmentId, serviceId, env, fetchImpl })).find((entry) => entry.domain === normalizedDomain) ?? null;
   if (!created) {
     throw new Error(`Railway custom domain create did not return a usable domain for ${normalizedDomain}.`);
   }
@@ -2241,12 +1745,15 @@ async function railwayDeleteMutation({
         throw error;
       }
       lastError = error;
-      await new Promise((resolve) => setTimeout(resolve, 2500 * (attempt + 1)));
+      await new Promise((resolve2) => setTimeout(resolve2, 2500 * (attempt + 1)));
     }
   }
   throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "Railway delete mutation did not complete."));
 }
 async function deleteRailwayCustomDomain({
+  projectId,
+  environmentId,
+  serviceId,
   domainId,
   env = process.env,
   fetchImpl = fetch
@@ -2254,20 +1761,14 @@ async function deleteRailwayCustomDomain({
   if (!railwayConnectionLabel(domainId)) {
     return { status: "missing", id: domainId };
   }
-  const mutation = configuredEnvValue(env, "TREESEED_RAILWAY_CUSTOM_DOMAIN_DELETE_MUTATION") || `
-mutation TreeseedRailwayCustomDomainDelete($id: String!) {
-	customDomainDelete(id: $id)
-}
-`.trim();
-  return railwayDeleteMutation({
-    query: mutation,
-    variables: { id: domainId },
-    env,
-    fetchImpl,
-    missingResult: { status: "missing", id: domainId }
-  });
+  void fetchImpl;
+  if (!projectId || !environmentId || !serviceId) throw new Error(`Railway CLI domain deletion requires project, environment, and service ids for ${domainId}.`);
+  await runRailwayCliJson({ args: ["domain", "delete", domainId, "--project", projectId, "--environment", environmentId, "--service", serviceId, "--yes", "--json"], env });
+  return { status: "deleted" };
 }
 async function deleteRailwayService({
+  projectId,
+  environmentId,
   serviceId,
   env = process.env,
   fetchImpl = fetch
@@ -2275,20 +1776,14 @@ async function deleteRailwayService({
   if (!railwayConnectionLabel(serviceId)) {
     return { status: "missing", id: serviceId };
   }
-  const mutation = configuredEnvValue(env, "TREESEED_RAILWAY_SERVICE_DELETE_MUTATION") || `
-mutation TreeseedRailwayServiceDelete($id: String!) {
-	serviceDelete(id: $id)
-}
-`.trim();
-  return railwayDeleteMutation({
-    query: mutation,
-    variables: { id: serviceId },
-    env,
-    fetchImpl,
-    missingResult: { status: "missing", id: serviceId }
-  });
+  void fetchImpl;
+  if (!projectId || !environmentId) throw new Error(`Railway CLI service deletion requires project and environment ids for ${serviceId}.`);
+  await runRailwayCliJson({ args: ["service", "delete", "--project", projectId, "--environment", environmentId, "--service", serviceId, "--yes", "--json"], env });
+  return { status: "deleted" };
 }
 async function deleteRailwayVolume({
+  projectId,
+  environmentId,
   volumeId,
   env = process.env,
   fetchImpl = fetch
@@ -2296,57 +1791,17 @@ async function deleteRailwayVolume({
   if (!railwayConnectionLabel(volumeId)) {
     return { status: "missing", id: volumeId };
   }
-  const configuredMutation = configuredEnvValue(env, "TREESEED_RAILWAY_VOLUME_DELETE_MUTATION");
-  if (configuredMutation) {
-    return railwayDeleteMutation({
-      query: configuredMutation,
-      variables: { volumeId, id: volumeId },
-      env,
-      fetchImpl,
-      missingResult: { status: "missing", id: volumeId }
-    });
-  }
-  const primaryMutation = `
-mutation TreeseedRailwayVolumeDelete($volumeId: String!) {
-	volumeDelete(volumeId: $volumeId)
-}
-`.trim();
-  const fallbackMutation = `
-mutation TreeseedRailwayVolumeDeleteById($id: String!) {
-	volumeDelete(volumeId: $id)
-}
-`.trim();
-  const primary = await railwayDeleteMutation({
-    query: primaryMutation,
-    variables: { volumeId },
-    env,
-    fetchImpl,
-    missingResult: { status: "missing", id: volumeId }
-  }).catch((error) => {
-    if (looksLikeRailwayVolumeDeleteShapeUnsupported(error)) {
-      return null;
-    }
-    throw error;
-  });
-  const fallback = await railwayDeleteMutation({
-    query: fallbackMutation,
-    variables: { id: volumeId },
-    env,
-    fetchImpl,
-    missingResult: { status: "missing", id: volumeId }
-  }).catch((error) => {
-    if (looksLikeRailwayVolumeDeleteShapeUnsupported(error) && primary) {
-      return primary;
-    }
-    throw error;
-  });
-  return fallback ?? primary ?? { status: "deleted" };
+  void fetchImpl;
+  if (!projectId || !environmentId) throw new Error(`Railway CLI volume deletion requires project and environment ids for ${volumeId}.`);
+  await runRailwayCliJson({ args: ["volume", "--project", projectId, "--environment", environmentId, "delete", "--volume", volumeId, "--yes", "--json"], env });
+  return { status: "deleted" };
 }
 function looksLikeRailwayVolumeDeleteShapeUnsupported(error) {
   const message = error instanceof Error ? error.message : String(error ?? "");
   return /Unknown argument|Cannot query field|Unknown field|Field .* is not defined|volumeDelete.*argument|Problem processing request/iu.test(message);
 }
 async function deleteRailwayEnvironment({
+  projectId,
   environmentId,
   env = process.env,
   fetchImpl = fetch
@@ -2354,18 +1809,16 @@ async function deleteRailwayEnvironment({
   if (!railwayConnectionLabel(environmentId)) {
     return { status: "missing", id: environmentId };
   }
-  const mutation = configuredEnvValue(env, "TREESEED_RAILWAY_ENVIRONMENT_DELETE_MUTATION") || `
-mutation TreeseedRailwayEnvironmentDelete($id: String!) {
-	environmentDelete(id: $id)
-}
-`.trim();
-  return railwayDeleteMutation({
-    query: mutation,
-    variables: { id: environmentId },
-    env,
-    fetchImpl,
-    missingResult: { status: "missing", id: environmentId }
-  });
+  void fetchImpl;
+  if (!projectId) throw new Error(`Railway CLI environment deletion requires a project id for ${environmentId}.`);
+  const tempRoot = mkdtempSync(resolve(tmpdir(), "treeseed-railway-environment-delete-"));
+  try {
+    await runRailwayCliJson({ args: ["link", projectId, "--json"], env, cwd: tempRoot });
+    await runRailwayCliJson({ args: ["environment", "delete", environmentId, "--yes", "--json"], env, cwd: tempRoot });
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+  return { status: "deleted" };
 }
 async function deleteRailwayProject({
   projectId,
@@ -2375,20 +1828,12 @@ async function deleteRailwayProject({
   if (!railwayConnectionLabel(projectId)) {
     return { status: "missing", id: projectId };
   }
-  const mutation = configuredEnvValue(env, "TREESEED_RAILWAY_PROJECT_DELETE_MUTATION") || `
-mutation TreeseedRailwayProjectDelete($id: String!) {
-	projectDelete(id: $id)
-}
-`.trim();
-  return railwayDeleteMutation({
-    query: mutation,
-    variables: { id: projectId },
-    env,
-    fetchImpl,
-    missingResult: { status: "missing", id: projectId }
-  });
+  void fetchImpl;
+  await runRailwayCliJson({ args: ["project", "delete", "--project", projectId, "--yes", "--json"], env });
+  return { status: "deleted" };
 }
 export {
+  assertRailwayGraphqlReadOnly,
   deleteRailwayCustomDomain,
   deleteRailwayEnvironment,
   deleteRailwayProject,