@fabrika/provider-zerops 0.0.26 → 0.3.1

package/src/manifest.ts

@@ -1,6 +1,12 @@
-import type { AppActionDef, AppGates, AppSchema, AppScopeDef, GateRule, RoleDef } from '@fabrika/auth-core'
+import { appSchemaSchema } from '@fabrika/auth'
+import type { AppSchema } from '@fabrika/auth-core'
 import type { JsonValue, ProviderCodec } from '@fabrika/provider-contract'
+import { normalizeGateRule, proxyGateRuleFieldsSchema } from '@fabrika/proxy-core/manifest'
+import { z } from 'zod'
 import { compileImport, ENV_ISOLATION, OVERRIDE, renderYaml } from './compile'
+import { parseZeropsDescriptor, selectZeropsDescriptorSetup } from './descriptor'
+import { assertAuthoredManagedDocument, assertAuthoredManagedInputs } from './managed-env'
+import { allowedReferenceHosts, foreignReferenceHost } from './service-references'
 import type { ZeropsAppConfig, ZeropsNamespaceResourceRequirement, ZeropsProxySpec, ZeropsSharedPostgresBinding } from './types'
 
 export const FABRIKA_MANIFEST_VERSION = 3
@@ -46,7 +52,7 @@ export interface FabrikaManifest {
 		/** The exact repository-root build descriptor used for this artifact. */
 		sourceDescriptor: ZeropsArtifactSourceDescriptor
 		/** The canonical document used both for resource claims and the Zerops API payload. */
-		importDocument: FabrikaImportDocument
+		importDocument: FabrikaManifestImportDocument
 		deployService: string
 		zeropsSetup?: string
 		proxy?: ZeropsProxySpec
@@ -59,243 +65,171 @@ export interface ManifestExpectation {
 	env?: string
 }
 
-const prop = (value: unknown, key: string): unknown => typeof value === 'object' && value !== null ? Reflect.get(value, key) : undefined
-
-const jsonValue = (value: unknown): JsonValue => {
-	if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-		return value
-	}
-	if (Array.isArray(value)) {
-		return value.map(jsonValue)
-	}
-	if (typeof value === 'object') {
-		const result: { [key: string]: JsonValue } = {}
-		for (const [key, entry] of Object.entries(value)) {
-			if (entry !== undefined) {
-				result[key] = jsonValue(entry)
-			}
-		}
-		return result
-	}
-	throw new Error(`Fabrika manifest contains a non-JSON ${typeof value} value`)
-}
-
-const jsonObject = (value: unknown, label: string): { [key: string]: JsonValue } => {
-	const parsed = jsonValue(value)
-	if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-		throw new Error(`invalid fabrika manifest ${label}`)
-	}
-	return parsed
-}
-
-const string = (value: unknown, key: string): string | undefined => {
-	const candidate = prop(value, key)
-	return typeof candidate === 'string' ? candidate : undefined
-}
-
-const nonEmptyString = (value: unknown, key: string): string | undefined => {
-	const candidate = string(value, key)
-	return candidate !== undefined && candidate !== '' ? candidate : undefined
-}
-
-const stringArray = (value: unknown, key: string): string[] | undefined => {
-	const candidate = prop(value, key)
-	if (!Array.isArray(candidate) || candidate.some((item) => typeof item !== 'string' || item === '')) {
-		return undefined
+export const assertFabrikaManifestCoordinates = (app: Pick<FabrikaManifest['app'], 'id' | 'env'>, expected: ManifestExpectation): void => {
+	if (expected.appId !== undefined && expected.appId !== app.id) {
+		throw new Error(`manifest app drift: expected \`${expected.appId}\`, got \`${app.id}\``)
 	}
-	return candidate
-}
-
-const optionalString = (value: unknown, key: string): string | null => {
-	const candidate = prop(value, key)
-	if (candidate === undefined) {
-		return null
+	if (expected.env !== undefined && expected.env !== app.env) {
+		throw new Error(`manifest environment drift: expected \`${expected.env}\`, got \`${app.env}\``)
 	}
-	return typeof candidate === 'string' && candidate !== '' ? candidate : null
 }
 
-function parseScope(value: unknown): AppScopeDef | null {
-	const type = nonEmptyString(value, 'type')
-	const label = optionalString(value, 'label')
-	if (type === undefined || (prop(value, 'label') !== undefined && label === null)) {
-		return null
-	}
-	return label === null ? { type } : { type, label }
+const manifestJsonSchema: z.ZodType<JsonValue, z.ZodTypeDef, unknown> = z.lazy(() =>
+	z.union([
+		z.null(),
+		z.string(),
+		z.number(),
+		z.nan(),
+		z.boolean(),
+		z.array(manifestJsonSchema),
+		z.preprocess((value) =>
+			typeof value === 'object' && value !== null && !Array.isArray(value)
+				? Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined))
+				: value, z.record(manifestJsonSchema)),
+	])
+)
+const jsonValue = (value: unknown): JsonValue => {
+	const parsed = manifestJsonSchema.safeParse(value)
+	if (!parsed.success) throw new Error('Fabrika manifest contains a non-JSON value')
+	return parsed.data
 }
 
-function parseAction(value: unknown): AppActionDef | null {
-	const action = nonEmptyString(value, 'action')
-	const description = optionalString(value, 'description')
-	if (action === undefined || (prop(value, 'description') !== undefined && description === null)) {
-		return null
+const nonEmptyStringsSchema = z.array(z.string().min(1))
+// Unlike the proxy wire contract, the manifest refuses a null service credential.
+const manifestGateSchema = proxyGateRuleFieldsSchema
+	.refine((rule) => rule.kind !== 'service' || rule.credential !== null)
+	.transform(normalizeGateRule)
+const manifestProxySchema = z.object({ upstream: z.string().min(1), gates: z.object({ rules: z.array(manifestGateSchema) }) })
+const namespaceResourcesSchema = z.array(z.object({
+	resourceKey: z.literal('service:postgres'),
+	hostname: z.literal('postgres'),
+	connectionString: z.literal(SHARED_POSTGRES_CONNECTION_STRING),
+})).max(1)
+
+const manifestAppSchema = z.object({
+	id: z.string().min(1),
+	env: z.string().min(1),
+	schema: appSchemaSchema.optional(),
+	pipeline: z.object({ secrets: nonEmptyStringsSchema, vars: nonEmptyStringsSchema }),
+})
+const manifestEnvelopeSchema = z.object({ manifestVersion: z.literal(FABRIKA_MANIFEST_VERSION), app: manifestAppSchema, target: z.unknown() })
+
+export const zeropsArtifactSourceDescriptorSchema = z.object({
+	path: z.literal('zerops.yaml'),
+	contents: z.string().min(1).refine((contents) => new TextEncoder().encode(contents).byteLength <= ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES),
+	sha256: z.string().regex(SHA256_PATTERN),
+}).strict()
+
+/** Refuse fields fabrika owns, so an authored document can never set them. */
+const forbidFields = (fields: readonly string[], message: string) => (record: Record<string, JsonValue>, ctx: z.RefinementCtx): void => {
+	for (const field of fields) {
+		if (Object.hasOwn(record, field)) ctx.addIssue({ code: 'custom', path: [field], message })
 	}
-	return description === null ? { action } : { action, description }
 }
-
-function parseRole(value: unknown): RoleDef | null {
-	const name = nonEmptyString(value, 'name')
-	const description = optionalString(value, 'description')
-	const permissions = stringArray(value, 'permissions')
-	if (name === undefined || permissions === undefined || (prop(value, 'description') !== undefined && description === null)) {
-		return null
+const importServiceSchema = z.intersection(
+	z.record(manifestJsonSchema),
+	z.object({
+		hostname: z.string().regex(ZEROPS_SERVICE_HOSTNAME_PATTERN),
+		type: z.string().min(1),
+		envIsolation: z.literal(ENV_ISOLATION),
+		override: z.literal(OVERRIDE),
+	}),
+).superRefine(forbidFields(['envSecrets', 'dotEnvSecrets'], 'invalid fabrika manifest: Zerops import contains a forbidden environment field'))
+const importProjectSchema = z.intersection(z.record(manifestJsonSchema), z.object({ envIsolation: z.literal(ENV_ISOLATION) }))
+	.superRefine(forbidFields(['envVariables'], 'invalid fabrika manifest: Zerops import contains a forbidden project environment field'))
+
+/** 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)
 	}
-	return description === null ? { name, permissions } : { name, description, permissions }
-}
-
-function parseSchema(value: unknown): AppSchema | null {
-	const rawScopes = prop(value, 'scopes')
-	const rawActions = prop(value, 'actions')
-	const rawRoles = prop(value, 'roles')
-	if (!Array.isArray(rawScopes) || !Array.isArray(rawActions) || typeof rawRoles !== 'object' || rawRoles === null || Array.isArray(rawRoles)) {
+	if (Array.isArray(value)) {
+		for (const entry of value) {
+			const host = foreignReferenceInValue(entry, allowed)
+			if (host !== null) return host
+		}
 		return null
 	}
-	const scopes: AppScopeDef[] = []
-	for (const raw of rawScopes) {
-		const scope = parseScope(raw)
-		if (scope === null) return null
-		scopes.push(scope)
-	}
-	const actions: AppActionDef[] = []
-	for (const raw of rawActions) {
-		const action = parseAction(raw)
-		if (action === null) return null
-		actions.push(action)
-	}
-	const roles: Record<string, RoleDef> = {}
-	for (const [key, raw] of Object.entries(rawRoles)) {
-		const role = parseRole(raw)
-		if (key === '' || role === null) return null
-		roles[key] = role
-	}
-	return { scopes, actions, roles }
-}
-
-function parseGate(value: unknown): GateRule | null {
-	const path = nonEmptyString(value, 'path')
-	const kind = string(value, 'kind')
-	if (path === undefined || !path.startsWith('/')) return null
-	if (kind === 'public' || kind === 'human') return { path, kind }
-	if (kind !== 'service') return null
-	const rawCredential = prop(value, 'credential')
-	if (rawCredential === undefined) return { path, kind }
-	const location = string(rawCredential, 'in')
-	const name = nonEmptyString(rawCredential, 'name')
-	if ((location !== 'header' && location !== 'query' && location !== 'cookie') || name === undefined) return null
-	return { path, kind, credential: { in: location, name } }
-}
-
-function parseGates(value: unknown): AppGates | null {
-	const rawRules = prop(value, 'rules')
-	if (!Array.isArray(rawRules)) return null
-	const rules: GateRule[] = []
-	for (const raw of rawRules) {
-		const rule = parseGate(raw)
-		if (rule === null) return null
-		rules.push(rule)
-	}
-	return { rules }
-}
-
-const parseNamespaceResources = (value: unknown): ZeropsNamespaceResourceRequirement[] | null => {
-	if (!Array.isArray(value)) return null
-	const resources: ZeropsNamespaceResourceRequirement[] = []
-	let hasPostgres = false
-	for (const resource of value) {
-		if (
-			string(resource, 'resourceKey') !== 'service:postgres'
-			|| string(resource, 'hostname') !== 'postgres'
-			|| string(resource, 'connectionString') !== SHARED_POSTGRES_CONNECTION_STRING
-		) {
-			return null
+	if (typeof value === 'object' && value !== null) {
+		for (const [key, entry] of Object.entries(value)) {
+			const host = foreignReferenceHost(key, allowed) ?? foreignReferenceInValue(entry, allowed)
+			if (host !== null) return host
 		}
-		if (hasPostgres) return null
-		hasPostgres = true
-		resources.push({
-			resourceKey: 'service:postgres',
-			hostname: 'postgres',
-			connectionString: SHARED_POSTGRES_CONNECTION_STRING,
-		})
 	}
-	return resources
+	return null
 }
 
-function parseProxy(value: unknown): ZeropsProxySpec | null {
-	const upstream = nonEmptyString(value, 'upstream')
-	const gates = parseGates(prop(value, 'gates'))
-	return upstream === undefined || gates === null ? null : { upstream, gates }
-}
-
-const parseImportDocument = (value: unknown): FabrikaImportDocument => {
-	if (value === undefined) {
-		throw new Error('invalid fabrika manifest Zerops import document')
-	}
-	const raw = jsonObject(value, 'Zerops import document')
-	const unknownKeys = Object.keys(raw).filter((key) => key !== 'project' && key !== 'services')
-	if (unknownKeys.length > 0) {
-		throw new Error(`invalid fabrika manifest Zerops import document field \`${unknownKeys[0]}\``)
-	}
-	const rawServices = raw['services']
-	if (!Array.isArray(rawServices) || rawServices.length === 0) {
-		throw new Error('invalid fabrika manifest Zerops import services')
-	}
-	const services: Array<{ readonly [key: string]: JsonValue }> = []
-	const hostnames = new Set<string>()
-	for (const [index, rawService] of rawServices.entries()) {
-		const service = jsonObject(rawService, `Zerops import service ${index}`)
-		const hostname = service['hostname']
-		if (typeof hostname !== 'string' || !ZEROPS_SERVICE_HOSTNAME_PATTERN.test(hostname)) {
-			throw new Error(`invalid fabrika manifest Zerops service hostname at index ${index}`)
-		}
-		if (hostnames.has(hostname)) {
-			throw new Error(`invalid fabrika manifest: duplicate Zerops service hostname \`${hostname}\``)
-		}
-		if (typeof service['type'] !== 'string' || service['type'] === '') {
-			throw new Error(`invalid fabrika manifest Zerops service type for \`${hostname}\``)
-		}
-		// `override: true` is required on EVERY service class, managed included — without it the platform
-		// rejects a re-apply of the whole document as a name collision (see `compile.ts`).
-		if (service['envIsolation'] !== ENV_ISOLATION || service['override'] !== OVERRIDE) {
-			throw new Error(`invalid fabrika manifest Zerops service invariants for \`${hostname}\``)
+const importDocumentSchema = z.object({ project: importProjectSchema.optional(), services: z.array(importServiceSchema).min(1) })
+	.strict()
+	.superRefine(({ services }, ctx) => {
+		const hostnames = services.map((service) => service.hostname)
+		const duplicate = hostnames.find((hostname, index) => hostnames.indexOf(hostname) !== index)
+		if (duplicate !== undefined) {
+			ctx.addIssue({ code: 'custom', message: `invalid fabrika manifest: duplicate Zerops service hostname \`${duplicate}\`` })
+			return
 		}
-		if (service['envSecrets'] !== undefined || service['dotEnvSecrets'] !== undefined) {
-			throw new Error('invalid fabrika manifest: Zerops import contains a forbidden environment field')
-		}
-		hostnames.add(hostname)
-		services.push(service)
-	}
-	const rawProject = raw['project']
-	let project: { readonly [key: string]: JsonValue } | undefined
-	if (rawProject !== undefined) {
-		project = jsonObject(rawProject, 'Zerops import project')
-		if (project['envIsolation'] !== ENV_ISOLATION || project['envVariables'] !== undefined) {
-			throw new Error('invalid fabrika manifest: Zerops import contains a forbidden project environment field')
+		// 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 service of services) {
+			const foreign = foreignReferenceInValue(service, allowed)
+			if (foreign !== null) {
+				ctx.addIssue({
+					code: 'custom',
+					message: `invalid fabrika manifest: Zerops service \`${service.hostname}\` references service \`${foreign}\`, which this app does not own`,
+				})
+				return
+			}
 		}
-	}
-	return project === undefined ? { services } : { project, services }
+	})
+
+/** The import document a manifest carries: every service already holds the ADR-0004 invariants. */
+export type FabrikaManifestImportDocument = z.infer<typeof importDocumentSchema>
+
+const manifestTargetSchema = z.object({
+	sourceDescriptor: zeropsArtifactSourceDescriptorSchema,
+	platform: z.literal('zerops'),
+	deployService: z.string().min(1),
+	importDocument: importDocumentSchema,
+	zeropsSetup: z.string().min(1).optional(),
+	proxy: manifestProxySchema.optional(),
+	namespaceResources: namespaceResourcesSchema.optional(),
+})
+
+const importDocumentError = (issue: z.ZodIssue, path: readonly (string | number)[]): string => {
+	const [section, index, field] = path
+	if (issue.code === 'custom') return issue.message
+	if (issue.code === 'unrecognized_keys' && section === undefined) return `invalid fabrika manifest Zerops import document field \`${issue.keys[0]}\``
+	if (section === 'project') {
+		return index === 'envIsolation'
+			? 'invalid fabrika manifest: Zerops import contains a forbidden project environment field'
+			: 'invalid fabrika manifest Zerops import project'
+	}
+	if (typeof index !== 'number') return 'invalid fabrika manifest Zerops import services'
+	if (field === 'hostname') return `invalid fabrika manifest Zerops service hostname at index ${index}`
+	return `invalid fabrika manifest Zerops service ${field === 'type' ? 'type' : 'invariants'} at index ${index}`
 }
 
-const parseSourceDescriptor = (value: unknown): ZeropsArtifactSourceDescriptor => {
-	if (value === undefined) {
-		throw new Error('invalid fabrika manifest Zerops source descriptor')
-	}
-	const raw = jsonObject(value, 'Zerops source descriptor')
-	const unknownKeys = Object.keys(raw).filter((key) => key !== 'path' && key !== 'contents' && key !== 'sha256')
-	if (unknownKeys.length > 0) {
-		throw new Error(`invalid fabrika manifest Zerops source descriptor field \`${unknownKeys[0]}\``)
-	}
-	const contents = raw['contents']
-	const sha256 = raw['sha256']
-	if (
-		raw['path'] !== 'zerops.yaml'
-		|| typeof contents !== 'string'
-		|| contents === ''
-		|| new TextEncoder().encode(contents).byteLength > ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES
-		|| typeof sha256 !== 'string'
-		|| !SHA256_PATTERN.test(sha256)
-	) {
-		throw new Error('invalid fabrika manifest Zerops source descriptor')
+const targetError = (issue: z.ZodIssue | undefined): string => {
+	const [section, ...rest] = issue?.path ?? []
+	if (issue === undefined) return 'invalid fabrika manifest Zerops target'
+	switch (section) {
+		case 'sourceDescriptor':
+			return issue.code === 'unrecognized_keys' && rest.length === 0
+				? `invalid fabrika manifest Zerops source descriptor field \`${issue.keys[0]}\``
+				: 'invalid fabrika manifest Zerops source descriptor'
+		case 'importDocument':
+			return importDocumentError(issue, rest)
+		case 'zeropsSetup':
+			return 'invalid fabrika manifest zeropsSetup'
+		case 'proxy':
+			return 'invalid fabrika manifest proxy declaration'
+		case 'namespaceResources':
+			return 'invalid fabrika manifest namespace resources'
+		default:
+			return 'invalid fabrika manifest Zerops target'
 	}
-	return { path: 'zerops.yaml', contents, sha256 }
 }
 
 export const createZeropsArtifactSourceDescriptor = async (contents: string): Promise<ZeropsArtifactSourceDescriptor> => {
@@ -319,13 +253,7 @@ export const verifyZeropsArtifactSourceDescriptor = async (descriptor: ZeropsArt
 }
 
 export const manifestServiceHostnames = (manifest: FabrikaManifest): string[] =>
-	manifest.target.importDocument.services.map((service) => {
-		const hostname = service['hostname']
-		if (typeof hostname !== 'string') {
-			throw new Error('invalid canonical Zerops service hostname')
-		}
-		return hostname
-	})
+	manifest.target.importDocument.services.map((service) => service.hostname)
 
 export const renderFabrikaImportYaml = (manifest: FabrikaManifest): string => renderYaml(manifest.target.importDocument)
 
@@ -333,86 +261,48 @@ export const renderFabrikaImportYaml = (manifest: FabrikaManifest): string => re
 export const renderFabrikaProvisioningYaml = (manifest: FabrikaManifest): string =>
 	renderYaml({
 		...(manifest.target.importDocument.project === undefined ? {} : { project: manifest.target.importDocument.project }),
-		services: manifest.target.importDocument.services.map((service) => ({ ...service, startWithoutCode: true })),
+		services: manifest.target.importDocument.services.map((service) => ({ ...service, override: false, startWithoutCode: true })),
 	})
 
 export function parseFabrikaManifest(value: unknown, expected: ManifestExpectation = {}): FabrikaManifest {
-	if (prop(value, 'manifestVersion') !== FABRIKA_MANIFEST_VERSION) {
-		throw new Error(`unsupported fabrika manifest version (expected ${FABRIKA_MANIFEST_VERSION})`)
-	}
-	const rawApp = prop(value, 'app')
-	const id = nonEmptyString(rawApp, 'id')
-	const env = nonEmptyString(rawApp, 'env')
-	const rawPipeline = prop(rawApp, 'pipeline')
-	const secrets = stringArray(rawPipeline, 'secrets')
-	const vars = stringArray(rawPipeline, 'vars')
-	if (id === undefined || env === undefined || secrets === undefined || vars === undefined) {
-		throw new Error('invalid fabrika manifest app metadata')
-	}
-	if (expected.appId !== undefined && expected.appId !== id) {
-		throw new Error(`manifest app drift: expected \`${expected.appId}\`, got \`${id}\``)
-	}
-	if (expected.env !== undefined && expected.env !== env) {
-		throw new Error(`manifest environment drift: expected \`${expected.env}\`, got \`${env}\``)
-	}
-	const rawSchema = prop(rawApp, 'schema')
-	let schema: AppSchema | undefined
-	if (rawSchema !== undefined) {
-		const parsed = parseSchema(rawSchema)
-		if (parsed === null) {
-			throw new Error('invalid fabrika manifest schema')
-		}
-		schema = parsed
-	}
-
-	const rawTarget = prop(value, 'target')
-	const sourceDescriptor = parseSourceDescriptor(prop(rawTarget, 'sourceDescriptor'))
-	const rawImportDocument = prop(rawTarget, 'importDocument')
-	const deployService = nonEmptyString(rawTarget, 'deployService')
-	if (
-		string(rawTarget, 'platform') !== 'zerops'
-		|| deployService === undefined
-	) {
-		throw new Error('invalid fabrika manifest Zerops target')
-	}
-	const importDocument = parseImportDocument(rawImportDocument)
-	const serviceHostnames = importDocument.services.map((service) => {
-		const hostname = service['hostname']
-		if (typeof hostname !== 'string') {
-			throw new Error('invalid fabrika manifest Zerops service hostname')
-		}
-		return hostname
-	})
+	const envelope = manifestEnvelopeSchema.safeParse(value)
+	if (!envelope.success) {
+		const [section, field] = envelope.error.issues[0]?.path ?? []
+		if (section !== 'app') throw new Error(`unsupported fabrika manifest version (expected ${FABRIKA_MANIFEST_VERSION})`)
+		throw new Error(field === 'schema' ? 'invalid fabrika manifest schema' : 'invalid fabrika manifest app metadata')
+	}
+	const { id, env, schema, pipeline: { secrets, vars } } = envelope.data.app
+	assertFabrikaManifestCoordinates({ id, env }, expected)
+
+	const target = manifestTargetSchema.safeParse(envelope.data.target)
+	if (!target.success) {
+		throw new Error(targetError(target.error.issues[0]))
+	}
+	const { sourceDescriptor, deployService, importDocument, zeropsSetup, proxy, namespaceResources } = target.data
+	assertAuthoredManagedDocument(importDocument.services)
+	if (importDocument.project !== undefined) assertAuthoredManagedDocument(importDocument.project)
+	assertAuthoredManagedInputs({ variableNames: vars, secretNames: secrets })
+	const parsedDescriptor = parseZeropsDescriptor(sourceDescriptor.contents)
+	assertAuthoredManagedDocument(parsedDescriptor.document)
+	const serviceHostnames = importDocument.services.map((service) => service.hostname)
 	if (!serviceHostnames.includes(deployService)) {
 		throw new Error('invalid fabrika manifest Zerops deploy service')
 	}
-	const zeropsSetup = optionalString(rawTarget, 'zeropsSetup')
-	if (prop(rawTarget, 'zeropsSetup') !== undefined && zeropsSetup === null) {
-		throw new Error('invalid fabrika manifest zeropsSetup')
-	}
-	const rawProxy = prop(rawTarget, 'proxy')
-	let proxy: ZeropsProxySpec | undefined
-	if (rawProxy !== undefined) {
-		const parsed = parseProxy(rawProxy)
-		if (parsed === null) {
-			throw new Error('invalid fabrika manifest proxy declaration')
-		}
-		proxy = parsed
-		const separator = parsed.upstream.indexOf(':')
-		const upstreamHostname = separator === -1 ? parsed.upstream : parsed.upstream.slice(0, separator)
+	const foreignInDescriptor = foreignReferenceInValue(
+		parsedDescriptor.document,
+		allowedReferenceHosts(serviceHostnames),
+	)
+	if (foreignInDescriptor !== null) {
+		throw new Error(`invalid fabrika manifest: zerops.yaml references service \`${foreignInDescriptor}\`, which this app does not own`)
+	}
+	selectZeropsDescriptorSetup(parsedDescriptor, zeropsSetup)
+	if (proxy !== undefined) {
+		const separator = proxy.upstream.indexOf(':')
+		const upstreamHostname = separator === -1 ? proxy.upstream : proxy.upstream.slice(0, separator)
 		if (!serviceHostnames.includes(upstreamHostname)) {
 			throw new Error(`invalid fabrika manifest: proxy upstream service \`${upstreamHostname}\` is not owned by this app`)
 		}
 	}
-	const rawNamespaceResources = prop(rawTarget, 'namespaceResources')
-	let namespaceResources: ZeropsNamespaceResourceRequirement[] | undefined
-	if (rawNamespaceResources !== undefined) {
-		const parsed = parseNamespaceResources(rawNamespaceResources)
-		if (parsed === null) {
-			throw new Error('invalid fabrika manifest namespace resources')
-		}
-		namespaceResources = parsed
-	}
 	if (namespaceResources?.some((resource) => serviceHostnames.includes(resource.hostname)) === true) {
 		throw new Error('invalid fabrika manifest: an app cannot declare a namespace-owned service')
 	}
@@ -430,7 +320,7 @@ export function parseFabrikaManifest(value: unknown, expected: ManifestExpectati
 			sourceDescriptor,
 			importDocument,
 			deployService,
-			...(zeropsSetup !== null ? { zeropsSetup } : {}),
+			...(zeropsSetup !== undefined ? { zeropsSetup } : {}),
 			...(proxy !== undefined ? { proxy } : {}),
 			...(namespaceResources !== undefined ? { namespaceResources } : {}),
 		},
@@ -454,31 +344,21 @@ export function compileFabrikaManifest(config: ZeropsAppConfig, env: string, sou
 		if (deployService === undefined || !serviceHostnames.includes(deployService)) {
 			throw new Error('fabrika app build: a multi-service Zerops app must name a valid deployService')
 		}
-		if (config.target.namespaceResources?.some((resource) => serviceHostnames.includes(resource.hostname)) === true) {
-			throw new Error('fabrika app build: an app cannot declare a namespace-owned service')
-		}
-		const manifest: FabrikaManifest = {
+		const candidate = {
 			manifestVersion: FABRIKA_MANIFEST_VERSION,
-			app: {
-				id: config.id,
-				env,
-				...(config.schema !== undefined ? { schema: config.schema } : {}),
-				pipeline: {
-					secrets: [...(config.pipeline?.secrets ?? [])],
-					vars: [...declaredVars],
-				},
-			},
+			app: { id: config.id, env, schema: config.schema, pipeline: { secrets: config.pipeline?.secrets ?? [], vars: declaredVars } },
 			target: {
 				platform: 'zerops',
 				sourceDescriptor,
-				importDocument: parseImportDocument(document),
+				importDocument: document,
 				deployService,
-				...(config.target.zeropsSetup !== undefined ? { zeropsSetup: config.target.zeropsSetup } : {}),
-				...(config.target.proxy !== undefined ? { proxy: config.target.proxy } : {}),
-				...(config.target.namespaceResources !== undefined ? { namespaceResources: [...config.target.namespaceResources] } : {}),
+				zeropsSetup: config.target.zeropsSetup,
+				proxy: config.target.proxy,
+				namespaceResources: config.target.namespaceResources,
 			},
 		}
-		return parseFabrikaManifest(manifest, { appId: config.id, env })
+		// The JSON copy is the artifact's own form: authored objects lose inherited fields and undefined keys once, here.
+		return parseFabrikaManifest(jsonValue(candidate), { appId: config.id, env })
 	} finally {
 		for (const name of declaredVars) {
 			const value = prior[name]
@@ -497,3 +377,16 @@ export const zeropsArtifactCodec: ProviderCodec<FabrikaManifest> = {
 	encode: jsonValue,
 	decode: (payload) => parseFabrikaManifest(payload),
 }
+
+/** Hash the original validated artifact, never an interpolated import or execution overlay. */
+export async function hashFabrikaManifest(manifest: FabrikaManifest): Promise<string> {
+	const canonical = (value: JsonValue): JsonValue => {
+		if (Array.isArray(value)) return value.map(canonical)
+		if (typeof value !== 'object' || value === null) return value
+		return Object.fromEntries(
+			Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, entry]) => [key, canonical(entry)]),
+		)
+	}
+	const bytes = new TextEncoder().encode(JSON.stringify(canonical(zeropsArtifactCodec.encode(manifest))))
+	return Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}