@fabrika/provider-zerops 0.3.3 → 0.4.0

package/src/namespace/update.ts

@@ -0,0 +1,212 @@
+import {
+	PROVIDER_NAMESPACE_IMMUTABLE,
+	PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED,
+	type ProviderDeploymentNamespace,
+	type ProviderEnvelope,
+	type ProviderNamespaceUpdateInput,
+	type ProviderNamespaceUpdatePlan,
+	type ProviderNamespaceUpdates,
+} from '@fabrika/provider-contract'
+import { waitForProcess, ZeropsApiError, type ZeropsProcess } from '../api'
+import { defaultSleep } from '../collaborators'
+import { envelope, namespaceUpdatePayloadSchema, normalizeTarget, zeropsNamespaceTargetCodec } from './codec'
+import { asNamespaceError, namespaceError, ZEROPS_NAMESPACE_CANCELLED } from './errors'
+import type { NormalizedZeropsNamespaceTarget, ZeropsNamespaceOptions, ZeropsNamespacePostgres, ZeropsNamespaceTarget } from './types'
+import { validateService } from './validation'
+
+// Budget: ≤ 60 s on the autoscaling process plus ≤ 30 s of read-back — inside one request, and inside the lease TTL.
+const PROCESS_POLL_INTERVAL_MS = 2_000
+const PROCESS_POLL_ATTEMPTS = 30
+const READBACK_INTERVAL_MS = 3_000
+/** UNVERIFIED: how soon `autoscalingProfileId` reads the new profile after the PUT and its process finish. */
+const READBACK_ATTEMPTS = 10
+
+type FixedField = Exclude<keyof ZeropsNamespaceTarget, 'postgres'>
+
+/** Every target field but `postgres`, whose profile is the one thing an update may move. A new field fails to compile until listed. */
+const FIXED_FIELDS: { readonly [K in FixedField]: (target: ZeropsNamespaceTarget) => ZeropsNamespaceTarget[K] } = {
+	proxySource: (target) => target.proxySource,
+	proxyBuild: (target) => target.proxyBuild,
+	proxyDeployment: (target) => target.proxyDeployment,
+	projectName: (target) => target.projectName,
+	corePackage: (target) => target.corePackage,
+	publicAccess: (target) => target.publicAccess,
+	managed: (target) => target.managed,
+	projectId: (target) => target.projectId,
+	proxyServiceId: (target) => target.proxyServiceId,
+	postgresServiceId: (target) => target.postgresServiceId,
+	proxyConfigured: (target) => target.proxyConfigured,
+	proxyBaselineSequence: (target) => target.proxyBaselineSequence,
+	proxyAppVersionId: (target) => target.proxyAppVersionId,
+	proxyHosts: (target) => target.proxyHosts,
+	ready: (target) => target.ready,
+}
+
+const immutable = (message: string) => namespaceError(PROVIDER_NAMESPACE_IMMUTABLE, message, false)
+
+/** The stored target with the requested payload's top-level fields laid over it, validated by the one codec. */
+const mergedTarget = (
+	namespace: ProviderDeploymentNamespace,
+	current: NormalizedZeropsNamespaceTarget,
+	requested: ProviderEnvelope,
+	options: ZeropsNamespaceOptions,
+): NormalizedZeropsNamespaceTarget => {
+	const payload = requested.payload
+	if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+		throw new Error('Zerops namespace update payload must be an object')
+	}
+	const checked = namespaceUpdatePayloadSchema.safeParse(payload)
+	if (!checked.success) {
+		const issue = checked.error.issues[0]
+		const path = issue?.path.join('.') ?? ''
+		if (issue?.code === 'unrecognized_keys') {
+			const field = [path, issue.keys[0] ?? ''].filter((part) => part !== '').join('.')
+			throw new Error(`Zerops namespace update field ${field} is not a namespace target field`)
+		}
+		throw new Error(`Zerops namespace update field ${path === '' ? 'payload' : path} is invalid`)
+	}
+	const stored = zeropsNamespaceTargetCodec.encode(current)
+	if (typeof stored !== 'object' || stored === null || Array.isArray(stored)) {
+		throw new Error('Zerops namespace target did not encode to an object')
+	}
+	return normalizeTarget({ ...namespace, target: { ...requested, payload: { ...stored, ...payload } } }, options)
+}
+
+/** Refuse every difference except the PostgreSQL profile, naming the fields. */
+const planUpdate = (
+	namespace: ProviderDeploymentNamespace,
+	requested: ProviderEnvelope,
+	options: ZeropsNamespaceOptions,
+): ProviderNamespaceUpdatePlan => {
+	const current = normalizeTarget(namespace, options)
+	const merged = mergedTarget(namespace, current, requested, options)
+	const changed = Object.entries(FIXED_FIELDS)
+		.filter(([, read]) => JSON.stringify(read(current)) !== JSON.stringify(read(merged)))
+		.map(([field]) => field)
+	if (changed.length > 0) {
+		throw immutable(`Zerops namespace ${namespace.id} cannot change ${changed.join(', ')} in place; only the PostgreSQL profile can`)
+	}
+	const was = current.postgres
+	const wanted = merged.postgres
+	const unchanged: ProviderNamespaceUpdatePlan = { namespace: { ...namespace, target: envelope(current) }, change: null }
+	// The merge starts from the stored target, so `wanted` is absent only when `was` is.
+	if (wanted === undefined) return unchanged
+	if (was === undefined) {
+		throw immutable(`Zerops namespace ${namespace.id} has no PostgreSQL service, and one cannot be added in place`)
+	}
+	if (was.type !== wanted.type) {
+		throw immutable(`Zerops namespace ${namespace.id} cannot change its PostgreSQL type from ${was.type} to ${wanted.type} in place`)
+	}
+	if (wanted.profile === was.profile) return unchanged
+	if (wanted.profile === undefined) {
+		throw immutable(`Zerops namespace ${namespace.id} cannot return its PostgreSQL service to the platform default profile in place`)
+	}
+	return {
+		namespace: { ...namespace, target: envelope({ ...current, postgres: wanted }) },
+		change: { field: 'postgres.profile', from: was.profile ?? null, to: wanted.profile },
+	}
+}
+
+const unconfirmed = (serviceId: string, profile: string, cause: unknown) =>
+	namespaceError(
+		PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED,
+		`Zerops PostgreSQL service ${serviceId} was asked to move to profile ${profile}, and the change is not confirmed`,
+		true,
+		cause instanceof Error ? cause.message : undefined,
+	)
+
+/** A platform refusal answered before anything was accepted; everything else once the PUT is sent is ambiguous. */
+const refusedOutright = (cause: unknown): boolean =>
+	cause instanceof ZeropsApiError && cause.status >= 400 && cause.status < 500 && cause.status !== 429
+
+const readBack = async (serviceId: string, profile: string, options: ZeropsNamespaceOptions, signal: AbortSignal): Promise<void> => {
+	const sleep = options.sleep ?? defaultSleep
+	for (let attempt = 0;; attempt += 1) {
+		if (signal.aborted) {
+			throw namespaceError(ZEROPS_NAMESPACE_CANCELLED, 'Zerops namespace update was cancelled', true)
+		}
+		const live = (await options.api.getService({ serviceId, signal })).autoscalingProfileId
+		if (live === profile) return
+		if (attempt >= READBACK_ATTEMPTS) {
+			throw new Error(`the service still reads ${live ?? 'no profile'}`)
+		}
+		await sleep(READBACK_INTERVAL_MS, signal)
+	}
+}
+
+const applyProfile = async (
+	current: NormalizedZeropsNamespaceTarget,
+	wanted: ZeropsNamespacePostgres,
+	profile: string,
+	unconfirmedProfile: string | undefined,
+	options: ZeropsNamespaceOptions,
+	signal: AbortSignal,
+): Promise<void> => {
+	const projectId = current.projectId
+	const serviceId = current.postgresServiceId
+	if (projectId === undefined || serviceId === undefined) {
+		throw new Error('Zerops namespace has no PostgreSQL service id')
+	}
+	const service = await options.api.getService({ serviceId, signal })
+	validateService(service, projectId, wanted.type, false, undefined, {
+		...(current.postgres?.profile === undefined ? {} : { declared: current.postgres.profile }),
+		changingTo: profile,
+		...(unconfirmedProfile === undefined ? {} : { unconfirmed: unconfirmedProfile }),
+	})
+	if (service.autoscalingProfileId !== profile) {
+		let process: ZeropsProcess | null
+		try {
+			process = await options.api.configureAutoscaling({ serviceId, autoscalingProfileId: profile, signal })
+		} catch (cause) {
+			if (refusedOutright(cause)) throw cause
+			throw unconfirmed(serviceId, profile, cause)
+		}
+		try {
+			if (process !== null && process.id !== '') {
+				await waitForProcess({
+					api: options.api,
+					processId: process.id,
+					sleep: options.sleep ?? defaultSleep,
+					signal,
+					label: 'the PostgreSQL autoscaling change',
+					intervalMs: PROCESS_POLL_INTERVAL_MS,
+					attempts: PROCESS_POLL_ATTEMPTS,
+				})
+			}
+		} catch (cause) {
+			throw unconfirmed(serviceId, profile, cause)
+		}
+	}
+	try {
+		await readBack(serviceId, profile, options, signal)
+	} catch (cause) {
+		throw unconfirmed(serviceId, profile, cause)
+	}
+}
+
+const applyUpdate = async (input: ProviderNamespaceUpdateInput, options: ZeropsNamespaceOptions): Promise<ProviderDeploymentNamespace> => {
+	const current = normalizeTarget(input.namespace, options)
+	if (!current.ready) {
+		throw new Error(`Zerops namespace ${input.namespace.id} is not ready`)
+	}
+	const plan = planUpdate(input.namespace, input.next.target, options)
+	const wanted = normalizeTarget(plan.namespace, options).postgres
+	// Checked even with no planned change: after an unconfirmed update, confirming the live service is
+	// what lets core return the namespace to ready.
+	if (wanted?.profile === undefined) return plan.namespace
+	const unconfirmedProfile = input.unconfirmed === undefined ? undefined : normalizeTarget(input.unconfirmed, options).postgres?.profile
+	await applyProfile(current, wanted, wanted.profile, unconfirmedProfile, options, input.signal)
+	return plan.namespace
+}
+
+/** Move a ready namespace's PostgreSQL service to another profile — the one field Zerops changes in place. */
+export const createZeropsNamespaceUpdates = (options: ZeropsNamespaceOptions): ProviderNamespaceUpdates => ({
+	plan: (namespace, requested) => planUpdate(namespace, requested, options),
+	apply: async (input) => {
+		try {
+			return await applyUpdate(input, options)
+		} catch (cause) {
+			throw asNamespaceError(cause, 'update')
+		}
+	},
+})

package/src/namespace/validation.ts

@@ -0,0 +1,43 @@
+import type { ZeropsService } from '../api'
+
+/**
+ * The profile a service is checked against. `declared` is what the stored target says. `changingTo` is
+ * set only while an update moves the service, and `unconfirmed` while it retries an earlier update whose
+ * outcome is unknown: a live service already on either reads as the change in progress, not as drift.
+ */
+export interface ZeropsExpectedProfile {
+	readonly declared?: string
+	readonly changingTo?: string
+	readonly unconfirmed?: string
+}
+
+export const validateService = (
+	service: ZeropsService,
+	projectId: string,
+	expectedBase: string,
+	adopting: boolean,
+	expectedPublic?: boolean,
+	expectedProfile: ZeropsExpectedProfile = {},
+): void => {
+	if (service.id === '') {
+		throw new Error(`Zerops namespace service \`${service.name}\` returned an empty id`)
+	}
+	if (service.projectId !== undefined && service.projectId !== projectId) {
+		throw new Error(`Zerops namespace service \`${service.name}\` belongs to another project`)
+	}
+	if ((adopting || service.base !== undefined) && service.base !== expectedBase) {
+		throw new Error(`Zerops namespace service \`${service.name}\` uses ${service.base ?? 'an unknown type'}, expected ${expectedBase}`)
+	}
+	if (expectedPublic !== undefined && adopting && service.subdomainAccess !== expectedPublic) {
+		throw new Error(`Zerops namespace service \`${service.name}\` has incompatible public access`)
+	}
+	const live = service.autoscalingProfileId
+	if (live !== undefined && (live === expectedProfile.changingTo || live === expectedProfile.unconfirmed)) {
+		return
+	}
+	if (expectedProfile.declared !== undefined && live !== expectedProfile.declared) {
+		throw new Error(
+			`Zerops namespace service \`${service.name}\` uses profile ${live ?? 'unknown'}, but its namespace declares ${expectedProfile.declared}`,
+		)
+	}
+}

package/src/plan.ts

@@ -3,6 +3,7 @@ import type { ZeropsRuntimeTarget } from './types'
 
 export type ZeropsStepKind =
 	| 'apply-import'
+	| 'verify-exposure'
 	| 'write-service-env'
 	| 'reserve-version'
 	| 'upload-source'
@@ -36,6 +37,11 @@ export const buildZeropsPlan = (manifest: FabrikaManifest, target: ZeropsRuntime
 		kind: 'apply-import',
 		description: `Apply the Zerops import for ${serviceHostnames.length} service(s): ${serviceHostnames.join(', ')}`,
 	})
+	steps.push({
+		id: 'verify-exposure',
+		kind: 'verify-exposure',
+		description: 'Read back that no service has subdomain access and every bucket is one the platform created private',
+	})
 	steps.push({ id: 'write-service-env', kind: 'write-service-env', description: 'Write the managed service variables' })
 	steps.push({ id: 'reserve-version', kind: 'reserve-version', description: 'Reserve a Zerops app version' })
 	steps.push({ id: 'upload-source', kind: 'upload-source', description: 'Upload the resolved repository snapshot' })

package/src/provider.ts

@@ -8,11 +8,13 @@
 // runs. Recovery never resumes a deploy (ADR-0044): a version reserved but never triggered is deleted, and
 // one whose build may have been requested is settled only by polling it.
 
+import { appEnvironmentId } from '@fabrika/auth-core'
 import {
 	type DeployStepResult,
 	followLeaseLoss,
 	isLeaseLoss,
 	type JsonValue,
+	type ProviderApprovedAccess,
 	ProviderInvocationAbort,
 	type ProviderManagedEnvironment,
 	type ProviderRunEvents,
@@ -31,15 +33,33 @@ import {
 } from './api'
 import { defaultZeropsCollaborators, type ZeropsCollaboratorFactory, type ZeropsCollaborators } from './collaborators'
 import { assertZeropsInvariants, renderYaml } from './compile'
+import { FABRIKA_CHECK_VERSION, PLATFORM_TYPESCRIPT_VERSION, renderLockedExecutionDescriptor } from './execution'
+import {
+	createdServices,
+	type ExposureFinding,
+	formatExposureFindings,
+	formatStorageProvenance,
+	isObjectStorageType,
+	parseStorageProvenance,
+	STORAGE_PROVENANCE_KEY,
+} from './exposure'
 import {
 	assertAuthoredManagedDocument,
 	assertAuthoredManagedInputs,
+	isFrameworkFamilyVariable,
 	type ManagedValues,
 	overlayRelease,
-	parseManagedValues,
+	parseManagedEnvironment,
 	SERVICE_MANAGED_KEYS,
 } from './managed-env'
-import { type FabrikaImportDocument, type FabrikaManifest, manifestServiceHostnames, verifyZeropsArtifactSourceDescriptor } from './manifest'
+import {
+	approvedSchemaOf,
+	type FabrikaImportDocument,
+	type FabrikaManifest,
+	lockedExecutionFor,
+	manifestServiceHostnames,
+	verifyZeropsArtifactSourceDescriptor,
+} from './manifest'
 import { buildZeropsPlan, resolveDeployHostname, type ZeropsStep } from './plan'
 import { allowedReferenceHosts, foreignReferenceHost } from './service-references'
 import { isZeropsUploadDestination } from './source'
@@ -59,6 +79,8 @@ export interface ZeropsDeployRun {
 	readonly managedEnvironment: ProviderManagedEnvironment
 	readonly target: ZeropsRuntimeTarget
 	readonly artifact: FabrikaManifest
+	/** Control's approved access for the environment (ADR-0050); the lock-down and the IAM schema come from it. */
+	readonly access?: ProviderApprovedAccess
 	readonly dryRun: boolean
 	readonly signal: AbortSignal
 	readonly events: ProviderRunEvents
@@ -241,6 +263,10 @@ const terminalFailure = (version: ZeropsAppVersion): string => {
  * just before the build request is sent; together they decide whether a failure may delete the version.
  */
 interface Attempt {
+	/** Hostname → id of every service this run's import created. */
+	created?: ReadonlyMap<string, string>
+	/** The provenance marker `write-service-env` writes, or null to remove a marker no bucket needs any more. */
+	storageProvenance?: string | null
 	appVersionId?: string
 	uploadUrl?: string
 	processId?: string
@@ -258,6 +284,8 @@ interface StepEnv {
 	dryRun: boolean
 	attempt: Attempt
 	managedValues: ManagedValues
+	/** The key of each job and webhook of the approved contract, by its variable (ADR-0022 "Principal kinds"). */
+	familyVariables: Readonly<Record<string, string>>
 	/** `await-version` gives up at this instant. */
 	deadlineMs: number
 }
@@ -409,15 +437,78 @@ const awaitVersion = async (env: StepEnv, appVersionId: string, processId: strin
 	}
 }
 
-/** Write the five service-level managed keys; `FABRIKA_RELEASE` is never a service variable (ADR-0044). */
+/**
+ * The exposure read-back (ADR-0043): before a version can activate, every declared service must read
+ * `subdomainAccess: false`, and every object-storage service must be one this import created or the provenance
+ * marker names. A refusal raises an Operations alert, best-effort, and fails the run before any version exists.
+ */
+const verifyExposure = async (env: StepEnv): Promise<void> => {
+	const { zerops, log, signal, run } = env
+	const { artifact, target } = run
+	if (env.dryRun) {
+		log('  [dry-run] would read back subdomain access and bucket provenance of every declared service')
+		return
+	}
+	const created = env.attempt.created ?? new Map<string, string>()
+	const buckets = artifact.target.importDocument.services.filter((service) => isObjectStorageType(service.type)).map((service) => service.hostname)
+	const records = buckets.length === 0 ? [] : await zerops.api.listServiceEnv({ serviceId: target.serviceId, signal })
+	const marker = records.find((record) => record.key === STORAGE_PROVENANCE_KEY)
+	const known = new Set([...parseStorageProvenance(marker?.content), ...(target.createdBuckets ?? [])])
+	const findings: ExposureFinding[] = []
+	const bucketIds: string[] = []
+	for (const hostname of manifestServiceHostnames(artifact)) {
+		assertRunning(signal)
+		const service = await zerops.api.findService({ projectId: target.projectId, hostname, signal })
+		if (service === null) {
+			findings.push({ hostname, reason: 'is absent after the import, so its exposure cannot be read back' })
+			continue
+		}
+		if (service.subdomainAccess !== false) {
+			findings.push({
+				hostname,
+				reason: service.subdomainAccess === true
+					? 'has a `.zerops.app` subdomain, which reaches it past the namespace proxy; disable it in Zerops'
+					: 'did not report its subdomain access',
+			})
+		}
+		if (!buckets.includes(hostname)) continue
+		if (created.get(hostname) === service.id || known.has(service.id)) {
+			bucketIds.push(service.id)
+		} else {
+			findings.push({ hostname, reason: 'is a bucket the platform did not create private (no provenance); create it through a Fabrika import' })
+		}
+	}
+	if (findings.length > 0) {
+		const dsn = env.managedValues.FABRIKA_OPERATIONS_DSN
+		if (dsn !== null) {
+			const alert = { appId: run.appId, env: run.env, release: env.managedValues.FABRIKA_RELEASE, findings }
+			await zerops.alertExposure({ dsn, alert, signal }).then(
+				() => log('  raised an Operations alert'),
+				() => log('  [warn] the Operations alert could not be sent'),
+			)
+		}
+		throw new Error(formatExposureFindings(findings))
+	}
+	env.attempt.storageProvenance = bucketIds.length > 0 ? formatStorageProvenance(bucketIds) : null
+	log(
+		`  ${manifestServiceHostnames(artifact).length} service(s) without subdomain access${
+			bucketIds.length === 0 ? '' : `; ${bucketIds.length} bucket(s) of platform provenance`
+		}`,
+	)
+}
+
+/** Write the nine service-level managed keys; `FABRIKA_RELEASE` is never a service variable (ADR-0044). */
 const writeServiceEnv = async (env: StepEnv): Promise<void> => {
-	const { zerops, log, signal, managedValues } = env
+	const { zerops, log, signal, managedValues, familyVariables } = env
 	const serviceId = env.run.target.serviceId
 	if (env.dryRun) {
-		const written = SERVICE_MANAGED_KEYS.filter((key) => managedValues[key] !== null)
+		const written = [...SERVICE_MANAGED_KEYS.filter((key) => managedValues[key] !== null), ...Object.keys(familyVariables)]
 		const removed = SERVICE_MANAGED_KEYS.filter((key) => managedValues[key] === null)
 		log(`  [dry-run] would write service variables on ${serviceId}: ${written.join(', ') || '(none)'}`)
 		log(`  [dry-run] would remove service variables on ${serviceId} if present: ${removed.join(', ') || '(none)'}`)
+		if (Object.keys(familyVariables).length > 0) {
+			log(`  [dry-run] would remove every other job, webhook and connector variable on ${serviceId}`)
+		}
 		return
 	}
 	assertRunning(signal)
@@ -437,6 +528,35 @@ const writeServiceEnv = async (env: StepEnv): Promise<void> => {
 			log(`  ${key}: unchanged`)
 		}
 	}
+	const provenance = env.attempt.storageProvenance
+	const marker = records.find((record) => record.key === STORAGE_PROVENANCE_KEY)
+	if (typeof provenance === 'string' && marker?.content !== provenance) {
+		assertRunning(signal)
+		await zerops.api.putServiceEnv({ serviceId, key: STORAGE_PROVENANCE_KEY, value: provenance, signal })
+		log(`  ${STORAGE_PROVENANCE_KEY}: updated`)
+	} else if (provenance === null && marker !== undefined) {
+		assertRunning(signal)
+		await zerops.api.deleteServiceEnv({ envId: marker.id, signal })
+		log(`  ${STORAGE_PROVENANCE_KEY}: removed`)
+	}
+	// A workload key is written like a managed key; one whose workload is gone is removed, so no stale key stays readable.
+	for (const [key, value] of Object.entries(familyVariables)) {
+		const existing = records.find((record) => record.key === key)
+		assertRunning(signal)
+		if (existing?.content !== value) {
+			await zerops.api.putServiceEnv({ serviceId, key, value, signal })
+			log(`  ${key}: updated`)
+		} else {
+			log(`  ${key}: unchanged`)
+		}
+	}
+	for (const record of records) {
+		if (isFrameworkFamilyVariable(record.key) && !Object.hasOwn(familyVariables, record.key)) {
+			assertRunning(signal)
+			await zerops.api.deleteServiceEnv({ envId: record.id, signal })
+			log(`  ${record.key}: removed`)
+		}
+	}
 }
 
 /** Run one step's effect. Resolves on success, throws on failure (caught + recorded by `runSteps`). */
@@ -458,6 +578,7 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 			// `override: true` on every service (written by the compiler) is what makes re-applying safe.
 			const result = await zerops.api.importServices({ projectId: target.projectId, yaml: compiled.yaml, signal })
 			log(`  imported: ${result.services.map((service) => `${service.name} (${service.id})`).join(', ') || '(none reported)'}`)
+			attempt.created = createdServices(result)
 			// An import ANSWERS before its services exist. Triggering a pipeline on a service Zerops is
 			// still creating answers 400 `projectImportInvalidParameter`, which is what the first deploy
 			// into a fresh namespace hit; a re-apply onto services that already exist reports none.
@@ -472,6 +593,11 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 			return
 		}
 
+		case 'verify-exposure': {
+			await verifyExposure(env)
+			return
+		}
+
 		case 'write-service-env': {
 			await writeServiceEnv(env)
 			return
@@ -529,13 +655,25 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 		}
 
 		case 'trigger-build': {
+			const locked = lockedExecutionFor(artifact, run, dryRun)
 			if (dryRun) {
-				log('  [dry-run] would trigger build+deploy with FABRIKA_RELEASE written into the execution descriptor')
+				log(
+					locked === null
+						? '  [dry-run] would trigger build+deploy with FABRIKA_RELEASE written into the execution descriptor'
+						: '  [dry-run] would trigger build+deploy with the generated run section and build checks',
+				)
 				return
 			}
 			const appVersionId = requireVersion(env, 'trigger-build')
 			await verifyZeropsArtifactSourceDescriptor(artifact.target.sourceDescriptor)
-			const descriptor = overlayRelease(artifact.target.sourceDescriptor.contents, artifact.target.zeropsSetup, env.managedValues.FABRIKA_RELEASE)
+			const { contents } = artifact.target.sourceDescriptor
+			const release = env.managedValues.FABRIKA_RELEASE
+			const descriptor = locked === null
+				? overlayRelease(contents, artifact.target.zeropsSetup, release)
+				: renderLockedExecutionDescriptor(contents, artifact.target.zeropsSetup, release, locked)
+			if (locked !== null) {
+				log(`  generated run section; build checks @fabrika/check@${FABRIKA_CHECK_VERSION}, typescript@${PLATFORM_TYPESCRIPT_VERSION}`)
+			}
 			assertRunning(signal)
 			// Recorded BEFORE the request: from here on the version is settled only by polling it (ADR-0044).
 			const checkpoint: ZeropsRunState = { appVersionId, triggered: true }
@@ -579,7 +717,7 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 		}
 
 		case 'reconcile-schema': {
-			const schema = artifact.app.schema
+			const schema = approvedSchemaOf(run)
 			const propustkaUrl = target.propustkaUrl
 			if (schema === undefined || propustkaUrl === undefined) {
 				return
@@ -587,17 +725,18 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 			// Return origins ride this step because `apps.setReturnOrigins` 404s for an app IAM has never
 			// heard of, and the schema reconcile is what registers it. Separate call, same moment.
 			const returnOrigins = run.returnOrigins !== undefined && run.returnOrigins.length > 0 ? run.returnOrigins : undefined
+			const iamApp = appEnvironmentId(artifact.app.id, artifact.app.env)
 			if (dryRun) {
-				log(`  [dry-run] would reconcile schema for \`${artifact.app.id}\` against ${propustkaUrl}`)
+				log(`  [dry-run] would reconcile schema for \`${iamApp}\` against ${propustkaUrl}`)
 				if (returnOrigins !== undefined) {
-					log(`  [dry-run] would register return origins for \`${artifact.app.id}\`: ${returnOrigins.join(', ')}`)
+					log(`  [dry-run] would register return origins for \`${iamApp}\`: ${returnOrigins.join(', ')}`)
 				}
 				return
 			}
 			assertRunning(signal)
 			await zerops.reconcileSchema({
 				url: propustkaUrl,
-				app: artifact.app.id,
+				app: iamApp,
 				schema,
 				...(returnOrigins === undefined ? {} : { returnOrigins }),
 				adminKey: target.adminKey,
@@ -626,7 +765,15 @@ async (run: ZeropsDeployRun): Promise<ZeropsDeployResult> => {
 		throw new Error(`zerops: artifact environment drift: expected \`${run.env}\`, got \`${run.artifact.app.env}\``)
 	}
 	assertAuthoredManagedInputs({ variableNames: Object.keys(run.vars), secretNames: Object.keys(run.secrets) })
-	const managedValues = parseManagedValues(run.managedEnvironment)
+	// The proxy serves an endpoint table exactly when Control approved a contract, whatever the artifact says.
+	const contractProxy = run.access !== undefined
+	const { values: handed, familyVariables } = parseManagedEnvironment(run.managedEnvironment)
+	// Only a contract application checks the secret; any other would merely hold a credential its own code can print.
+	const managedValues: ManagedValues = contractProxy ? handed : { ...handed, FABRIKA_PROXY_SECRET: null }
+	if (!run.dryRun && contractProxy && managedValues.FABRIKA_PROXY_SECRET === null) {
+		// The application would refuse every request its proxy sends (ADR-0022 rule 5).
+		throw new Error('zerops: a contract application needs its proxy secret, and Control supplied none')
+	}
 	const hostnames = manifestServiceHostnames(run.artifact)
 	const document = interpolateManifest(run.artifact.target.importDocument, run.artifact.app.pipeline.vars, run.vars, hostnames)
 	const compiled = { yaml: renderYaml(document), hostnames }
@@ -641,6 +788,7 @@ async (run: ZeropsDeployRun): Promise<ZeropsDeployResult> => {
 		dryRun: run.dryRun,
 		attempt: { triggered: false },
 		managedValues,
+		familyVariables,
 		deadlineMs: Date.now() + ZEROPS_VERSION_DEADLINE_MS,
 	}
 	const steps = buildZeropsPlan(run.artifact, run.target)

package/src/types.ts

@@ -1,5 +1,7 @@
-import type { AppGates } from '@fabrika/auth-core'
+import type { ContractArtifact } from '@fabrika/auth-core'
 import type { AppConfigBase } from '@fabrika/provider-contract'
+import type { ContractProxyApp } from '@fabrika/proxy-core/manifest'
+import type { ZeropsRuntimePackage } from './execution'
 import type {
 	ZeropsHealthCheck,
 	ZeropsImportProject,
@@ -82,9 +84,9 @@ export type ZeropsServiceSpec = Omit<ZeropsImportService, ZeropsCompilerOwnedSer
 
 export type ZeropsProjectSpec = Omit<ZeropsImportProject, ZeropsCompilerOwnedProjectField>
 
-export interface ZeropsProxySpec {
+/** What the namespace proxy applies to the app: the manifest form of its compiled contract, from `contractProxyTable`. */
+export interface ZeropsProxySpec extends Pick<ContractProxyApp, 'endpoints' | 'reservedPrefixes' | 'snapshot'> {
 	upstream: string
-	gates: AppGates
 }
 
 /**
@@ -107,6 +109,13 @@ export interface ZeropsSourceTarget {
 	zeropsSetup?: string
 	proxy?: ZeropsProxySpec
 	namespaceResources?: ZeropsNamespaceResourceRequirement[]
+	/**
+	 * The compiled contract of a contract application. Its presence locks the setup down (ADR-0043): the platform
+	 * generates the run section and the server build, and the authored `zerops.yaml` keeps only the SPA build.
+	 */
+	contract?: ContractArtifact
+	/** System packages for the runtime image of a contract application, from a closed list. */
+	runtimePackages?: ZeropsRuntimePackage[]
 	services: (ctx: ZeropsResourceContext) => ZeropsServiceSpec[]
 	project?: ZeropsProjectSpec
 }
@@ -134,6 +143,8 @@ export interface ZeropsRunState {
 export interface ZeropsRuntimeTarget {
 	projectId: string
 	serviceId: string
+	/** The buckets the environment's registration created, from its stored target (creation evidence, ADR-0043). */
+	createdBuckets?: readonly string[]
 	accessToken: string
 	/** Absent only for dry runs, which perform no source or Zerops mutation. */
 	source?: ZeropsRuntimeSource