@fabrika/provider-zerops 0.0.25 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.0.25",
+	"version": "0.2.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -32,9 +32,9 @@
 		"gen:schema": "bun scripts/generate-zerops-types.ts"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.0.25",
-		"@fabrika/auth-core": "^0.0.25",
-		"@fabrika/provider-contract": "^0.0.25",
-		"@fabrika/proxy-contract": "^0.0.25"
+		"@fabrika/auth": "^0.2.0",
+		"@fabrika/auth-core": "^0.2.0",
+		"@fabrika/provider-contract": "^0.2.0",
+		"@fabrika/proxy-contract": "^0.2.0"
 	}
 }

package/src/api.ts

@@ -258,7 +258,7 @@ export interface ZeropsServiceEnv {
 
 /**
  * A short-lived grant for the project's LOG service. VERIFIED: `ResponseProjectLog` — the field names and
- * types are exactly these. What is NOT verified is what the URLs speak; see `readBuildLog`.
+ * types are exactly these. What the URLs speak was measured separately; see `readBuildLog`.
  */
 export interface ZeropsLogAccess {
 	url: string
@@ -271,10 +271,14 @@ export interface ZeropsLogAccess {
 	expiration: string
 }
 
+/** The RFC3339 stamp the plaintext log window puts first on every line. Anchored so a bare year cannot pass. */
+const LOG_LINE_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+
 /** One relayed build/runtime log line. Shape is fabrika's, not the platform's. */
 export interface ZeropsLogLine {
-	/** ISO timestamp when Zerops recorded the line, when it supplied one. */
+	/** RFC3339 stamp Zerops put at the head of the line, when the line carried one. */
 	timestamp?: string
+	/** The line as the log service wrote it, timestamp and tag included. */
 	message: string
 }
 
@@ -457,8 +461,9 @@ export interface ZeropsApi {
 	 * Every environment variable of ONE service, each with the record id `deleteServiceEnv` takes.
 	 * VERIFIED: `GET /service-stack/{id}/env` (`{ items }`).
 	 *
-	 * NOT `GET /service-stack/{id}/user-data`, which answers `400 serviceStackNotFound` on every
-	 * service, deployed or not — see `docs/reference/zerops-platform.md`. The `/env` reading omits
+	 * NOT `GET /service-stack/{id}/user-data`: it answers a list now (2026-08-21), but `/env` is the
+	 * endpoint whose record ids `PUT`/`DELETE /user-data/{id}` take, and the list's paging terms were
+	 * never verified — see `docs/reference/zerops-platform.md`. The `/env` reading omits
 	 * variables the service's own `zerops.yaml` declares (`type: ENV`); fabrika never writes those.
 	 * The OpenAPI publishes no lookup/pagination terms and live probes found query terms ignored, so the
 	 * implementation reads one full response under a byte bound rather than imposing an entry-count cap.
@@ -548,17 +553,42 @@ export interface ZeropsApi {
 	getLogAccess(input: { projectId: string; signal: AbortSignal }): Promise<ZeropsLogAccess>
 
 	/**
-	 * UNVERIFIED — THE ONE SHAPE NOBODY COULD CHECK. `GET /project/{id}/log` hands back URLs to a
-	 * SEPARATE log service, and that service's request/response contract appears in no published document
-	 * (it is not in the OpenAPI file, which stops at the grant). The default implementation's reading is:
-	 * GET `urlPlain` with the grant as a bearer, one plain-text line per log record, `limit`/`from` as
-	 * query params. Treat that as a guess.
+	 * One window of the project's log, narrowed to ONE app version.
+	 *
+	 * VERIFIED 2026-08-21 by measurement, not by document: the OpenAPI file stops at the grant, so the
+	 * separate log service was read against a live project. `urlPlain` answers one
+	 * `<RFC3339 timestamp> <tag> <message>` line per record and accepts `serviceStackId`, `limit`, `tags`
+	 * and `desc`; `from` and unknown terms are accepted and silently ignored, so nothing may depend on them.
+	 *
+	 * ORDERING, also measured: `limit=N` without `desc` returns the NEWEST N records in ASCENDING timestamp
+	 * order (`limit=3` against a log starting 15:50 answered 17:00:00, 17:00:00, 17:15:00), and `desc=1`
+	 * returns the same newest N, newest first. So `desc` is needed neither for the `since` cut nor for a
+	 * build longer than the limit: each poll re-reads the newest window and the caller's dedupe streams it.
 	 *
-	 * BECAUSE it is a guess, the driver treats a failure here as non-fatal: log relay degrades to "no
-	 * lines" and the deploy still succeeds or fails on `/app-version` status alone. An unverified endpoint
-	 * must never be able to fail a deploy.
+	 * A version's BUILD lines carry the tag `zbuilder@<appVersionId>` and are produced on a separate
+	 * builder stack, so they are selected by `tags` ALONE — combining that tag with the runtime
+	 * `serviceStackId` matches nothing. RUNTIME lines carry no version marker at all and the runtime
+	 * service's window mixes every version that ever ran, so they are selected by `serviceStackId` and cut
+	 * at `since` (the version's `build.pipelineStart`). Without `since` no runtime line is read: a line
+	 * from an earlier version is worse in a run log than a missing one. The cut is by TIME, not identity —
+	 * the outgoing container keeps logging until it is replaced, so its lines stamped after `since` still
+	 * pass, and only the earlier version's older history is excluded.
+	 *
+	 * The two windows are read INDEPENDENTLY: one failing must not discard what the other returned, and only
+	 * a failure of every window attempted is raised. The driver then treats that as non-fatal anyway — log
+	 * relay degrades to "no lines" and the deploy succeeds or fails on `/app-version` status alone. A log
+	 * service must never be able to fail a deploy.
 	 */
-	readBuildLog(input: { access: ZeropsLogAccess; serviceId: string; limit?: number; signal: AbortSignal }): Promise<ZeropsLogLine[]>
+	readBuildLog(input: {
+		access: ZeropsLogAccess
+		serviceId: string
+		/** Select this version's build lines by their `zbuilder@` tag; without it no build line is read. */
+		appVersionId?: string
+		/** RFC3339 lower bound for runtime lines, normally `build.pipelineStart`; without it none are read. */
+		since?: string
+		limit?: number
+		signal: AbortSignal
+	}): Promise<ZeropsLogLine[]>
 }
 
 // ── default (real) implementation ───────────────────────────────────────────────
@@ -1245,20 +1275,47 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 			}
 		},
 
-		readBuildLog: async ({ access, serviceId, limit, signal }) => {
-			// UNVERIFIED (see the interface): this is a best reading of an undocumented log service, not a
-			// contract. It is written so a wrong guess degrades to "no lines" instead of failing a deploy.
+		readBuildLog: async ({ access, serviceId, appVersionId, since, limit, signal }) => {
 			if (access.urlPlain === '') {
 				return []
 			}
 			const separator = access.urlPlain.includes('?') ? '&' : '?'
-			const url = `${access.urlPlain}${separator}serviceStackId=${encodeURIComponent(serviceId)}&limit=${limit ?? 200}`
-			const response = await doFetch(url, { headers: { authorization: `Bearer ${access.accessToken}` }, signal })
-			if (!response.ok) {
-				throw new Error(`zerops: read build log failed (${response.status})`)
+			const readWindow = async (terms: string): Promise<{ lines: ZeropsLogLine[]; error: unknown }> => {
+				try {
+					const url = `${access.urlPlain}${separator}${terms}&limit=${limit ?? 200}`
+					const response = await doFetch(url, { headers: { authorization: `Bearer ${access.accessToken}` }, signal })
+					if (!response.ok) {
+						throw new Error(`zerops: read build log failed (${response.status})`)
+					}
+					const text = await response.text()
+					const lines = text.split('\n').filter((line) => line.trim() !== '').map((line) => {
+						const head = line.slice(0, Math.max(line.indexOf(' '), 0))
+						return LOG_LINE_TIMESTAMP.test(head) ? { timestamp: head, message: line } : { message: line }
+					})
+					return { lines, error: undefined }
+				} catch (error) {
+					return { lines: [], error }
+				}
+			}
+			// Selected by tag alone: the build runs on a builder stack, so pairing the tag with the runtime
+			// service id matches nothing (see the interface).
+			const build = appVersionId === undefined ? undefined : await readWindow(`tags=${encodeURIComponent(`zbuilder@${appVersionId}`)}`)
+			const runtime = since === undefined ? undefined : await readWindow(`serviceStackId=${encodeURIComponent(serviceId)}`)
+			const attempted = [build, runtime].filter((result) => result !== undefined)
+			if (attempted.length === 0) {
+				return []
+			}
+			// Independent windows: only a failure of every one attempted is worth raising.
+			const failure = attempted.find((result) => result.error !== undefined)
+			if (failure !== undefined && attempted.every((result) => result.error !== undefined)) {
+				throw failure.error
 			}
-			const text = await response.text()
-			return text.split('\n').filter((line) => line.trim() !== '').map((line) => ({ message: line }))
+			const boundary = since === undefined ? Number.NaN : Date.parse(since)
+			// The runtime window carries every version that ever ran, so a line the driver cannot date is dropped.
+			const runtimeLines = runtime === undefined || Number.isNaN(boundary)
+				? runtime?.lines ?? []
+				: runtime.lines.filter((line) => line.timestamp !== undefined && Date.parse(line.timestamp) >= boundary)
+			return [...build?.lines ?? [], ...runtimeLines]
 		},
 	}
 }

package/src/compile.ts

@@ -18,6 +18,7 @@
 // credentials leak to app B. "Never write to project-level env" alone does not prevent that; the isolation
 // setting is the other half.
 
+import type { JsonValue } from '@fabrika/provider-contract'
 import type { ZeropsImportProject, ZeropsImportService } from './schema.generated'
 import type { ZeropsProjectSpec, ZeropsResourceContext, ZeropsServiceSpec, ZeropsSourceTarget } from './types'
 
@@ -37,6 +38,16 @@ export interface ZeropsImportDocument {
 	services: ZeropsImportService[]
 }
 
+/**
+ * The same document once it has been through JSON — a manifest's stored `importDocument`, or one whose
+ * values were substituted. Structurally identical, leaves typed as JSON, so `assertZeropsInvariants`
+ * checks it too rather than trusting whoever produced it.
+ */
+export interface ZeropsJsonImportDocument {
+	readonly project?: { readonly [key: string]: JsonValue }
+	readonly services: ReadonlyArray<{ readonly [key: string]: JsonValue }>
+}
+
 /** What the compiler needs beyond the app's declaration. */
 export interface CompileInput {
 	target: ZeropsSourceTarget
@@ -185,14 +196,14 @@ const compileProject = (spec: ZeropsProjectSpec): ZeropsImportProject => {
  *
  * Deliberately checks the emitted document rather than the input: it is the document that reaches Zerops.
  */
-export const assertZeropsInvariants = (document: ZeropsImportDocument): void => {
+export const assertZeropsInvariants = (document: ZeropsImportDocument | ZeropsJsonImportDocument): void => {
 	const project = document.project
 	if (project !== undefined) {
-		if (project.envVariables !== undefined) {
+		if (project['envVariables'] !== undefined) {
 			throw new Error('zerops: refusing to write PROJECT-level env variables — they reach every service in the project (ADR-0004)')
 		}
-		if (project.envIsolation !== ENV_ISOLATION) {
-			throw new Error(`zerops: project envIsolation must be \`${ENV_ISOLATION}\`, got \`${String(project.envIsolation)}\` (ADR-0004)`)
+		if (project['envIsolation'] !== ENV_ISOLATION) {
+			throw new Error(`zerops: project envIsolation must be \`${ENV_ISOLATION}\`, got \`${String(project['envIsolation'])}\` (ADR-0004)`)
 		}
 	}
 	if (document.services.length === 0) {
@@ -200,23 +211,24 @@ export const assertZeropsInvariants = (document: ZeropsImportDocument): void =>
 	}
 	const seen = new Set<string>()
 	for (const service of document.services) {
-		if (service.envIsolation !== ENV_ISOLATION) {
+		const hostname = String(service['hostname'])
+		if (service['envIsolation'] !== ENV_ISOLATION) {
 			throw new Error(
-				`zerops: service \`${service.hostname}\` envIsolation must be \`${ENV_ISOLATION}\`, got \`${String(service.envIsolation)}\` (ADR-0004)`,
+				`zerops: service \`${hostname}\` envIsolation must be \`${ENV_ISOLATION}\`, got \`${String(service['envIsolation'])}\` (ADR-0004)`,
 			)
 		}
 		// Every service class, managed included. A document missing it anywhere cannot be re-applied at
 		// all: the platform answers `400 serviceStackNameUnavailable` on the first hostname that exists
 		// and rejects the whole import, so one omission breaks every later apply, not just that service.
-		if (service.override !== OVERRIDE) {
+		if (service['override'] !== OVERRIDE) {
 			throw new Error(
-				`zerops: service \`${service.hostname}\` must carry \`override: true\`; without it a re-apply is rejected as a name collision`,
+				`zerops: service \`${hostname}\` must carry \`override: true\`; without it a re-apply is rejected as a name collision`,
 			)
 		}
-		if (service.envSecrets !== undefined || service.dotEnvSecrets !== undefined) {
+		if (service['envSecrets'] !== undefined || service['dotEnvSecrets'] !== undefined) {
 			// Never assert on the VALUE — only that the field is present.
 			throw new Error(
-				`zerops: service \`${service.hostname}\` carries secrets in the import document; secrets are written through the env API (ADR-0004)`,
+				`zerops: service \`${hostname}\` carries secrets in the import document; secrets are written through the env API (ADR-0004)`,
 			)
 		}
 		// `zeropsSetup` is part of the import's pipeline configuration, and the platform rejects the WHOLE
@@ -230,15 +242,15 @@ export const assertZeropsInvariants = (document: ZeropsImportDocument): void =>
 		// Nothing is lost by dropping the setup name here: it is only redundant restatement of Zerops' own
 		// "setup name defaults to the hostname" rule, and a deploy that needs to say otherwise passes
 		// `zeropsSetup` at TRIGGER time, where no repository is required.
-		if (service.zeropsSetup !== undefined && service.buildFromGit === undefined) {
+		if (service['zeropsSetup'] !== undefined && service['buildFromGit'] === undefined) {
 			throw new Error(
-				`zerops: service \`${service.hostname}\` names \`zeropsSetup\` without \`buildFromGit\`; the platform rejects the import (pass the setup when triggering the pipeline instead)`,
+				`zerops: service \`${hostname}\` names \`zeropsSetup\` without \`buildFromGit\`; the platform rejects the import (pass the setup when triggering the pipeline instead)`,
 			)
 		}
-		if (seen.has(service.hostname)) {
-			throw new Error(`zerops: duplicate service hostname \`${service.hostname}\` in the import document`)
+		if (seen.has(hostname)) {
+			throw new Error(`zerops: duplicate service hostname \`${hostname}\` in the import document`)
 		}
-		seen.add(service.hostname)
+		seen.add(hostname)
 	}
 }
 
@@ -257,13 +269,55 @@ export const compileImport = (input: CompileInput): ZeropsImportDocument => {
 /** Keys/scalars that are safe unquoted in YAML. Everything else gets a double-quoted, JSON-escaped form. */
 const PLAIN = /^[A-Za-z_][A-Za-z0-9_./@+-]*$/
 
+/**
+ * Code points a YAML 1.1 reader (go-yaml, which parses this on Zerops) ends a line on or refuses outright,
+ * while Bun's 1.2 reader takes them for ordinary text — so no test using Bun can see the difference. `\n`
+ * and `\r` are excluded: the block form owns one and `blockScalarSafe` refuses the other.
+ */
+const isYamlHostileCodePoint = (code: number): boolean =>
+	(code < 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d)
+	|| (code >= 0x7f && code <= 0x9f)
+	|| code === 0x2028
+	|| code === 0x2029
+	|| code === 0xfeff
+	|| (code >= 0xd800 && code <= 0xdfff)
+
+/** `JSON.stringify` leaves DEL, the C1 block, U+2028/9 and U+FEFF raw; YAML's own `\uXXXX` carries them. */
+const escapeYamlHostile = (quoted: string): string =>
+	[...quoted].map((character) => {
+		const code = character.codePointAt(0) ?? 0
+		return isYamlHostileCodePoint(code) ? `\\u${code.toString(16).padStart(4, '0')}` : character
+	}).join('')
+
 const scalar = (value: string): string => {
 	// Reserved plain scalars that YAML would read as booleans/null, plus anything with structure.
 	const reserved = new Set(['true', 'false', 'null', 'yes', 'no', 'on', 'off', '~'])
 	if (value !== '' && PLAIN.test(value) && !reserved.has(value.toLowerCase())) {
 		return value
 	}
-	return JSON.stringify(value)
+	return escapeYamlHostile(JSON.stringify(value))
+}
+
+/**
+ * A `|-` block reproduces the string only when the text owns its own lines. An indented or blank first
+ * line moves (or breaks) the block's own indentation, `\r` and a blank line do not survive it, and `-`
+ * eats a trailing newline. A code point a YAML 1.1 reader breaks a line on cannot go in at all — the block
+ * is the one form with no escapes. Everything else goes out double-quoted, which is exact YAML.
+ */
+const blockScalarSafe = (value: string): boolean => {
+	if (!value.includes('\n') || value.includes('\r')) {
+		return false
+	}
+	if ([...value].some((character) => isYamlHostileCodePoint(character.codePointAt(0) ?? 0))) {
+		return false
+	}
+	const lines = value.split('\n')
+	const first = lines[0] ?? ''
+	if (first === '' || first.startsWith(' ') || first.startsWith('\t')) {
+		return false
+	}
+	// A blank line loses its whitespace, and an empty last line is the trailing newline `-` strips.
+	return !lines.some((line, index) => line.trim() === '' && (line !== '' || index === lines.length - 1))
 }
 
 const isArray = (value: unknown): value is unknown[] => Array.isArray(value)
@@ -316,9 +370,8 @@ const emit = (value: unknown, indent: number): string[] => {
 		return lines
 	}
 	if (typeof value === 'string') {
-		if (value.includes('\n')) {
-			const body = value.replace(/\n$/, '').split('\n').map((line) => `${pad}  ${line}`)
-			return [`${pad}|-`, ...body]
+		if (blockScalarSafe(value)) {
+			return [`${pad}|-`, ...value.split('\n').map((line) => `${pad}  ${line}`)]
 		}
 		return [`${pad}${scalar(value)}`]
 	}

package/src/control.ts

@@ -17,6 +17,7 @@ import type {
 	RuntimeProviderRun,
 	SchemaReconciler,
 } from '@fabrika/provider-contract'
+import { ProviderSecretError } from '@fabrika/provider-contract'
 import {
 	createZeropsApi,
 	ZEROPS_ACTIVE,
@@ -40,6 +41,7 @@ import {
 } from './manifest'
 import { createZeropsNamespaceCapabilities, type ZeropsNamespaceTarget, zeropsNamespaceTargetCodec } from './namespace'
 import { createZeropsProvider, type ZeropsSourceTransportBinding } from './provider'
+import { allowedReferenceHosts, foreignReferenceHost, serviceReferenceHosts } from './service-references'
 import { normalizeZeropsSourceRepository, type ZeropsSourceClient, type ZeropsSourceClientV2, type ZeropsSourceResolveResult } from './source'
 import type { ZeropsRunState, ZeropsRuntimeTarget } from './types'
 
@@ -316,6 +318,20 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 			{ appId: environment.appId, env: environment.env },
 		)
 
+	/**
+	 * A variable written through the env API resolves `${host_KEY}` at container start like `run.envVariables`
+	 * does, across services whatever `envIsolation` says — so an unchecked secret reads the proxy's key.
+	 */
+	const assertOwnReferencesOnly = (environment: ProviderEnvironment, name: string, value: string): void => {
+		// A secret naming no service at all must not start failing on an artifact that no longer parses.
+		if (serviceReferenceHosts(name).length === 0 && serviceReferenceHosts(value).length === 0) return
+		const allowed = allowedReferenceHosts(manifestServiceHostnames(artifactFor(environment)))
+		const foreign = foreignReferenceHost(name, allowed) ?? foreignReferenceHost(value, allowed)
+		if (foreign !== null) {
+			throw new ProviderSecretError(`zerops: secret \`${name}\` references service \`${foreign}\`, which this app does not own`, 'foreignReference')
+		}
+	}
+
 	const cancelSourceBestEffort = async (runId: string, appVersionId: string): Promise<void> => {
 		const sourceController = new AbortController()
 		const timeoutController = new AbortController()
@@ -678,6 +694,7 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 		},
 		secrets: {
 			put: async (input) => {
+				assertOwnReferencesOnly(input.environment, input.name, input.value)
 				const target = decodeEnvironment(input.environment).target
 				await api.putServiceEnv({
 					serviceId: target.serviceId,

package/src/index.ts

@@ -49,7 +49,7 @@ export {
 	renderImportYaml,
 	renderYaml,
 } from './compile'
-export type { CompileInput, ZeropsImportDocument } from './compile'
+export type { CompileInput, ZeropsImportDocument, ZeropsJsonImportDocument } from './compile'
 export { createZeropsControlProvider, zeropsStoredTargetCodec } from './control'
 export type { ZeropsBeforeDeploy, ZeropsBeforeDeployInput, ZeropsControlProviderOptions, ZeropsProviderExecutor, ZeropsStoredTarget } from './control'
 export {

package/src/manifest.ts

@@ -1,6 +1,7 @@
 import type { AppActionDef, AppGates, AppSchema, AppScopeDef, GateRule, RoleDef } from '@fabrika/auth-core'
 import type { JsonValue, ProviderCodec } from '@fabrika/provider-contract'
 import { compileImport, ENV_ISOLATION, OVERRIDE, renderYaml } from './compile'
+import { allowedReferenceHosts, foreignReferenceHost } from './service-references'
 import type { ZeropsAppConfig, ZeropsNamespaceResourceRequirement, ZeropsProxySpec, ZeropsSharedPostgresBinding } from './types'
 
 export const FABRIKA_MANIFEST_VERSION = 3
@@ -225,6 +226,36 @@ function parseProxy(value: unknown): ZeropsProxySpec | null {
 	return upstream === undefined || gates === null ? null : { upstream, gates }
 }
 
+/** The first foreign host referenced by any string leaf OR key of `value`, however deeply nested. */
+const foreignReferenceInValue = (value: unknown, allowed: ReadonlySet<string>): string | null => {
+	if (typeof value === 'string') {
+		return foreignReferenceHost(value, allowed)
+	}
+	if (Array.isArray(value)) {
+		for (const entry of value) {
+			const host = foreignReferenceInValue(entry, allowed)
+			if (host !== null) return host
+		}
+		return null
+	}
+	if (typeof value === 'object' && value !== null) {
+		for (const key of Object.keys(value)) {
+			const host = foreignReferenceHost(key, allowed) ?? foreignReferenceInValue(prop(value, key), allowed)
+			if (host !== null) return host
+		}
+	}
+	return null
+}
+
+/** Read the descriptor as the platform does. Text scanning misses what YAML folds, escapes or hides in a block scalar. */
+const parseDescriptorDocument = (contents: string): unknown => {
+	try {
+		return Bun.YAML.parse(contents)
+	} catch {
+		throw new Error('invalid fabrika manifest: zerops.yaml is not parseable YAML')
+	}
+}
+
 const parseImportDocument = (value: unknown): FabrikaImportDocument => {
 	if (value === undefined) {
 		throw new Error('invalid fabrika manifest Zerops import document')
@@ -238,7 +269,7 @@ const parseImportDocument = (value: unknown): FabrikaImportDocument => {
 	if (!Array.isArray(rawServices) || rawServices.length === 0) {
 		throw new Error('invalid fabrika manifest Zerops import services')
 	}
-	const services: Array<{ readonly [key: string]: JsonValue }> = []
+	const parsed: Array<[string, { readonly [key: string]: JsonValue }]> = []
 	const hostnames = new Set<string>()
 	for (const [index, rawService] of rawServices.entries()) {
 		const service = jsonObject(rawService, `Zerops import service ${index}`)
@@ -261,8 +292,19 @@ const parseImportDocument = (value: unknown): FabrikaImportDocument => {
 			throw new Error('invalid fabrika manifest: Zerops import contains a forbidden environment field')
 		}
 		hostnames.add(hostname)
-		services.push(service)
+		parsed.push([hostname, service])
+	}
+	// A `${host_KEY}` reference crosses `envIsolation: service` by design, so the declared hostnames are the
+	// boundary. They are never rewritten at deploy: a shared namespace's app prefix is authored INTO the
+	// hostname (`service-names.ts`), which `registrationResourceClaims` then enforces.
+	const allowed = allowedReferenceHosts([...hostnames])
+	for (const [hostname, service] of parsed) {
+		const foreign = foreignReferenceInValue(service, allowed)
+		if (foreign !== null) {
+			throw new Error(`invalid fabrika manifest: Zerops service \`${hostname}\` references service \`${foreign}\`, which this app does not own`)
+		}
 	}
+	const services = parsed.map(([, service]) => service)
 	const rawProject = raw['project']
 	let project: { readonly [key: string]: JsonValue } | undefined
 	if (rawProject !== undefined) {
@@ -386,6 +428,10 @@ export function parseFabrikaManifest(value: unknown, expected: ManifestExpectati
 	if (!serviceHostnames.includes(deployService)) {
 		throw new Error('invalid fabrika manifest Zerops deploy service')
 	}
+	const foreignInDescriptor = foreignReferenceInValue(parseDescriptorDocument(sourceDescriptor.contents), allowedReferenceHosts(serviceHostnames))
+	if (foreignInDescriptor !== null) {
+		throw new Error(`invalid fabrika manifest: zerops.yaml references service \`${foreignInDescriptor}\`, which this app does not own`)
+	}
 	const zeropsSetup = optionalString(rawTarget, 'zeropsSetup')
 	if (prop(rawTarget, 'zeropsSetup') !== undefined && zeropsSetup === null) {
 		throw new Error('invalid fabrika manifest zeropsSetup')

package/src/namespace.ts

@@ -6,6 +6,7 @@ import {
 	type ProviderNamespaceCapabilities,
 	ProviderNamespaceError,
 	type ProviderNamespaceFact,
+	type ProviderNamespaceHost,
 	type ProviderNamespaceMutationInput,
 	type ProviderNamespaceOperator,
 	type ProviderNamespacePlanInput,
@@ -13,7 +14,7 @@ import {
 	type ProviderNamespacePreset,
 	type ProviderRegistration,
 } from '@fabrika/provider-contract'
-import { encodeProxyManifestJson, FABRIKA_PROXY_MANIFEST_JSON } from '@fabrika/proxy-contract'
+import { encodeProxyManifestJson, FABRIKA_PROXY_MANIFEST_JSON, isProxyHost } from '@fabrika/proxy-contract'
 import {
 	ZEROPS_ACTIVE,
 	ZEROPS_SERVICE_NOT_HTTP,
@@ -35,6 +36,8 @@ export const ZEROPS_NAMESPACE_PROXY_HOSTNAME = 'proxy'
 export const ZEROPS_NAMESPACE_POSTGRES_HOSTNAME = 'postgres'
 export const ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE = 'FABRIKA_IAM_ISSUER'
 export const ZEROPS_NAMESPACE_IAM_KEY_VARIABLE = 'FABRIKA_IAM_KEY'
+/** The platform-owned variable naming one URL per published HTTP port. READ_ONLY, written by Zerops. */
+export const ZEROPS_NAMESPACE_SUBDOMAIN_VARIABLE = 'zeropsSubdomain'
 /**
  * How an app reaches the namespace-owned PostgreSQL service — port, database and TLS mode NAMED, not
  * defaulted. Every part settled against a live account, none of it safe to infer:
@@ -91,6 +94,8 @@ export interface ZeropsNamespaceTarget {
 	readonly proxyConfigured?: boolean
 	readonly proxyBaselineSequence?: number
 	readonly proxyAppVersionId?: string
+	/** The hosts the published proxy answers on, recorded once so a namespace read needs no platform call. */
+	readonly proxyHosts?: readonly ProviderNamespaceHost[]
 	readonly ready?: boolean
 }
 
@@ -221,6 +226,54 @@ const parsePostgres = (payload: JsonValue): ZeropsNamespacePostgres | undefined
 	return profile === undefined ? { type } : { type, profile }
 }
 
+const parseProxyHosts = (payload: JsonValue): readonly ProviderNamespaceHost[] | undefined => {
+	const value = property(payload, 'proxyHosts')
+	if (value === undefined) return undefined
+	if (!Array.isArray(value)) {
+		throw new Error('Zerops namespace target proxyHosts must be an array')
+	}
+	return value.map((entry) => {
+		if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+			throw new Error('Zerops namespace target proxyHosts entry must be an object')
+		}
+		const host = property(entry, 'host')
+		const port = property(entry, 'port')
+		if (typeof host !== 'string' || host === '') {
+			throw new Error('Zerops namespace target proxyHosts host must be a non-empty string')
+		}
+		if (typeof port !== 'number' || !Number.isInteger(port) || port <= 0) {
+			throw new Error('Zerops namespace target proxyHosts port must be a positive integer')
+		}
+		return { host, port }
+	})
+}
+
+/**
+ * One host per published HTTP port, out of the newline-separated URLs the platform writes.
+ *
+ * The form is `<hostname>-<hash>-<port>.<region>.zerops.app` (e.g. `proxy-2ec8-8080`). Read as URLs
+ * rather than split on `-`, so a hostname whose own first label ends in digits cannot be misread; a line
+ * that is not a URL, or whose first label carries no trailing port — the single portless line a proxy
+ * that has never deployed publishes — is skipped rather than guessed at.
+ */
+const parseZeropsProxyHosts = (value: string): ProviderNamespaceHost[] => {
+	const hosts: ProviderNamespaceHost[] = []
+	for (const line of value.split('\n')) {
+		const trimmed = line.trim()
+		if (trimmed === '') continue
+		let hostname: string
+		try {
+			hostname = new URL(trimmed).hostname
+		} catch {
+			continue
+		}
+		const port = /-(\d+)$/.exec(hostname.split('.')[0] ?? '')?.[1]
+		if (port === undefined) continue
+		hosts.push({ host: hostname, port: Number.parseInt(port, 10) })
+	}
+	return hosts.sort((left, right) => left.port - right.port)
+}
+
 export const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget> = {
 	version: 1,
 	encode: (target) => ({
@@ -238,6 +291,7 @@ export const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget> =
 		...(target.proxyConfigured !== undefined ? { proxyConfigured: target.proxyConfigured } : {}),
 		...(target.proxyBaselineSequence !== undefined ? { proxyBaselineSequence: target.proxyBaselineSequence } : {}),
 		...(target.proxyAppVersionId !== undefined ? { proxyAppVersionId: target.proxyAppVersionId } : {}),
+		...(target.proxyHosts === undefined ? {} : { proxyHosts: target.proxyHosts.map((entry) => ({ host: entry.host, port: entry.port })) }),
 		...(target.ready !== undefined ? { ready: target.ready } : {}),
 	}),
 	decode: (payload) => {
@@ -272,6 +326,7 @@ export const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget> =
 			...(optionalString(payload, 'proxyAppVersionId') !== undefined
 				? { proxyAppVersionId: optionalString(payload, 'proxyAppVersionId') }
 				: {}),
+			...(parseProxyHosts(payload) !== undefined ? { proxyHosts: parseProxyHosts(payload) } : {}),
 			...(optionalBoolean(payload, 'ready') !== undefined ? { ready: optionalBoolean(payload, 'ready') } : {}),
 		}
 	},
@@ -320,6 +375,25 @@ const registrationResourceClaims = (registration: ProviderRegistration): string[
 		appId: registration.app.id,
 		env: registration.environment.env,
 	})
+	// A proxy target is routed by HOST, so a registration with no domain has nothing the proxy can serve:
+	// refuse it here, where nothing has been created yet, instead of at the first deploy's manifest compile.
+	if (manifest.target.proxy !== undefined) {
+		const domain = registration.environment.domain ?? ''
+		if (domain.trim() === '') {
+			throw new Error(
+				`Zerops proxy target \`${registration.app.id}/${registration.environment.env}\` requires a public domain: `
+					+ `pass --domain with a host this namespace serves (\`namespaces get ${namespace.id}\` lists them)`,
+			)
+		}
+		// One Caddy fronts the whole namespace and its host matcher reads `*` as a wildcard label, so a
+		// pattern here would answer for every sibling app. The manifest parser refuses it either way.
+		if (!isProxyHost(domain.toLowerCase())) {
+			throw new Error(
+				`Zerops proxy target \`${registration.app.id}/${registration.environment.env}\` domain \`${domain}\` is not a literal hostname: `
+					+ 'use dot-separated labels of letters, digits and `-` (no wildcard, no port, no placeholder)',
+			)
+		}
+	}
 	const namespaceClaims = new Set(namespaceResourceClaims(namespace))
 	for (const requirement of manifest.target.namespaceResources ?? []) {
 		if (!namespaceClaims.has(requirement.resourceKey)) {
@@ -503,10 +577,14 @@ const namespacePresentation = (
 	const postgres = target.postgres === undefined
 		? 'App-owned database services'
 		: `Shared ${target.postgres.type}${target.postgres.profile === undefined ? '' : ` (${target.postgres.profile})`}`
+	// Only a published subdomain namespace knows its own hosts; custom domains are bound out of band, so
+	// the provider names none and an operator reads them where they were bound.
+	const hosts = publicAccess === 'zerops-subdomain' && target.ready === true ? target.proxyHosts ?? [] : []
 	const instructions = [
 		...(publicAccess === 'custom-domain'
 			? [`Bind each application domain to the \`proxy\` service in Zerops project \`${projectName}\`; keep every app service private.`]
 			: ['Use the proxy Zerops subdomain only for non-production access; app services must remain private.']),
+		...(hosts.length === 0 ? [] : ['Register a proxy-target environment with one of the hosts below as its domain; each host serves one app.']),
 		...(target.postgres === undefined
 			? []
 			: ['Every app consuming the shared PostgreSQL binding shares its physical service and provider-issued credential.']),
@@ -528,6 +606,7 @@ const namespacePresentation = (
 			{ label: 'Public access', value: publicAccess },
 		],
 		instructions,
+		...(hosts.length === 0 ? {} : { hosts }),
 	}
 }
 
@@ -832,6 +911,38 @@ const ensureProxyConfiguration = async (
 	return deployRequired
 }
 
+/**
+ * The hosts the proxy publishes, off the platform-owned `zeropsSubdomain` variable.
+ *
+ * Read through the same `/env` listing every other namespace variable uses, and read AFTER the proxy is
+ * published: the variable names a host per DEPLOYED HTTP port, so a proxy that never deployed names none.
+ * Recording the answer in the target is what keeps `namespaces get` a database read.
+ */
+const readProxyHosts = async (
+	namespace: ProviderDeploymentNamespace,
+	target: NormalizedZeropsNamespaceTarget,
+	options: ZeropsNamespaceOptions,
+	signal: AbortSignal,
+): Promise<readonly ProviderNamespaceHost[]> => {
+	const proxyServiceId = target.proxyServiceId
+	if (proxyServiceId === undefined) {
+		throw new Error('Zerops namespace has no proxy service id')
+	}
+	try {
+		const variables = await options.api.listServiceEnv({ serviceId: proxyServiceId, signal })
+		const subdomains = variables.find((variable) => variable.key === ZEROPS_NAMESPACE_SUBDOMAIN_VARIABLE)
+		return subdomains === undefined ? [] : parseZeropsProxyHosts(subdomains.content)
+	} catch {
+		// A host listing is a convenience; the proxy is already built, deployed and published. Failing the
+		// namespace over it would report a placement that WORKS as broken. Never the cause: it can carry
+		// upstream text this provider has not redacted.
+		console.warn(
+			`Zerops namespace ${namespace.id}: reading the published proxy hosts failed; the placement is ready and lists none until its next reconcile`,
+		)
+		return []
+	}
+}
+
 const latestAfterBaseline = async (
 	target: NormalizedZeropsNamespaceTarget,
 	options: ZeropsNamespaceOptions,
@@ -1125,10 +1236,14 @@ const runNamespaceMutation = async (
 	if (target.publicAccess === 'zerops-subdomain') {
 		await ensureSubdomainAccess(target, options, input.signal)
 	}
+	const proxyHosts = target.publicAccess === 'zerops-subdomain' ? await readProxyHosts(namespace, target, options, input.signal) : []
 	target = {
 		...target,
 		proxyBaselineSequence: undefined,
 		proxyAppVersionId: undefined,
+		// Cleared when the proxy publishes none and on a custom-domain namespace, so the record never
+		// outlives what it describes.
+		proxyHosts: proxyHosts.length === 0 ? undefined : proxyHosts,
 		ready: true,
 	}
 	return checkpoint(input, namespace, target)

package/src/provider.ts

@@ -9,7 +9,7 @@
 // the poll loop rechecks it, the sleep between polls is interruptible, and a cancelled run asks Zerops to
 // cancel the build it started rather than leaving it running.
 
-import { createProvider, type ProviderDeploySession, type ProviderModule, type TypedProviderRun } from '@fabrika/provider-contract'
+import { createProvider, type JsonValue, type ProviderDeploySession, type ProviderModule, type TypedProviderRun } from '@fabrika/provider-contract'
 import {
 	waitForProcess,
 	ZEROPS_ACTIVE,
@@ -23,14 +23,16 @@ import {
 } from './api'
 import { zeropsTargetCodec } from './codec'
 import { defaultSleep, defaultZeropsCollaborators, type ZeropsCollaboratorFactory, type ZeropsCollaborators } from './collaborators'
+import { assertZeropsInvariants, renderYaml } from './compile'
 import {
+	type FabrikaImportDocument,
 	type FabrikaManifest,
 	manifestServiceHostnames,
-	renderFabrikaImportYaml,
 	verifyZeropsArtifactSourceDescriptor,
 	zeropsArtifactCodec,
 } from './manifest'
 import { buildZeropsPlan, resolveDeployHostname, type ZeropsJobSpec, type ZeropsPlan } from './plan'
+import { allowedReferenceHosts, foreignReferenceHost } from './service-references'
 import type { ZeropsSourceUploadInputV2, ZeropsSourceUploadResult } from './source'
 import type { ZeropsRunState, ZeropsRuntimeSource, ZeropsRuntimeTarget } from './types'
 
@@ -70,19 +72,139 @@ const assertRunning = (signal: AbortSignal): void => {
 
 const PLACEHOLDER = /\$\{([A-Z][A-Z0-9_]*)\}/g
 
-/** Resolve only variables declared by the manifest. Unknown or missing placeholders fail the deploy. */
-export function interpolateManifest(source: string, declared: string[], values: Record<string, string>): string {
-	const allowed = new Set(declared)
-	return source.replace(PLACEHOLDER, (_placeholder, name: string) => {
-		if (!allowed.has(name)) {
-			throw new Error(`zerops: manifest uses undeclared variable \`${name}\``)
+/** Fields that decide WHAT a service is: a placeholder there would let a value redefine the service. */
+const STRUCTURAL_FIELDS: readonly string[] = ['hostname', 'type', 'envIsolation', 'override']
+
+/** Rebuild the tree with every string leaf resolved — arrays and nested objects included. */
+const substituteLeaves = (value: JsonValue, resolve: (text: string) => string): JsonValue => {
+	if (typeof value === 'string') {
+		return resolve(value)
+	}
+	if (Array.isArray(value)) {
+		return value.map((item) => substituteLeaves(item, resolve))
+	}
+	if (value !== null && typeof value === 'object') {
+		return substituteRecord(value, resolve)
+	}
+	return value
+}
+
+const substituteRecord = (
+	record: { readonly [key: string]: JsonValue },
+	resolve: (text: string) => string,
+): { [key: string]: JsonValue } => {
+	const substituted: { [key: string]: JsonValue } = {}
+	for (const [key, entry] of Object.entries(record)) {
+		const planted = key.match(PLACEHOLDER)
+		if (planted !== null) {
+			throw new Error(`zerops: placeholder \`${String(planted[0])}\` stands in an import document key; a variable may only fill a value`)
 		}
-		const value = values[name]
-		if (value === undefined) {
-			throw new Error(`zerops: manifest variable \`${name}\` has no deploy-time value`)
+		// Defined rather than assigned: a literal `__proto__` key would otherwise set the prototype.
+		Object.defineProperty(substituted, key, {
+			value: substituteLeaves(entry, resolve),
+			enumerable: true,
+			writable: true,
+			configurable: true,
+		})
+	}
+	return substituted
+}
+
+/** A structural field that moved means a placeholder sat where only the compiler may write. */
+const assertStructureUnchanged = (before: FabrikaImportDocument, after: FabrikaImportDocument): void => {
+	if (JSON.stringify(before.project) !== JSON.stringify(after.project)) {
+		throw new Error('zerops: variable substitution changed the project entry; a variable may not stand in the project fabrika creates')
+	}
+	for (const [index, service] of after.services.entries()) {
+		const original = before.services[index]
+		for (const field of STRUCTURAL_FIELDS) {
+			if (original?.[field] !== service[field]) {
+				throw new Error(`zerops: variable substitution changed service field \`${field}\`; a variable may not stand in a service's identity`)
+			}
 		}
-		return value
-	})
+	}
+}
+
+/** Substitution is a single pass, so a placeholder left in the document came out of a variable's VALUE. */
+const assertNoPlaceholderLeft = (document: FabrikaImportDocument): void => {
+	const refuse = (text: string): void => {
+		const left = text.match(PLACEHOLDER)
+		if (left !== null) {
+			throw new Error(`zerops: placeholder \`${String(left[0])}\` survived substitution; a variable value may not carry one`)
+		}
+	}
+	const visitRecord = (record: { readonly [key: string]: JsonValue }): void => {
+		for (const [key, entry] of Object.entries(record)) {
+			refuse(key)
+			visit(entry)
+		}
+	}
+	const visit = (value: JsonValue): void => {
+		if (typeof value === 'string') {
+			refuse(value)
+			return
+		}
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item)
+			return
+		}
+		if (value !== null && typeof value === 'object') {
+			visitRecord(value)
+		}
+	}
+	if (document.project !== undefined) {
+		visitRecord(document.project)
+	}
+	for (const service of document.services) {
+		visitRecord(service)
+	}
+}
+
+/**
+ * Resolve the manifest's declared variables INTO THE DOCUMENT — never into the rendered YAML, where a
+ * value carrying a quote or a newline would be read as structure and could add a service or turn
+ * `envIsolation` off. Only variables the manifest declares resolve; every other placeholder fails the
+ * deploy, and so does a value that names a service outside the app (Zerops resolves `${host_KEY}`
+ * regardless of isolation). The document is re-checked here because this is the last point it is an object.
+ */
+export function interpolateManifest(
+	document: FabrikaImportDocument,
+	declared: readonly string[],
+	values: Record<string, string>,
+	ownHostnames: readonly string[],
+): FabrikaImportDocument {
+	const allowed = new Set(declared)
+	const hosts = allowedReferenceHosts(ownHostnames)
+	const resolve = (text: string): string => {
+		const substituted = text.replace(PLACEHOLDER, (_placeholder, name: string) => {
+			if (!allowed.has(name)) {
+				throw new Error(`zerops: manifest uses undeclared variable \`${name}\``)
+			}
+			const value = values[name]
+			if (value === undefined) {
+				throw new Error(`zerops: manifest variable \`${name}\` has no deploy-time value`)
+			}
+			const foreign = foreignReferenceHost(value, hosts)
+			if (foreign !== null) {
+				throw new Error(`zerops: manifest variable \`${name}\` references service \`${foreign}\`, which this app does not own`)
+			}
+			return value
+		})
+		// Adjacent values can spell a reference neither of them carries alone.
+		const foreign = substituted === text ? null : foreignReferenceHost(substituted, hosts)
+		if (foreign !== null) {
+			throw new Error(`zerops: a substituted value references service \`${foreign}\`, which this app does not own`)
+		}
+		return substituted
+	}
+	const services = document.services.map((service) => substituteRecord(service, resolve))
+	const substituted: FabrikaImportDocument = document.project === undefined
+		? { services }
+		: { project: substituteRecord(document.project, resolve), services }
+	assertZeropsInvariants(substituted)
+	assertStructureUnchanged(document, substituted)
+	assertNoPlaceholderLeft(substituted)
+	return substituted
 }
 
 /** Human-readable failure for a version that finished in a non-`ACTIVE` state. */
@@ -170,23 +292,41 @@ const cleanupPreTriggerVersion = async (env: StepEnv, source: ZeropsRuntimeSourc
 }
 
 /**
- * Relay whatever build log Zerops will give us into the run's progress sink.
+ * Relay ONE app version's build log into the run's progress sink.
+ *
+ * Scoped to the version being deployed: the runtime service's log window mixes every version that ever ran
+ * on it, so an unscoped read stamps a run's log with lines from earlier releases. `appVersionId` selects
+ * the build lines and `since` — the version's pipeline start — cuts the runtime ones
+ * (see `ZeropsApi.readBuildLog`). Before the platform reports a pipeline start there is nothing to cut
+ * against, so no runtime line is relayed yet. The cut is by time, so the OUTGOING container's own lines
+ * still arrive until it is replaced; what it removes is every earlier version's history.
  *
- * Deliberately FAILURE-TOLERANT: the log service's protocol is the one shape in this driver nobody could
- * verify against a document (see `ZeropsApi.readBuildLog`). An unverified endpoint must never be able to
- * fail a deploy, so a broken guess degrades to "no lines relayed" and the run still succeeds or fails on
- * the platform's process and app-version statuses.
+ * Deliberately FAILURE-TOLERANT: a log service must never be able to fail a deploy, so an error degrades
+ * to "no lines relayed" and the run still succeeds or fails on the platform's process and app-version
+ * statuses.
  *
  * Relay is pull-based (ADR-0003), so each poll re-reads a window that overlaps the last one; `seen` keeps
  * the run log from repeating itself. Two genuinely identical lines with no timestamp collapse into one —
  * an acceptable trade for not printing the same window every three seconds.
  */
-const relayLog = async (env: StepEnv, access: ZeropsLogAccess | null, seen: Set<string>): Promise<void> => {
+const relayLog = async (
+	env: StepEnv,
+	access: ZeropsLogAccess | null,
+	seen: Set<string>,
+	appVersionId: string,
+	since: string | undefined,
+): Promise<void> => {
 	if (access === null) {
 		return
 	}
 	try {
-		const lines = await env.zerops.api.readBuildLog({ access, serviceId: env.run.target.serviceId, signal: env.signal })
+		const lines = await env.zerops.api.readBuildLog({
+			access,
+			serviceId: env.run.target.serviceId,
+			appVersionId,
+			...(since === undefined ? {} : { since }),
+			signal: env.signal,
+		})
 		for (const line of lines) {
 			const key = `${line.timestamp ?? ''}\u0000${line.message}`
 			if (seen.has(key)) {
@@ -248,7 +388,7 @@ const awaitVersion = async (env: StepEnv, appVersionId: string, processId: strin
 			log(`  ${appVersionId}: ${version.status ?? 'unknown'}`)
 			previous = version.status
 		}
-		await relayLog(env, access, seen)
+		await relayLog(env, access, seen, appVersionId, version.build?.pipelineStart)
 
 		if (process?.status !== undefined && ZEROPS_PROCESS_TERMINAL.has(process.status) && process.status !== ZEROPS_PROCESS_FINISHED) {
 			throw new Error(
@@ -470,10 +610,8 @@ export const createZeropsProvider = (
 				throw new Error(`zerops: artifact environment drift: expected \`${run.env}\`, got \`${run.artifact.app.env}\``)
 			}
 			const hostnames = manifestServiceHostnames(run.artifact)
-			const compiled = {
-				yaml: interpolateManifest(renderFabrikaImportYaml(run.artifact), run.artifact.app.pipeline.vars, run.vars),
-				hostnames,
-			}
+			const document = interpolateManifest(run.artifact.target.importDocument, run.artifact.app.pipeline.vars, run.vars, hostnames)
+			const compiled = { yaml: renderYaml(document), hostnames }
 			const deployHostname = resolveDeployHostname(run.artifact)
 			const plan: ZeropsPlan = buildZeropsPlan(run.artifact, run.target, run.env)
 			const env: StepEnv = {

package/src/service-references.ts

@@ -0,0 +1,28 @@
+/**
+ * `${<host>_<KEY>}` — Zerops resolves it across services regardless of `envIsolation`, so the host is the boundary.
+ * `${RUNTIME_<host>_<KEY>}`, the build-time bridge, counts as a reference to that host until measured otherwise.
+ */
+const SERVICE_REFERENCE = /\$\{(?:RUNTIME_)?([a-z0-9]{1,25})_[A-Za-z0-9_]+\}/g
+
+/** Namespace services every app in it may reference; the proxy is deliberately not one of them. */
+const SHARED_NAMESPACE_HOSTNAMES: readonly string[] = ['postgres']
+
+/** Hosts named by cross-service references in `text`, deduplicated, in order of first appearance. */
+export function serviceReferenceHosts(text: string): string[] {
+	const hosts: string[] = []
+	for (const match of text.matchAll(SERVICE_REFERENCE)) {
+		const host = match[1]
+		if (host !== undefined && !hosts.includes(host)) hosts.push(host)
+	}
+	return hosts
+}
+
+/** The hosts a service of this app may reference: its own declared hostnames plus the namespace's shared services. */
+export function allowedReferenceHosts(ownHostnames: readonly string[]): ReadonlySet<string> {
+	return new Set([...ownHostnames, ...SHARED_NAMESPACE_HOSTNAMES])
+}
+
+/** The first referenced host outside `allowed`, or null when every reference stays inside the app. */
+export function foreignReferenceHost(text: string, allowed: ReadonlySet<string>): string | null {
+	return serviceReferenceHosts(text).find((host) => !allowed.has(host)) ?? null
+}