@fabrika/provider-zerops 0.0.26 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.0.26",
+	"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.26",
-		"@fabrika/auth-core": "^0.0.26",
-		"@fabrika/provider-contract": "^0.0.26",
-		"@fabrika/proxy-contract": "^0.0.26"
+		"@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/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

@@ -14,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,
@@ -377,11 +377,22 @@ const registrationResourceClaims = (registration: ProviderRegistration): string[
 	})
 	// 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 && (registration.environment.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)`,
-		)
+	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 ?? []) {

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. */
@@ -488,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
+}