@teamscala/service-boot 0.23.304 → 0.23.305

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.304",
+  "version": "0.23.305",
   "sideEffects": false,
   "files": [
     "src"

package/src/resolve-service-port.d.ts

@@ -16,11 +16,17 @@
  * The rule, and why it is not "env always wins":
  *
  * Railway injects PORT and healthchecks that exact port, reporting the service
- * unavailable if it listens elsewhere — so where there is NO routing row (a
- * Railway-only backend), the env is the only truth and must win.
+ * unavailable if it listens elsewhere. So on Railway the injected PORT is
+ * authoritative period — a `service_install`/`service_routing` row carries the
+ * service's LOCAL dev port (e.g. portal 5200), and on Railway binding that
+ * instead of PORT means Railway probes a port nothing listens on and the deploy
+ * fails healthcheck. The registry-wins rule below exists to stop LOCAL port
+ * collisions (one host, many services); inside a Railway container there are no
+ * sibling services to collide with, so PORT must win. `isRailway` is the caller's
+ * assertion that it is booting inside Railway (from `RAILWAY_ENVIRONMENT`).
  *
- * But a `service_routing` row means this service has a DECLARED port on this
- * host. There, a PORT that disagrees is a polluted launcher environment, never
+ * Off Railway, a `service_routing`/`service_install` row means this service has
+ * a DECLARED port on this host. There, a PORT that disagrees is a polluted launcher environment, never
  * an intention, and obeying it binds someone else's port. That is not a
  * hypothetical: mcp-ai-chat-system booted onto 3021 — session-picker's port —
  * while its own MCP_SERVER_URL still pointed at 8080. Both processes bound 3021,
@@ -60,7 +66,10 @@ export interface PortResolution {
  * @param envPort   parsed PORT env, or undefined when unset/unparseable
  * @param declaredPort `service_routing.local_port`, or undefined when the
  *                     service has no routing row (the Railway-only case)
+ * @param isRailway  true when booting inside Railway (caller derives from
+ *                   `RAILWAY_ENVIRONMENT`); there the injected PORT is authoritative
+ *                   regardless of the row, because Railway healthchecks it
  */
-export declare function resolveServicePort(envPort: number | undefined, declaredPort: number | undefined): PortResolution | {
+export declare function resolveServicePort(envPort: number | undefined, declaredPort: number | undefined, isRailway?: boolean): PortResolution | {
     error: "no-port-source";
 };

package/src/resolve-service-port.test.ts

@@ -95,4 +95,31 @@ describe("resolveServicePort", () => {
 			});
 		});
 	});
+
+	describe("Railway: injected PORT is authoritative over the row's dev port", () => {
+		// The 2026-07-31 portal incident: portal declares its dev port 5200 in
+		// service_install, Railway injects PORT=8080 and healthchecks 8080. The
+		// registry-wins rule (correct on the shared dev host) made portal bind 5200
+		// on Railway, so Railway's healthcheck probed a dead port and the deploy
+		// failed — despite the service booting healthy. On Railway PORT must win.
+		test("a conflicting declared port does NOT override Railway's injected PORT", () => {
+			expect(resolveServicePort(8080, 5200, true)).toEqual({ port: 8080, source: "env" });
+		});
+
+		test("an agreeing declared port still resolves to env on Railway", () => {
+			expect(resolveServicePort(8080, 8080, true)).toEqual({ port: 8080, source: "env" });
+		});
+
+		test("Railway with no injected PORT falls back to the declared port", () => {
+			expect(resolveServicePort(undefined, 5200, true)).toEqual({ port: 5200, source: "service_routing" });
+		});
+
+		test("isRailway defaults to false: off Railway the registry still wins a conflict", () => {
+			expect(resolveServicePort(8080, 5200)).toEqual({
+				port: 5200,
+				source: "service_routing",
+				conflict: { envPort: 8080, declaredPort: 5200 },
+			});
+		});
+	});
 });

package/src/resolve-service-port.ts

@@ -16,11 +16,17 @@
  * The rule, and why it is not "env always wins":
  *
  * Railway injects PORT and healthchecks that exact port, reporting the service
- * unavailable if it listens elsewhere — so where there is NO routing row (a
- * Railway-only backend), the env is the only truth and must win.
+ * unavailable if it listens elsewhere. So on Railway the injected PORT is
+ * authoritative period — a `service_install`/`service_routing` row carries the
+ * service's LOCAL dev port (e.g. portal 5200), and on Railway binding that
+ * instead of PORT means Railway probes a port nothing listens on and the deploy
+ * fails healthcheck. The registry-wins rule below exists to stop LOCAL port
+ * collisions (one host, many services); inside a Railway container there are no
+ * sibling services to collide with, so PORT must win. `isRailway` is the caller's
+ * assertion that it is booting inside Railway (from `RAILWAY_ENVIRONMENT`).
  *
- * But a `service_routing` row means this service has a DECLARED port on this
- * host. There, a PORT that disagrees is a polluted launcher environment, never
+ * Off Railway, a `service_routing`/`service_install` row means this service has
+ * a DECLARED port on this host. There, a PORT that disagrees is a polluted launcher environment, never
  * an intention, and obeying it binds someone else's port. That is not a
  * hypothetical: mcp-ai-chat-system booted onto 3021 — session-picker's port —
  * while its own MCP_SERVER_URL still pointed at 8080. Both processes bound 3021,
@@ -63,14 +69,26 @@ function isBindablePort(value: number | undefined): value is number {
  * @param envPort   parsed PORT env, or undefined when unset/unparseable
  * @param declaredPort `service_routing.local_port`, or undefined when the
  *                     service has no routing row (the Railway-only case)
+ * @param isRailway  true when booting inside Railway (caller derives from
+ *                   `RAILWAY_ENVIRONMENT`); there the injected PORT is authoritative
+ *                   regardless of the row, because Railway healthchecks it
  */
 export function resolveServicePort(
 	envPort: number | undefined,
 	declaredPort: number | undefined,
+	isRailway = false,
 ): PortResolution | { error: "no-port-source" } {
 	const envUsable = isBindablePort(envPort);
 	const declaredUsable = isBindablePort(declaredPort);
 
+	// On Railway the injected PORT is authoritative: Railway healthchecks that
+	// exact port, and the declared port is the service's LOCAL dev port — binding
+	// it makes the healthcheck probe a port nothing listens on. There are no
+	// sibling services to collide with inside a container, so PORT wins.
+	if (isRailway && envUsable) {
+		return { port: envPort, source: "env" };
+	}
+
 	// No routing row: Railway's injected PORT is the only truth available.
 	if (!declaredUsable) {
 		return envUsable ? { port: envPort, source: "env" } : { error: "no-port-source" };

package/src/ui-service.ts

@@ -74,9 +74,13 @@ export async function bootUiService(
 	//
 	// This branch previously took `process.env.PORT` unconditionally, which is
 	// how scala-quiz (declared 5203) booted onto session-picker's 3021 from a
-	// leaked env and silently split that daemon's traffic (2026-07-31). Railway
-	// is unaffected by construction: it injects PORT and a Railway-only service
-	// has no declared port, so the env still wins there.
+	// leaked env and silently split that daemon's traffic (2026-07-31). On the
+	// dev host the registry wins a conflict (below). On Railway the injected PORT
+	// wins instead — Railway healthchecks exactly that port, and the row's port
+	// is the service's LOCAL dev port (e.g. portal 5200), so binding it on Railway
+	// makes the healthcheck probe a dead port and the deploy fails (`isRailway`
+	// path in the resolver).
+	const isRailway = Boolean(process.env.RAILWAY_ENVIRONMENT);
 	const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
 	// The APP binds its PRIVATE port (app_port) when present — for scale-to-zero
 	// services `port` is the ACTIVATOR's ingress (what callers resolve), not the
@@ -85,7 +89,7 @@ export async function bootUiService(
 	// bind the activator's port → SO_REUSEPORT silent load-balancing (the
 	// service-ports-from-registry trap: clean boot, two owners in ss -ltnp).
 	const declaredAppPort = config.app_port ?? config.port;
-	const resolution = resolveServicePort(envPort, declaredAppPort);
+	const resolution = resolveServicePort(envPort, declaredAppPort, isRailway);
 	if ("error" in resolution) {
 		throw new BootFatalError(
 			"ui-service.port-resolution",