@treeseed/sdk 0.10.27 → 0.11.0

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

@@ -1,8 +1,6 @@
 import { request as httpsRequest } from "node:https";
 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) {
@@ -195,6 +193,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) {
@@ -641,6 +664,8 @@ async function ensureRailwayService({
   projectId,
   serviceName,
   serviceId,
+  environmentId,
+  imageRef,
   env = process.env,
   fetchImpl = fetch
 }) {
@@ -651,11 +676,55 @@ async function ensureRailwayService({
     (service2) => desiredServiceId && service2.id === desiredServiceId || desiredServiceName && service2.name === desiredServiceName
   ) ?? null;
   if (existing) {
+    const desiredImageRef = railwayConnectionLabel(imageRef);
+    if (desiredImageRef) {
+      try {
+        await updateRailwayServiceImageSource({
+          serviceId: existing.id,
+          imageRef: desiredImageRef,
+          env,
+          fetchImpl
+        });
+      } catch (error) {
+        if (!looksLikeRailwayImageSourceUpdateUnsupported(error)) {
+          throw error;
+        }
+        await deleteRailwayService({ serviceId: existing.id, env, fetchImpl });
+        await waitForRailwayServiceMissing({ projectId, serviceId: existing.id, env, fetchImpl });
+        const replacement = await createRailwayImageService({
+          projectId,
+          environmentId,
+          serviceName: desiredServiceName || existing.name,
+          imageRef: desiredImageRef,
+          env,
+          fetchImpl
+        });
+        return { service: replacement, created: true, replaced: true };
+      }
+    }
     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,
+    env,
+    fetchImpl
+  });
+  return { service, created: true };
+}
+async function createRailwayImageService({
+  projectId,
+  serviceName,
+  environmentId,
+  imageRef,
+  env = process.env,
+  fetchImpl = fetch
+}) {
   const created = await railwayGraphqlRequest({
     query: `
 mutation TreeseedRailwayServiceCreate($input: ServiceCreateInput!) {
@@ -668,7 +737,13 @@ mutation TreeseedRailwayServiceCreate($input: ServiceCreateInput!) {
     variables: {
       input: {
         projectId,
-        name: desiredServiceName
+        name: serviceName,
+        ...railwayConnectionLabel(environmentId) ? { environmentId: railwayConnectionLabel(environmentId) } : {},
+        ...railwayConnectionLabel(imageRef) ? {
+          source: {
+            image: railwayConnectionLabel(imageRef)
+          }
+        } : {}
       }
     },
     env,
@@ -676,9 +751,189 @@ 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;
+}
+async function waitForRailwayServiceMissing({
+  projectId,
+  serviceId,
+  env = process.env,
+  fetchImpl = fetch,
+  attempts = 20,
+  delayMs = 1500
+}) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const services = await listRailwayServices({ projectId, env, fetchImpl }).catch(() => []);
+    if (!services.some((service) => service.id === serviceId)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  throw new Error(`Railway service ${serviceId} was not deleted before image source replacement.`);
+}
+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: ServiceUpdateInput!) {
+	serviceUpdate(id: $id, input: $input) {
+		id
+		name
+	}
+}
+`.trim(),
+    variables: {
+      id: serviceId,
+      input: {
+        source: {
+          image: desiredImage
+        }
+      }
+    },
+    env,
+    fetchImpl
+  });
+  const service = payload.data?.serviceUpdate ? normalizeService(payload.data.serviceUpdate) : null;
+  if (!service) {
+    throw new Error(`Railway service image 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 +972,212 @@ 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 proof = await inspectRailwayPostgresService({ projectId, environmentId, serviceId: existing.id, env, fetchImpl });
+    if (proof.ok) {
+      return { service: existing, created: false, proof };
+    }
+    await deleteRailwayService({ serviceId: existing.id, env, fetchImpl });
   }
-  const created = await railwayGraphqlRequest({
+  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
+			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,
+    message: ok ? "Deployment is healthy." : `Latest deployment status is ${status ?? "unknown"}${stopped ? " and stopped" : ""}${instanceStatuses.length ? `; instances=${instanceStatuses.join(",")}` : ""}.`
+  };
 }
 async function listRailwayServices({
   projectId,
@@ -884,6 +1308,7 @@ async function ensureRailwayServiceInstanceConfiguration({
   healthcheckIntervalSeconds,
   restartPolicy,
   runtimeMode,
+  deploymentRegion,
   env = process.env,
   fetchImpl = fetch,
   settleAttempts = 60,
@@ -899,6 +1324,8 @@ 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,
     startCommand: railwayConnectionLabel(startCommand) || null,
@@ -908,10 +1335,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 +1349,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.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 };
   }
@@ -947,7 +1375,12 @@ mutation TreeseedRailwayServiceInstanceUpdateLegacy($serviceId: String!, $enviro
           ...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,
@@ -1248,7 +1681,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,7 +1693,22 @@ 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)
   ) ?? null;
   let created = false;
@@ -1282,7 +1732,7 @@ 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 existing = findRailwayVolumeForService(refreshed, serviceId, environmentId) ?? findRailwayVolumeForService(refreshed, serviceId) ?? findSoleActiveRailwayVolumeForEnvironment(refreshed, environmentId);
         if (existing) {
           return existing;
         }
@@ -1313,10 +1763,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 +1810,68 @@ 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 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,
@@ -1471,12 +1994,16 @@ async function railwayDeleteMutation({
   missingResult
 }) {
   try {
-    await railwayGraphqlRequest({
+    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)) {
@@ -1506,6 +2033,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 +2062,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 +2158,12 @@ export {
   deleteRailwayCustomDomain,
   deleteRailwayEnvironment,
   deleteRailwayProject,
+  deleteRailwayService,
   deleteRailwayVolume,
+  deployRailwayServiceInstance,
   ensureRailwayCustomDomain,
   ensureRailwayEnvironment,
+  ensureRailwayGeneratedServiceDomain,
   ensureRailwayPostgresService,
   ensureRailwayProject,
   ensureRailwayService,
@@ -1584,10 +2172,12 @@ export {
   getRailwayAuthProfile,
   getRailwayProject,
   getRailwayServiceInstance,
+  inspectRailwayServiceDeploymentHealth,
   isUsableRailwayToken,
   listRailwayCustomDomains,
   listRailwayEnvironments,
   listRailwayProjects,
+  listRailwayServiceDomains,
   listRailwayServices,
   listRailwayVariables,
   listRailwayVolumes,
@@ -1597,6 +2187,7 @@ export {
   resolveRailwayApiUrl,
   resolveRailwayWorkspace,
   resolveRailwayWorkspaceContext,
+  updateRailwayServiceImageSource,
   updateRailwayServiceName,
   upsertRailwayVariables
 };