@treeseed/sdk 0.10.28 → 0.12.4

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

@@ -1,8 +1,7 @@
 import { request as httpsRequest } from "node:https";
+import { resolveTreeseedRailwayApiToken } from "../../service-credentials.js";
 const DEFAULT_RAILWAY_API_URL = "https://backboard.railway.com/graphql/v2";
 const DEFAULT_RAILWAY_WORKSPACE = "knowledge-coop";
-const RAILWAY_POSTGRES_TEMPLATE_ID = "b55da7dc-09be-4140-bc65-1284d15d349c";
-const RAILWAY_POSTGRES_TEMPLATE_SERVICE_ID = "b55da7dc-09be-4140-bc65-1284b15d349b";
 function normalizeRailwayEnvironmentName(value) {
   const normalized = typeof value === "string" ? value.trim() : "";
   if (!normalized) {
@@ -18,7 +17,7 @@ function isUsableRailwayToken(value) {
   return typeof value === "string" && value.trim().length >= 8;
 }
 function resolveRailwayApiToken(env = process.env) {
-  const token = configuredEnvValue(env, "RAILWAY_API_TOKEN");
+  const token = resolveTreeseedRailwayApiToken(env);
   return isUsableRailwayToken(token) ? token : "";
 }
 function resolveRailwayApiUrl(env = process.env) {
@@ -113,15 +112,36 @@ function normalizeProject(node) {
   if (!id || !name) {
     return null;
   }
+  const services = /* @__PURE__ */ new Map();
+  for (const service of normalizeConnectionNodes(node.services, normalizeService)) {
+    services.set(service.id, service);
+  }
+  for (const environment of normalizeConnectionNodes(node.environments, (entry) => entry)) {
+    for (const instance of normalizeConnectionNodes(environment.serviceInstances, (entry) => entry)) {
+      const serviceId = railwayConnectionLabel(instance.serviceId);
+      const serviceName = railwayConnectionLabel(instance.serviceName);
+      if (serviceId && serviceName) {
+        services.set(serviceId, { id: serviceId, name: serviceName });
+      }
+    }
+  }
   return {
     id,
     name,
     workspaceId: railwayConnectionLabel(node.workspaceId) || null,
     deletedAt: railwayConnectionLabel(node.deletedAt) || null,
     environments: normalizeConnectionNodes(node.environments, normalizeEnvironment),
-    services: normalizeConnectionNodes(node.services, normalizeService)
+    services: [...services.values()]
   };
 }
+function normalizeServiceInstanceService(node) {
+  const id = railwayConnectionLabel(node.serviceId);
+  const name = railwayConnectionLabel(node.serviceName);
+  if (!id || !name) {
+    return null;
+  }
+  return { id, name };
+}
 function normalizeVariableMap(value) {
   if (!value) {
     return {};
@@ -195,6 +215,31 @@ function normalizeRailwayCustomDomain(node) {
     dnsRecords
   };
 }
+function normalizeRailwayDomain(node, kind = "service") {
+  if (!node || typeof node !== "object") {
+    return null;
+  }
+  const record = node;
+  const id = railwayConnectionLabel(record.id) || railwayConnectionLabel(record.domain);
+  const domain = railwayConnectionLabel(record.domain);
+  if (!id || !domain) {
+    return null;
+  }
+  return {
+    id,
+    domain,
+    kind,
+    environmentId: railwayConnectionLabel(record.environmentId),
+    serviceId: railwayConnectionLabel(record.serviceId),
+    targetPort: normalizeRailwayNumber(record.targetPort)
+  };
+}
+function normalizeRailwayDomainList(value, kind) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => normalizeRailwayDomain(entry, kind)).filter(Boolean);
+}
 function normalizeRailwayVolumeInstance(node) {
   const id = railwayConnectionLabel(node.id);
   if (!id) {
@@ -208,13 +253,15 @@ function normalizeRailwayVolumeInstance(node) {
     environmentId: railwayConnectionLabel(node.environmentId) || railwayConnectionLabel(node.environment?.id) || null,
     mountPath: railwayConnectionLabel(node.mountPath) || railwayConnectionLabel(node.mount_path) || null,
     state: railwayConnectionLabel(node.state) || null,
+    isPendingDeletion: node.isPendingDeletion === true || node.pendingDeletion === true,
+    deletedAt: railwayConnectionLabel(node.deletedAt) || null,
     sizeGb,
     usedGb
   };
 }
 function isActiveRailwayVolumeInstance(instance) {
   const state = String(instance.state ?? "READY").toUpperCase();
-  return state !== "DELETING" && state !== "DELETED";
+  return !instance.isPendingDeletion && !(typeof instance.deletedAt === "string" && instance.deletedAt.trim()) && state !== "DELETING" && state !== "DELETED";
 }
 function normalizeVolumeInstances(value) {
   const direct = Array.isArray(value) ? value : null;
@@ -277,6 +324,13 @@ function collectRailwayVolumes(value, seen = /* @__PURE__ */ new Set()) {
   }
   return [...byId.values()];
 }
+function railwayApiTimeoutMs(env, explicitTimeoutMs) {
+  if (typeof explicitTimeoutMs === "number" && Number.isFinite(explicitTimeoutMs) && explicitTimeoutMs > 0) {
+    return explicitTimeoutMs;
+  }
+  const configured = Number.parseInt(String(env.TREESEED_RAILWAY_API_TIMEOUT_MS ?? "").trim(), 10);
+  return Number.isFinite(configured) && configured > 0 ? configured : 12e4;
+}
 async function railwayGraphqlRequest({
   query,
   variables,
@@ -284,19 +338,20 @@ async function railwayGraphqlRequest({
   apiToken,
   apiUrl,
   fetchImpl = fetch,
-  timeoutMs = 3e4,
-  retries = 8
+  timeoutMs,
+  retries = 4
 }) {
   const token = apiToken || resolveRailwayApiToken(env);
   if (!token) {
-    throw new Error("Configure RAILWAY_API_TOKEN before invoking Railway APIs.");
+    throw new Error("Configure TREESEED_RAILWAY_API_TOKEN before invoking Railway APIs.");
   }
+  const requestTimeoutMs = railwayApiTimeoutMs(env, timeoutMs);
   let attempt = 0;
   for (; ; ) {
     const controller = new AbortController();
     let timer = null;
     try {
-      const response = fetchImpl === fetch ? await railwayGraphqlHttpsRequest(apiUrl || resolveRailwayApiUrl(env), token, { query, variables }, timeoutMs) : await Promise.race([
+      const response = fetchImpl === fetch ? await railwayGraphqlHttpsRequest(apiUrl || resolveRailwayApiUrl(env), token, { query, variables }, requestTimeoutMs) : await Promise.race([
         fetchImpl(apiUrl || resolveRailwayApiUrl(env), {
           method: "POST",
           headers: {
@@ -314,8 +369,8 @@ async function railwayGraphqlRequest({
         new Promise((_, reject) => {
           timer = setTimeout(() => {
             controller.abort();
-            reject(markRailwayTransientError(new Error(`Railway API request timed out after ${timeoutMs}ms.`)));
-          }, timeoutMs);
+            reject(markRailwayTransientError(new Error(`Railway API request timed out after ${requestTimeoutMs}ms.`)));
+          }, requestTimeoutMs);
         })
       ]);
       const payload = response.payload;
@@ -349,7 +404,24 @@ async function railwayGraphqlRequest({
 async function railwayGraphqlHttpsRequest(url, token, body, timeoutMs) {
   const rawBody = JSON.stringify(body);
   return new Promise((resolve, reject) => {
-    const req = httpsRequest(url, {
+    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}`,
@@ -371,18 +443,21 @@ async function railwayGraphqlHttpsRequest(url, token, body, timeoutMs) {
         }
         const status = res.statusCode ?? 0;
         const retryAfterHeader = res.headers["retry-after"];
-        resolve({
+        finish(() => resolve({
           ok: status >= 200 && status < 300,
           status,
           payload,
           retryAfter: Array.isArray(retryAfterHeader) ? retryAfterHeader[0] ?? null : retryAfterHeader ?? null
-        });
+        }));
       });
     });
     req.on("timeout", () => {
-      req.destroy(markRailwayTransientError(new Error(`Railway API request timed out after ${timeoutMs}ms.`)));
+      const error = markRailwayTransientError(new Error(`Railway API request timed out after ${timeoutMs}ms.`));
+      if (!settled) {
+        req?.destroy(error);
+      }
     });
-    req.on("error", reject);
+    req.on("error", (error) => finish(() => reject(error)));
     req.write(rawBody);
     req.end();
   });
@@ -637,25 +712,130 @@ query TreeseedRailwayProjectEnvironments($projectId: String!) {
   });
   return normalizeConnectionNodes(payload.data?.project ? payload.data.project.environments : null, normalizeEnvironment);
 }
+async function listRailwayEnvironmentServices({
+  environmentId,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  const payload = await railwayGraphqlRequest({
+    query: `
+query TreeseedRailwayEnvironmentServices($environmentId: String!) {
+	environment(id: $environmentId) {
+		id
+		name
+		serviceInstances(first: 100) {
+			edges {
+				node {
+					id
+					serviceId
+					serviceName
+					environmentId
+				}
+			}
+		}
+	}
+}
+`.trim(),
+    variables: { environmentId },
+    env,
+    fetchImpl
+  });
+  return normalizeConnectionNodes(
+    payload.data?.environment ? payload.data.environment.serviceInstances : null,
+    normalizeServiceInstanceService
+  );
+}
 async function ensureRailwayService({
   projectId,
   serviceName,
   serviceId,
+  environmentId,
+  imageRef,
+  sourceRepo,
+  sourceBranch,
   env = process.env,
   fetchImpl = fetch
 }) {
   const services = await listRailwayServices({ projectId, env, fetchImpl });
   const desiredServiceName = railwayConnectionLabel(serviceName);
   const desiredServiceId = railwayConnectionLabel(serviceId);
-  const existing = services.find(
+  let existing = services.find(
     (service2) => desiredServiceId && service2.id === desiredServiceId || desiredServiceName && service2.name === desiredServiceName
   ) ?? null;
+  if (!existing && environmentId) {
+    const environmentServices = await listRailwayEnvironmentServices({ environmentId, env, fetchImpl }).catch(() => []);
+    existing = environmentServices.find(
+      (service2) => desiredServiceId && service2.id === desiredServiceId || desiredServiceName && service2.name === desiredServiceName
+    ) ?? null;
+  }
   if (existing) {
+    const desiredImageRef = railwayConnectionLabel(imageRef);
+    const desiredSourceRepo = railwayConnectionLabel(sourceRepo);
+    if (desiredSourceRepo) {
+      try {
+        await updateRailwayServiceGitSource({
+          serviceId: existing.id,
+          sourceRepo: desiredSourceRepo,
+          sourceBranch,
+          env,
+          fetchImpl
+        });
+      } catch (error) {
+        if (!looksLikeRailwayImageSourceUpdateUnsupported(error)) {
+          throw error;
+        }
+        throw new Error(
+          `Railway Git source update for existing service ${existing.name} (${existing.id}) is unsupported; refusing to delete and recreate an existing service. Repair the service in place or use a provider-supported source update.`
+        );
+      }
+      return { service: existing, created: false };
+    }
+    if (desiredImageRef) {
+      try {
+        await updateRailwayServiceImageSource({
+          serviceId: existing.id,
+          imageRef: desiredImageRef,
+          env,
+          fetchImpl
+        });
+      } catch (error) {
+        if (!looksLikeRailwayImageSourceUpdateUnsupported(error)) {
+          throw error;
+        }
+        throw new Error(
+          `Railway image source update for existing service ${existing.name} (${existing.id}) is unsupported; refusing to delete and recreate an existing service. Repair the service in place or use a provider-supported image source update.`
+        );
+      }
+    }
     return { service: existing, created: false };
   }
   if (!desiredServiceName) {
     throw new Error("Railway service creation requires a service name.");
   }
+  const service = await createRailwayImageService({
+    projectId,
+    environmentId,
+    serviceName: desiredServiceName,
+    imageRef,
+    sourceRepo,
+    sourceBranch,
+    env,
+    fetchImpl
+  });
+  return { service, created: true };
+}
+async function createRailwayImageService({
+  projectId,
+  serviceName,
+  environmentId,
+  imageRef,
+  sourceRepo,
+  sourceBranch,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  const desiredSourceRepo = railwayConnectionLabel(sourceRepo);
+  const desiredImageRef = railwayConnectionLabel(imageRef);
   const created = await railwayGraphqlRequest({
     query: `
 mutation TreeseedRailwayServiceCreate($input: ServiceCreateInput!) {
@@ -668,7 +848,18 @@ mutation TreeseedRailwayServiceCreate($input: ServiceCreateInput!) {
     variables: {
       input: {
         projectId,
-        name: desiredServiceName
+        name: serviceName,
+        ...railwayConnectionLabel(environmentId) ? { environmentId: railwayConnectionLabel(environmentId) } : {},
+        ...desiredSourceRepo ? {
+          source: {
+            repo: desiredSourceRepo
+          },
+          ...railwayConnectionLabel(sourceBranch) ? { branch: railwayConnectionLabel(sourceBranch) } : {}
+        } : desiredImageRef ? {
+          source: {
+            image: desiredImageRef
+          }
+        } : {}
       }
     },
     env,
@@ -676,9 +867,219 @@ mutation TreeseedRailwayServiceCreate($input: ServiceCreateInput!) {
   });
   const service = created.data?.serviceCreate ? normalizeService(created.data.serviceCreate) : null;
   if (!service) {
-    throw new Error(`Railway service create did not return a usable service for ${desiredServiceName}.`);
+    throw new Error(`Railway service create did not return a usable service for ${serviceName}.`);
   }
-  return { service, created: true };
+  return service;
+}
+function looksLikeRailwayImageSourceUpdateUnsupported(error) {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /Problem processing request|source|image|ServiceUpdateInput/iu.test(message);
+}
+async function updateRailwayServiceImageSource({
+  serviceId,
+  imageRef,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  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 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;
+}
+async function updateRailwayServiceGitSource({
+  serviceId,
+  sourceRepo,
+  sourceBranch,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  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;
+}
+async function ensureRailwayGeneratedServiceDomain({
+  projectId,
+  environmentId,
+  serviceId,
+  targetPort,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  const domains = await listRailwayServiceDomains({ projectId, environmentId, serviceId, env, fetchImpl });
+  const existing = domains.find((domain2) => domain2.kind === "service") ?? domains.find((domain2) => domain2.domain.endsWith(".railway.app")) ?? null;
+  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({
+      environmentId,
+      serviceId,
+      ...Number.isFinite(Number(targetPort)) ? { targetPort: Number(targetPort) } : {}
+    });
+  }
+  const domain = normalizeRailwayDomain(payload.data?.serviceDomainCreate);
+  if (!domain) {
+    throw new Error("Railway service domain create did not return a usable domain.");
+  }
+  return { domain, created: true };
+}
+async function listRailwayServiceDomains({
+  projectId,
+  environmentId,
+  serviceId,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  const payload = await railwayGraphqlRequest({
+    query: `
+query TreeseedRailwayServiceDomains($projectId: String!, $environmentId: String!, $serviceId: String!) {
+	domains(projectId: $projectId, environmentId: $environmentId, serviceId: $serviceId) {
+		serviceDomains {
+			id
+			domain
+			serviceId
+			environmentId
+			targetPort
+		}
+		customDomains {
+			id
+			domain
+			serviceId
+			environmentId
+			targetPort
+		}
+	}
+}
+`.trim(),
+    variables: { projectId, environmentId, serviceId },
+    env,
+    fetchImpl
+  });
+  const domains = payload.data?.domains && typeof payload.data.domains === "object" ? payload.data.domains : {};
+  return [
+    ...normalizeRailwayDomainList(domains.serviceDomains, "service"),
+    ...normalizeRailwayDomainList(domains.customDomains, "custom")
+  ];
+}
+async function deployRailwayServiceInstance({
+  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
+  });
+  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 };
 }
 async function updateRailwayServiceName({
   serviceId,
@@ -717,43 +1118,221 @@ async function ensureRailwayPostgresService({
   environmentId,
   serviceName,
   env = process.env,
-  fetchImpl = fetch
+  fetchImpl = fetch,
+  maxAttempts = 40
 }) {
   const desiredServiceName = railwayConnectionLabel(serviceName);
   if (!desiredServiceName) {
     throw new Error("Railway Postgres service creation requires a service name.");
   }
   const services = await listRailwayServices({ projectId, env, fetchImpl });
-  const existing = services.find((service2) => service2.name === desiredServiceName || service2.id === desiredServiceName) ?? null;
+  const existing = services.find((service) => service.name === desiredServiceName || service.id === desiredServiceName) ?? null;
   if (existing) {
-    return { service: existing, created: false };
-  }
-  const created = await railwayGraphqlRequest({
+    const proof = await inspectRailwayPostgresService({ projectId, environmentId, serviceId: existing.id, env, fetchImpl });
+    if (proof.ok) {
+      return { service: existing, created: false, proof };
+    }
+    throw new Error(
+      `Railway Postgres service ${existing.name} (${existing.id}) failed proof; refusing to delete and recreate an existing service. Repair the existing database service in place and rerun reconciliation.`
+    );
+  }
+  const template = await getRailwayTemplateByCode({ code: "postgres", env, fetchImpl });
+  await deployRailwayTemplate({
+    templateId: template.id,
+    serializedConfig: template.serializedConfig,
+    projectId,
+    environmentId,
+    env,
+    fetchImpl
+  });
+  const settled = await waitForRailwayPostgresTemplateService({
+    projectId,
+    environmentId,
+    desiredServiceName,
+    env,
+    fetchImpl,
+    maxAttempts
+  });
+  return { service: settled.service, created: true, proof: settled.proof };
+}
+async function getRailwayTemplateByCode({
+  code,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  const payload = await railwayGraphqlRequest({
     query: `
-mutation TreeseedRailwayPostgresServiceCreate($input: ServiceCreateInput!) {
-	serviceCreate(input: $input) {
+query TreeseedRailwayTemplate($code: String!) {
+	template(code: $code) {
 		id
+		code
 		name
+		serializedConfig
+	}
+}
+`.trim(),
+    variables: { code },
+    env,
+    fetchImpl,
+    timeoutMs: 15e3,
+    retries: 1
+  });
+  const template = payload.data?.template;
+  const id = railwayConnectionLabel(template?.id);
+  if (!id || !template || typeof template !== "object") {
+    throw new Error(`Railway Postgres template "${code}" was not found through the Railway API.`);
+  }
+  return {
+    id,
+    code: railwayConnectionLabel(template.code) || null,
+    name: railwayConnectionLabel(template.name) || null,
+    serializedConfig: normalizeTemplateSerializedConfig(template.serializedConfig)
+  };
+}
+function normalizeTemplateSerializedConfig(value) {
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+async function deployRailwayTemplate({
+  templateId,
+  serializedConfig,
+  projectId,
+  environmentId,
+  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,
-        name: desiredServiceName,
-        templateId: RAILWAY_POSTGRES_TEMPLATE_ID,
-        templateServiceId: RAILWAY_POSTGRES_TEMPLATE_SERVICE_ID
+        workspaceId: workspace.id
       }
     },
     env,
-    fetchImpl
+    fetchImpl,
+    timeoutMs: 2e4,
+    retries: 1
   });
-  const service = created.data?.serviceCreate ? normalizeService(created.data.serviceCreate) : null;
-  if (!service) {
-    throw new Error(`Railway Postgres service create did not return a usable service for ${desiredServiceName}.`);
+  if (!payload.data?.templateDeployV2?.projectId) {
+    throw new Error("Railway Postgres template deployment did not return a project id.");
   }
-  return { service, created: true };
+  return payload.data.templateDeployV2;
+}
+async function waitForRailwayPostgresTemplateService({
+  projectId,
+  environmentId,
+  desiredServiceName,
+  env = process.env,
+  fetchImpl = fetch,
+  maxAttempts = 40
+}) {
+  let lastProof = null;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const services = await listRailwayServices({ projectId, env, fetchImpl });
+    for (const service of services) {
+      const proof = await inspectRailwayPostgresService({
+        projectId,
+        environmentId,
+        serviceId: service.id,
+        env,
+        fetchImpl
+      });
+      if (proof.ok) {
+        const renamed = service.name === desiredServiceName ? service : await updateRailwayServiceName({ serviceId: service.id, name: desiredServiceName, env, fetchImpl });
+        return { service: renamed, proof };
+      }
+      lastProof = proof;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 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"}`);
+}
+async function inspectRailwayPostgresService({
+  projectId,
+  environmentId,
+  serviceId,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  const variables = await listRailwayVariables({ projectId, environmentId, serviceId, env, fetchImpl }).catch(() => ({}));
+  const hasConnectionVars = typeof variables.DATABASE_URL === "string" && typeof variables.PGHOST === "string" && typeof variables.PGUSER === "string" && typeof variables.PGPASSWORD === "string" && typeof variables.PGDATABASE === "string";
+  const volumes = await listRailwayVolumes({ projectId, env, fetchImpl }).catch(() => []);
+  const volume = volumes.find((candidate) => candidate.instances.some(
+    (instance) => instance.serviceId === serviceId && instance.environmentId === environmentId && instance.mountPath === "/var/lib/postgresql/data"
+  )) ?? null;
+  const deployment = await inspectRailwayServiceDeploymentHealth({ serviceId, environmentId, env, fetchImpl }).catch((error) => ({
+    ok: false,
+    status: null,
+    message: error instanceof Error ? error.message : String(error ?? "Unable to inspect PostgreSQL deployment health.")
+  }));
+  return {
+    ok: hasConnectionVars && Boolean(volume) && deployment.ok,
+    variableKeys: Object.keys(variables).sort(),
+    volumeId: volume?.id ?? null,
+    deploymentStatus: deployment.status,
+    message: hasConnectionVars ? volume ? deployment.ok ? "Railway managed PostgreSQL markers are present and the deployment is healthy." : `Railway managed PostgreSQL markers are present, but deployment health is not ready. ${deployment.message}` : "PostgreSQL connection variables exist, but the managed data volume is missing." : "PostgreSQL connection variables are missing."
+  };
+}
+async function inspectRailwayServiceDeploymentHealth({
+  serviceId,
+  environmentId,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  const payload = await railwayGraphqlRequest({
+    query: `
+query TreeseedRailwayServiceDeploymentHealth($serviceId: String!, $environmentId: String!) {
+	serviceInstance(serviceId: $serviceId, environmentId: $environmentId) {
+		latestDeployment {
+			status
+			deploymentStopped
+			meta
+			instances {
+				status
+			}
+		}
+	}
+}
+`.trim(),
+    variables: { serviceId, environmentId },
+    env,
+    fetchImpl
+  });
+  const deployment = payload.data?.serviceInstance?.latestDeployment;
+  const status = railwayConnectionLabel(deployment?.status)?.toUpperCase() ?? null;
+  const instanceStatuses = Array.isArray(deployment?.instances) ? deployment.instances.map((instance) => railwayConnectionLabel(instance?.status)?.toUpperCase()).filter(Boolean) : [];
+  const stopped = deployment?.deploymentStopped === true;
+  const ok = status === "SUCCESS" && !stopped && (instanceStatuses.length === 0 || instanceStatuses.some((candidate) => candidate === "RUNNING"));
+  return {
+    ok,
+    status,
+    branch: railwayConnectionLabel(deployment?.meta?.branch) || null,
+    repo: railwayConnectionLabel(deployment?.meta?.repo) || null,
+    rootDirectory: railwayConnectionLabel(deployment?.meta?.rootDirectory) || null,
+    commitHash: railwayConnectionLabel(deployment?.meta?.commitHash) || 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(",")}` : ""}.`
+  };
 }
 async function listRailwayServices({
   projectId,
@@ -791,6 +1370,8 @@ async function getRailwayServiceInstance({
   const legacySummary = {
     id: null,
     buildCommand: null,
+    dockerfilePath: null,
+    railwayConfigFile: null,
     startCommand: null,
     cronSchedule: null,
     rootDirectory: null,
@@ -809,6 +1390,8 @@ query TreeseedRailwayServiceInstance($serviceId: String!, $environmentId: String
 	serviceInstance(serviceId: $serviceId, environmentId: $environmentId) {
 		id
 		buildCommand
+		dockerfilePath
+		railwayConfigFile
 		startCommand
 		cronSchedule
 		rootDirectory
@@ -826,6 +1409,8 @@ query TreeseedRailwayServiceInstance($serviceId: String!, $environmentId: String
     return {
       id: railwayConnectionLabel(instance?.id) || null,
       buildCommand: railwayConnectionLabel(instance?.buildCommand) || null,
+      dockerfilePath: railwayConnectionLabel(instance?.dockerfilePath) || null,
+      railwayConfigFile: railwayConnectionLabel(instance?.railwayConfigFile) || null,
       startCommand: railwayConnectionLabel(instance?.startCommand) || null,
       cronSchedule: railwayConnectionLabel(instance?.cronSchedule) || null,
       rootDirectory: railwayConnectionLabel(instance?.rootDirectory) || null,
@@ -846,6 +1431,8 @@ query TreeseedRailwayServiceInstanceLegacy($serviceId: String!, $environmentId:
 	serviceInstance(serviceId: $serviceId, environmentId: $environmentId) {
 		id
 		buildCommand
+		dockerfilePath
+		railwayConfigFile
 		startCommand
 		cronSchedule
 		rootDirectory
@@ -861,6 +1448,8 @@ query TreeseedRailwayServiceInstanceLegacy($serviceId: String!, $environmentId:
         ...legacySummary,
         id: railwayConnectionLabel(instance?.id) || null,
         buildCommand: railwayConnectionLabel(instance?.buildCommand) || null,
+        dockerfilePath: railwayConnectionLabel(instance?.dockerfilePath) || null,
+        railwayConfigFile: railwayConnectionLabel(instance?.railwayConfigFile) || null,
         startCommand: railwayConnectionLabel(instance?.startCommand) || null,
         cronSchedule: railwayConnectionLabel(instance?.cronSchedule) || null,
         rootDirectory: railwayConnectionLabel(instance?.rootDirectory) || null
@@ -876,6 +1465,8 @@ async function ensureRailwayServiceInstanceConfiguration({
   serviceId,
   environmentId,
   buildCommand,
+  dockerfilePath,
+  railwayConfigFile,
   startCommand,
   cronSchedule,
   rootDirectory,
@@ -884,6 +1475,7 @@ async function ensureRailwayServiceInstanceConfiguration({
   healthcheckIntervalSeconds,
   restartPolicy,
   runtimeMode,
+  deploymentRegion,
   env = process.env,
   fetchImpl = fetch,
   settleAttempts = 60,
@@ -899,8 +1491,12 @@ async function ensureRailwayServiceInstanceConfiguration({
   if (!current.id) {
     return { instance: current, updated: false };
   }
+  const desiredRuntimeMode = railwayConnectionLabel(runtimeMode) === "service" ? "replicated" : railwayConnectionLabel(runtimeMode) || null;
+  const desiredDeploymentRegion = railwayConnectionLabel(deploymentRegion) || null;
   const desired = {
     buildCommand: railwayConnectionLabel(buildCommand) || null,
+    dockerfilePath: railwayConnectionLabel(dockerfilePath) || null,
+    railwayConfigFile: railwayConnectionLabel(railwayConfigFile) || null,
     startCommand: railwayConnectionLabel(startCommand) || null,
     cronSchedule: railwayConnectionLabel(cronSchedule) || null,
     rootDirectory: railwayConnectionLabel(rootDirectory) || null,
@@ -908,10 +1504,11 @@ async function ensureRailwayServiceInstanceConfiguration({
     healthcheckTimeoutSeconds: normalizeRailwayNumber(healthcheckTimeoutSeconds),
     healthcheckIntervalSeconds: normalizeRailwayNumber(healthcheckIntervalSeconds),
     restartPolicy: railwayConnectionLabel(restartPolicy) || null,
-    runtimeMode: railwayConnectionLabel(runtimeMode) || null,
-    sleepApplication: railwayConnectionLabel(runtimeMode) === "serverless" ? true : railwayConnectionLabel(runtimeMode) === "replicated" ? false : null
+    runtimeMode: desiredRuntimeMode,
+    deploymentRegion: desiredDeploymentRegion,
+    sleepApplication: desiredRuntimeMode === "serverless" ? true : desiredRuntimeMode === "replicated" ? false : null
   };
-  const needsRuntimeConfig = desired.healthcheckPath !== null || desired.healthcheckTimeoutSeconds !== null || desired.runtimeMode !== null;
+  const needsRuntimeConfig = desired.healthcheckPath !== null || desired.healthcheckTimeoutSeconds !== null || desired.runtimeMode !== null || desired.deploymentRegion !== null;
   if (needsRuntimeConfig && current.runtimeConfigSupported !== true) {
     throw new Error("Railway service instance runtime settings are unsupported by the current Railway API schema.");
   }
@@ -921,7 +1518,7 @@ async function ensureRailwayServiceInstanceConfiguration({
   if (desired.restartPolicy !== null) {
     throw new Error("Railway service instance restart policies are unsupported by the current Railway API schema.");
   }
-  const drifted = desired.buildCommand !== null && desired.buildCommand !== current.buildCommand || desired.startCommand !== null && desired.startCommand !== current.startCommand || desired.cronSchedule !== null && desired.cronSchedule !== current.cronSchedule || desired.rootDirectory !== null && desired.rootDirectory !== current.rootDirectory || desired.healthcheckPath !== null && desired.healthcheckPath !== current.healthcheckPath || desired.healthcheckTimeoutSeconds !== null && desired.healthcheckTimeoutSeconds !== current.healthcheckTimeoutSeconds || desired.runtimeMode !== null && desired.runtimeMode !== current.runtimeMode;
+  const drifted = desired.buildCommand !== null && desired.buildCommand !== current.buildCommand || desired.dockerfilePath !== null && desired.dockerfilePath !== current.dockerfilePath || desired.railwayConfigFile !== null && desired.railwayConfigFile !== current.railwayConfigFile || desired.startCommand !== null && desired.startCommand !== current.startCommand || desired.cronSchedule !== null && desired.cronSchedule !== current.cronSchedule || desired.rootDirectory !== null && desired.rootDirectory !== current.rootDirectory || desired.healthcheckPath !== null && desired.healthcheckPath !== current.healthcheckPath || desired.healthcheckTimeoutSeconds !== null && desired.healthcheckTimeoutSeconds !== current.healthcheckTimeoutSeconds || desired.runtimeMode !== null && desired.runtimeMode !== current.runtimeMode || desired.deploymentRegion !== null;
   if (!drifted) {
     return { instance: current, updated: false };
   }
@@ -942,12 +1539,19 @@ mutation TreeseedRailwayServiceInstanceUpdateLegacy($serviceId: String!, $enviro
         environmentId,
         input: {
           ...desired.buildCommand !== null ? { buildCommand: desired.buildCommand } : {},
+          ...desired.dockerfilePath !== null ? { dockerfilePath: desired.dockerfilePath } : {},
+          ...desired.railwayConfigFile !== null ? { railwayConfigFile: desired.railwayConfigFile } : {},
           ...desired.startCommand !== null ? { startCommand: desired.startCommand } : {},
           ...desired.cronSchedule !== null ? { cronSchedule: desired.cronSchedule } : {},
           ...desired.rootDirectory !== null ? { rootDirectory: desired.rootDirectory } : {},
           ...desired.healthcheckPath !== null ? { healthcheckPath: desired.healthcheckPath } : {},
           ...desired.healthcheckTimeoutSeconds !== null ? { healthcheckTimeout: desired.healthcheckTimeoutSeconds } : {},
-          ...desired.sleepApplication !== null ? { sleepApplication: desired.sleepApplication } : {}
+          ...desired.sleepApplication !== null ? { sleepApplication: desired.sleepApplication } : {},
+          ...desired.deploymentRegion !== null ? {
+            multiRegionConfig: {
+              [desired.deploymentRegion]: { numReplicas: 1 }
+            }
+          } : {}
         }
       },
       env,
@@ -1041,6 +1645,21 @@ mutation TreeseedRailwayVariableCollectionUpsert($input: VariableCollectionUpser
     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,
@@ -1054,23 +1673,29 @@ mutation TreeseedRailwayVariableCollectionUpsert($input: VariableCollectionUpser
       throw error;
     }
     for (const [key, value] of Object.entries(variables)) {
-      await railwayGraphqlRequest({
-        query,
-        variables: {
-          input: {
-            projectId,
-            environmentId,
-            serviceId: serviceId || null,
-            variables: { [key]: value },
-            replace: false,
-            skipDeploys: true
-          }
-        },
-        env,
-        fetchImpl
-      });
+      await upsertOne(key, value);
+    }
+  }
+  const observed = await listRailwayVariables({ projectId, environmentId, serviceId, env, fetchImpl }).catch(() => ({}));
+  const missing = Object.keys(variables).filter((key) => observed[key] == null);
+  for (const key of missing) {
+    await upsertOne(key, variables[key]);
+  }
+  let retried = missing.length > 0 ? await listRailwayVariables({ projectId, environmentId, serviceId, env, fetchImpl }).catch(() => ({})) : observed;
+  let stillMissing = Object.keys(variables).filter((key) => retried[key] == null);
+  for (let attempt = 0; stillMissing.length > 0 && attempt < 12; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+    retried = await listRailwayVariables({ projectId, environmentId, serviceId, env, fetchImpl }).catch(() => ({}));
+    stillMissing = Object.keys(variables).filter((key) => retried[key] == null);
+    if (stillMissing.length > 0 && attempt === 5) {
+      for (const key of stillMissing) {
+        await upsertOne(key, variables[key]);
+      }
     }
   }
+  if (stillMissing.length > 0) {
+    throw new Error(`Railway variable upsert did not persist: ${stillMissing.join(", ")}.`);
+  }
 }
 async function listRailwayVolumes({
   projectId,
@@ -1095,6 +1720,8 @@ query TreeseedRailwayVolumeList($projectId: String!) {
 								environmentId
 								mountPath
 								state
+								isPendingDeletion
+								deletedAt
 							}
 						}
 					}
@@ -1129,15 +1756,17 @@ mutation TreeseedRailwayVolumeCreate($input: VolumeCreateInput!) {
 		projectId
 		volumeInstances {
 			edges {
-				node {
-					id
-					serviceId
-					environmentId
-					mountPath
-								state
+					node {
+						id
+						serviceId
+						environmentId
+						mountPath
+						state
+						isPendingDeletion
+						deletedAt
+					}
 				}
 			}
-		}
 	}
 }
 `.trim();
@@ -1193,15 +1822,17 @@ mutation TreeseedRailwayVolumeUpdate($volumeId: String!, $input: VolumeUpdateInp
 		projectId
 		volumeInstances {
 			edges {
-				node {
-					id
-					serviceId
-					environmentId
-					mountPath
-								state
+					node {
+						id
+						serviceId
+						environmentId
+						mountPath
+						state
+						isPendingDeletion
+						deletedAt
+					}
 				}
 			}
-		}
 	}
 }
 `.trim();
@@ -1233,7 +1864,7 @@ mutation TreeseedRailwayVolumeInstanceUpdate($volumeId: String!, $input: VolumeI
     variables: {
       volumeId,
       input: {
-        ...serviceId ? { serviceId } : {},
+        ...serviceId !== void 0 ? { serviceId } : {},
         mountPath
       }
     },
@@ -1248,7 +1879,9 @@ async function ensureRailwayServiceVolume({
   name,
   mountPath,
   env = process.env,
-  fetchImpl = fetch
+  fetchImpl = fetch,
+  settleAttempts = 24,
+  settleDelayMs = 5e3
 }) {
   if (!mountPath.startsWith("/")) {
     throw new Error(`Railway volume mount path must be absolute: ${mountPath}`);
@@ -1258,8 +1891,25 @@ async function ensureRailwayServiceVolume({
     ...candidate,
     instances: candidate.instances.filter(isActiveRailwayVolumeInstance)
   })).filter((candidate) => candidate.instances.length > 0);
-  let volume = findRailwayVolumeForService(volumes, serviceId, environmentId) ?? activeVolumes.find(
+  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;
@@ -1282,7 +1932,13 @@ async function ensureRailwayServiceVolume({
       for (let attempt = 0; attempt < 8; attempt += 1) {
         await new Promise((resolve) => setTimeout(resolve, 1500));
         const refreshed = await listRailwayVolumes({ projectId, env, fetchImpl });
-        const existing = findRailwayVolumeForService(refreshed, serviceId, environmentId);
+        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;
         }
@@ -1295,7 +1951,9 @@ async function ensureRailwayServiceVolume({
   if (!volume) {
     volume = await createReplacementVolume();
   }
-  const desiredNameInUse = volumes.some((candidate) => candidate.id !== volume?.id && candidate.name === name);
+  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 };
@@ -1313,10 +1971,33 @@ async function ensureRailwayServiceVolume({
       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 (!looksLikeRailwayMissingResource(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();
       }
-      volume = await createReplacementVolume();
     }
     instance = volume.instances.find((entry) => entry.serviceId === serviceId && entry.environmentId === environmentId) ?? null;
     updated = true;
@@ -1337,18 +2018,77 @@ async function ensureRailwayServiceVolume({
     }
     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;
+    }
+    instance = mountedInstance(refreshedVolume);
+    if (instance) {
+      return { volume: refreshedVolume, instance };
+    }
+  }
+  return null;
+}
 function findRailwayVolumeForService(volumes, serviceId, environmentId) {
   return volumes.find(
     (candidate) => candidate.instances.some(
-      (instance) => instance.serviceId === serviceId && instance.environmentId === environmentId && isActiveRailwayVolumeInstance(instance)
+      (instance) => instance.serviceId === serviceId && (!environmentId || instance.environmentId === environmentId) && isActiveRailwayVolumeInstance(instance)
     )
   ) ?? 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 /would have \d+ volumes attached|can only have one volume|not authorized/iu.test(message);
+  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,
@@ -1463,6 +2203,10 @@ function looksLikeRailwayMissingResource(error) {
   const message = error instanceof Error ? error.message : String(error ?? "");
   return /not found|does not exist|could not find|unknown|invalid .*id/iu.test(message);
 }
+function looksLikeRailwayOperationInProgress(error) {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /operation is already in progress/iu.test(message);
+}
 async function railwayDeleteMutation({
   query,
   variables,
@@ -1470,20 +2214,32 @@ async function railwayDeleteMutation({
   fetchImpl,
   missingResult
 }) {
-  try {
-    await railwayGraphqlRequest({
-      query,
-      variables,
-      env,
-      fetchImpl
-    });
-    return { status: "deleted" };
-  } catch (error) {
-    if (looksLikeRailwayMissingResource(error)) {
-      return missingResult;
+  let lastError = null;
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    try {
+      const payload = await railwayGraphqlRequest({
+        query,
+        variables,
+        env,
+        fetchImpl
+      });
+      const mutationResult = Object.values(payload.data ?? {})[0];
+      if (mutationResult === false || mutationResult == null) {
+        throw new Error("Railway delete mutation returned no successful deletion result.");
+      }
+      return { status: "deleted" };
+    } catch (error) {
+      if (looksLikeRailwayMissingResource(error)) {
+        return missingResult;
+      }
+      if (!looksLikeRailwayOperationInProgress(error) || attempt >= 5) {
+        throw error;
+      }
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 2500 * (attempt + 1)));
     }
-    throw error;
   }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "Railway delete mutation did not complete."));
 }
 async function deleteRailwayCustomDomain({
   domainId,
@@ -1506,6 +2262,27 @@ mutation TreeseedRailwayCustomDomainDelete($id: String!) {
     missingResult: { status: "missing", id: domainId }
   });
 }
+async function deleteRailwayService({
+  serviceId,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  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 }
+  });
+}
 async function deleteRailwayVolume({
   volumeId,
   env = process.env,
@@ -1514,18 +2291,55 @@ async function deleteRailwayVolume({
   if (!railwayConnectionLabel(volumeId)) {
     return { status: "missing", id: volumeId };
   }
-  const mutation = configuredEnvValue(env, "TREESEED_RAILWAY_VOLUME_DELETE_MUTATION") || `
+  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();
-  return railwayDeleteMutation({
-    query: mutation,
+  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" };
+}
+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({
   environmentId,
@@ -1573,9 +2387,12 @@ export {
   deleteRailwayCustomDomain,
   deleteRailwayEnvironment,
   deleteRailwayProject,
+  deleteRailwayService,
   deleteRailwayVolume,
+  deployRailwayServiceInstance,
   ensureRailwayCustomDomain,
   ensureRailwayEnvironment,
+  ensureRailwayGeneratedServiceDomain,
   ensureRailwayPostgresService,
   ensureRailwayProject,
   ensureRailwayService,
@@ -1584,10 +2401,13 @@ export {
   getRailwayAuthProfile,
   getRailwayProject,
   getRailwayServiceInstance,
+  inspectRailwayServiceDeploymentHealth,
   isUsableRailwayToken,
   listRailwayCustomDomains,
+  listRailwayEnvironmentServices,
   listRailwayEnvironments,
   listRailwayProjects,
+  listRailwayServiceDomains,
   listRailwayServices,
   listRailwayVariables,
   listRailwayVolumes,
@@ -1597,6 +2417,8 @@ export {
   resolveRailwayApiUrl,
   resolveRailwayWorkspace,
   resolveRailwayWorkspaceContext,
+  updateRailwayServiceGitSource,
+  updateRailwayServiceImageSource,
   updateRailwayServiceName,
   upsertRailwayVariables
 };