@fabrika/provider-zerops 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.3.2",
+	"version": "0.4.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -43,11 +43,12 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth": "^0.3.2",
-		"@fabrika/auth-core": "^0.3.2",
-		"@fabrika/installation-init": "^0.3.2",
-		"@fabrika/provider-contract": "^0.3.2",
-		"@fabrika/proxy-core": "^0.3.2",
+		"@fabrika/auth": "^0.4.0",
+		"@fabrika/auth-core": "^0.4.0",
+		"@fabrika/iam-contract": "^0.4.0",
+		"@fabrika/installation-init": "^0.4.0",
+		"@fabrika/provider-contract": "^0.4.0",
+		"@fabrika/proxy-core": "^0.4.0",
 		"yaml": "^2.9.1"
 	}
 }

package/src/api/client.ts

@@ -35,7 +35,8 @@ const appVersionReservationSchema = z.object({
 	uploadUrl: z.string().refine((value) => value.trim() !== ''),
 	serviceStackId: z.string().refine((value) => value.trim() !== ''),
 })
-const triggerPipelineSchema = z.object({ process: processSchema.nullish() })
+/** `ResponseProcessNil`: a process, or none. */
+const processNilSchema = z.object({ process: processSchema.nullish() })
 const deleteAppVersionSchema = z.object({ success: z.literal(true) })
 
 // ── default (real) implementation ───────────────────────────────────────────────
@@ -282,7 +283,7 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 				body['zeropsSetup'] = zeropsSetup
 			}
 			const payload = await request('trigger-pipeline', 'PUT', `/service-stack/${serviceId}/trigger-pipeline`, { body, signal })
-			return readResponse('trigger-pipeline', triggerPipelineSchema, payload).process ?? null
+			return readResponse('trigger-pipeline', processNilSchema, payload).process ?? null
 		},
 
 		createAppVersion: async ({ serviceId, name, signal }) => {
@@ -352,6 +353,14 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 			await request('enable subdomain access', 'PUT', `/service-stack/${serviceId}/enable-subdomain-access`, { signal })
 		},
 
+		configureAutoscaling: async ({ serviceId, autoscalingProfileId, signal }) => {
+			const payload = await request('configure autoscaling', 'PUT', `/service-stack/${serviceId}/autoscaling`, {
+				body: { autoscalingProfileId },
+				signal,
+			})
+			return readResponse('configure autoscaling', processNilSchema, payload).process ?? null
+		},
+
 		getService: async ({ serviceId, signal }) =>
 			readResponse('get service', serviceSchema, await request('get service', 'GET', `/service-stack/${serviceId}`, { signal })),
 

package/src/api/types.ts

@@ -410,6 +410,19 @@ export interface ZeropsApi {
 	 */
 	enableSubdomainAccess(input: { serviceId: string; signal: AbortSignal }): Promise<void>
 
+	// ── service-stack: autoscaling ────────────────────────────────────────────────
+
+	/**
+	 * Move a managed service to another autoscaling profile. VERIFIED AS A SHAPE: `PUT
+	 * /service-stack/{id}/autoscaling` (`ConfigureAutoscaling`), body `RequestAutoscaling`, response
+	 * `ResponseProcessNil` — `null` when the platform hands back no process.
+	 *
+	 * The ONLY way to change a live profile: a re-import with a changed `profile` is silently ignored
+	 * (`docs/reference/zerops-platform.md`). UNVERIFIED: whether omitting `customAutoscaling` keeps or
+	 * resets custom overrides, and how soon `getService().autoscalingProfileId` reads the new value.
+	 */
+	configureAutoscaling(input: { serviceId: string; autoscalingProfileId: string; signal: AbortSignal }): Promise<ZeropsProcess | null>
+
 	// ── service-stack / project: reading state ────────────────────────────────────
 
 	/** One service by id. VERIFIED: `GET /service-stack/{id}`. */

package/src/cli.ts

@@ -8,6 +8,7 @@ import { parseZeropsCliArgs } from './cli-args'
 import {
 	compileFabrikaManifest,
 	createZeropsArtifactSourceDescriptor,
+	type FabrikaManifest,
 	manifestServiceHostnames,
 	ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES,
 } from './manifest'
@@ -69,6 +70,24 @@ export const readZeropsSourceDescriptor = async (root: string = process.cwd()) =
 	}
 }
 
+export interface ZeropsManifestBuildOptions {
+	/** App config path, resolved against the working directory like `--config`. */
+	readonly config: string
+	readonly env: string
+}
+
+const compileManifest = async (options: ZeropsManifestBuildOptions): Promise<FabrikaManifest> => {
+	const config = await loadConfig(options.config)
+	const sourceDescriptor = await readZeropsSourceDescriptor()
+	return compileFabrikaManifest(config, options.env, sourceDescriptor)
+}
+
+const serializeManifest = (manifest: FabrikaManifest): string => `${JSON.stringify(manifest, null, '\t')}\n`
+
+/** The exact text `build` writes to `fabrika.manifest.json`, produced in memory and written nowhere. */
+export const buildZeropsManifestText = async (options: ZeropsManifestBuildOptions): Promise<string> =>
+	serializeManifest(await compileManifest(options))
+
 export const runZeropsCli = async (argv: readonly string[]): Promise<void> => {
 	const args = parseZeropsCliArgs(argv)
 	if (args.help || args.command === undefined) {
@@ -81,11 +100,9 @@ export const runZeropsCli = async (argv: readonly string[]): Promise<void> => {
 	if (args.env === undefined || args.env === '') {
 		throw new Error('`build` requires --env=<env>')
 	}
-	const config = await loadConfig(args.config)
-	const sourceDescriptor = await readZeropsSourceDescriptor()
-	const manifest = compileFabrikaManifest(config, args.env, sourceDescriptor)
+	const manifest = await compileManifest({ config: args.config, env: args.env })
 	const output = resolve(process.cwd(), args.output)
-	await Bun.write(output, `${JSON.stringify(manifest, null, '\t')}\n`)
+	await Bun.write(output, serializeManifest(manifest))
 	console.info(`wrote ${output} (${manifestServiceHostnames(manifest).length} service(s))`)
 }
 

package/src/collaborators.ts

@@ -1,6 +1,7 @@
 import { reconcileSchema } from '@fabrika/auth'
 import type { SchemaReconciler } from '@fabrika/provider-contract'
 import { createZeropsApi, type ZeropsApi } from './api'
+import { type ExposureAlerter, sendExposureAlert } from './exposure'
 import type { ZeropsSourcePort } from './source/port'
 import type { ZeropsRuntimeTarget } from './types'
 
@@ -28,6 +29,8 @@ export interface ZeropsCollaborators {
 	/** Injected by the Zerops control composition; dry runs do not require it. */
 	source?: ZeropsSourcePort
 	reconcileSchema: SchemaReconciler
+	/** Raises the Operations alert for a refused activation; best-effort. */
+	alertExposure: ExposureAlerter
 	sleep: Sleeper
 }
 
@@ -46,5 +49,6 @@ const defaultReconcileSchema: SchemaReconciler = (input) =>
 export const defaultZeropsCollaborators: ZeropsCollaboratorFactory = (target) => ({
 	api: createZeropsApi({ token: target.accessToken, baseUrl: target.apiBaseUrl }),
 	reconcileSchema: defaultReconcileSchema,
+	alertExposure: sendExposureAlert,
 	sleep: defaultSleep,
 })

package/src/control.ts

@@ -1,3 +1,4 @@
+import { appEnvironmentId } from '@fabrika/auth-core'
 import type {
 	ControlProvider,
 	JsonValue,
@@ -21,8 +22,10 @@ import { decodeEnvelope, ProviderSecretError } from '@fabrika/provider-contract'
 import { z } from 'zod'
 import { createZeropsApi, waitForProcess, ZEROPS_ACTIVE, ZEROPS_TERMINAL, type ZeropsApi, type ZeropsAppVersion } from './api'
 import { defaultSleep, defaultZeropsCollaborators, type Sleeper } from './collaborators'
-import { assertAuthoredManagedInputs, assertAuthoredManagedName, parseManagedValues } from './managed-env'
+import { createdServices, type ExposureAlerter, isObjectStorageType } from './exposure'
+import { assertAuthoredManagedInputs, assertAuthoredManagedName, assertNoFrameworkReference, parseManagedEnvironment } from './managed-env'
 import {
+	approvedSchemaOf,
 	assertFabrikaManifestCoordinates,
 	type FabrikaManifest,
 	manifestServiceHostnames,
@@ -47,13 +50,21 @@ import { deleteVersion, isVersionNotFound } from './version-attempt'
 /** Provider coordinates that are safe to persist. Credentials are composed only for a live run. */
 export interface ZeropsStoredTarget {
 	serviceId: string
+	/**
+	 * The object-storage service ids the first registration's collision-refusing import created: the creation evidence
+	 * the first deploy writes into the provenance marker (ADR-0043). Absent when that import created no bucket.
+	 */
+	createdBuckets?: string[]
 }
 
-const storedTargetSchema = z.object({ serviceId: z.string().min(1) })
+const storedTargetSchema = z.object({ serviceId: z.string().min(1), createdBuckets: z.array(z.string().min(1)).min(1).optional() })
 
 export const zeropsStoredTargetCodec: ProviderCodec<ZeropsStoredTarget> = {
 	version: 2,
-	encode: (target) => ({ serviceId: target.serviceId }),
+	encode: (target) => ({
+		serviceId: target.serviceId,
+		...(target.createdBuckets === undefined ? {} : { createdBuckets: [...target.createdBuckets] }),
+	}),
 	decode: (payload) => {
 		const result = storedTargetSchema.safeParse(payload)
 		if (!result.success) throw new Error('Zerops stored target serviceId must be a non-empty string')
@@ -75,6 +86,7 @@ export interface ZeropsControlProviderOptions {
 	readonly api?: ZeropsApi
 	readonly source: ZeropsSourcePort
 	readonly reconcileSchema?: SchemaReconciler
+	readonly alertExposure?: ExposureAlerter
 	readonly sleep?: Sleeper
 	readonly namespaces?: {
 		readonly clientId: string
@@ -204,6 +216,7 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 			api,
 			source: options.source,
 			reconcileSchema: options.reconcileSchema ?? defaults.reconcileSchema,
+			alertExposure: options.alertExposure ?? defaults.alertExposure,
 			sleep: options.sleep ?? defaultSleep,
 		}
 	})
@@ -241,7 +254,8 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 		signal: AbortSignal,
 	): Promise<void> => {
 		const artifact = artifactFor(input.environment)
-		if (artifact.app.schema === undefined || options.propustkaUrl === undefined) return
+		const schema = approvedSchemaOf(input.environment)
+		if (schema === undefined || options.propustkaUrl === undefined) return
 		const placement = resolvedEnvironment(input.environment, { requireReady: false })
 		const runtimeTarget: ZeropsRuntimeTarget = {
 			projectId: placement.projectId,
@@ -255,8 +269,8 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 		signal.throwIfAborted()
 		await reconcileSchema({
 			url: options.propustkaUrl,
-			app: artifact.app.id,
-			schema: artifact.app.schema,
+			app: appEnvironmentId(artifact.app.id, artifact.app.env),
+			schema,
 			...(input.returnOrigins === undefined || input.returnOrigins.length === 0 ? {} : { returnOrigins: input.returnOrigins }),
 			adminKey: options.adminKey,
 			signal,
@@ -318,7 +332,8 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 		deploy: async (input: ProviderDeployInput): Promise<ProviderDeployOutcome> => {
 			input.signal.throwIfAborted()
 			assertAuthoredManagedInputs({ variableNames: Object.keys(input.vars), secretNames: Object.keys(input.secrets) })
-			const managedEnvironment = parseManagedValues(input.managedEnvironment)
+			const handed = parseManagedEnvironment(input.managedEnvironment)
+			const managedEnvironment = { ...handed.values, ...handed.familyVariables }
 			const binding = privateBinding(input.sourceBinding)
 			assertEnvironmentOfApp(input.app, input.environment)
 			const placement = resolvedEnvironment(input.environment, { requireReady: true })
@@ -340,6 +355,7 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 				projectId: placement.projectId,
 				serviceId: placement.target.serviceId,
 				accessToken: options.accessToken,
+				...(placement.target.createdBuckets === undefined ? {} : { createdBuckets: placement.target.createdBuckets }),
 				...(source === undefined ? {} : { source }),
 				...(options.apiBaseUrl !== undefined ? { apiBaseUrl: options.apiBaseUrl } : {}),
 				...(options.propustkaUrl !== undefined ? { propustkaUrl: options.propustkaUrl } : {}),
@@ -354,6 +370,7 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 				managedEnvironment,
 				target: runtimeTarget,
 				artifact,
+				...(input.environment.access === undefined ? {} : { access: input.environment.access }),
 				dryRun: input.dryRun,
 				signal: input.signal,
 				events: input.events,
@@ -438,6 +455,8 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 		secrets: {
 			put: async (input) => {
 				assertAuthoredManagedName(input.name)
+				assertNoFrameworkReference(input.name)
+				assertNoFrameworkReference(input.value)
 				assertOwnReferencesOnly(input.environment, input.name, input.value)
 				const target = decodeEnvironment(input.environment).target
 				await api.putServiceEnv({
@@ -510,11 +529,21 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 						if (discovered === null || discovered === undefined || discovered.id === '') {
 							throw new Error(`Zerops import did not create deploy service \`${manifest.target.deployService}\``)
 						}
+						// Only this collision-refusing import proves the platform created the buckets private (ADR-0043). The
+						// evidence is persisted with the registration, so no write can fail between it and the first deploy.
+						const created = present.length === 0 ? createdServices(imported) : new Map<string, string>()
+						const createdBuckets = manifest.target.importDocument.services.flatMap((service) => {
+							const id = isObjectStorageType(service.type) ? created.get(service.hostname) : undefined
+							return id === undefined ? [] : [id]
+						})
 						return normalizeRegistration({
 							app: input.registration.app,
 							environment: {
 								...input.registration.environment,
-								target: envelope(zeropsStoredTargetCodec, { serviceId: discovered.id }),
+								target: envelope(zeropsStoredTargetCodec, {
+									serviceId: discovered.id,
+									...(createdBuckets.length === 0 ? {} : { createdBuckets }),
+								}),
 							},
 						})
 					},

package/src/execution.ts

@@ -0,0 +1,371 @@
+// The execution descriptor of a CONTRACT application (ADR-0043): the platform, not the repository, decides what
+// runs. Of the authored setup only `build.base`, `build.os` and the SPA's `build.buildCommands` survive; the rest of
+// the build, the deploy gate and the whole `run` section are generated here. PURE — no network, no filesystem.
+
+import { type ContractArtifact, contractDigest, FABRIKA_CONTRACT_DIGEST, type FrameworkVariableName } from '@fabrika/auth-core'
+import type { JsonValue } from '@fabrika/provider-contract'
+import packageManifest from '../package.json'
+import { renderYaml } from './compile'
+import { parseZeropsDescriptor, type PreparedZeropsDescriptor, selectZeropsDescriptorSetup } from './descriptor'
+import { assertAuthoredManagedDocument } from './managed-env'
+
+/** The port the generated entrypoint listens on (`PORT`), and the one the proxy dials. */
+export const ZEROPS_APPLICATION_PORT = 3000
+
+/** The runtime every contract application runs on: the generated entrypoint is a Bun program. */
+export const ZEROPS_APPLICATION_RUNTIME = 'alpine/bun@1.3'
+
+/**
+ * The checker every build runs, pinned to this package's own version: the public packages are released together
+ * (`release:validate`), so this is the checker of the installation that renders the build.
+ */
+export const FABRIKA_CHECK_VERSION: string = packageManifest.version
+
+/** The compiler the platform type-checks with. It is fetched by version, never taken from the application's lockfile. */
+export const PLATFORM_TYPESCRIPT_VERSION = '5.9.3'
+
+/** System packages an application may add to its runtime image, installed by the generated `run.prepareCommands`. */
+export const ZEROPS_RUNTIME_PACKAGES = ['ffmpeg', 'ghostscript', 'imagemagick', 'poppler-utils', 'vips'] as const
+
+export type ZeropsRuntimePackage = (typeof ZEROPS_RUNTIME_PACKAGES)[number]
+
+export interface ZeropsContractJob {
+	readonly name: string
+	readonly schedule: string
+}
+
+/** The framework's file scan job (`@fabrika/app`'s `FILE_SCAN_JOB`), run every minute when a collection scans. */
+export const ZEROPS_FILE_SCAN_JOB = 'fabrika-file-scan'
+/** The framework's file sweep job (`@fabrika/app`'s `FILE_SWEEP_JOB` and its schedule), run when the contract has files. */
+export const ZEROPS_FILE_SWEEP_JOB = 'fabrika-file-sweep'
+const FILE_SWEEP_SCHEDULE = '41 * * * *'
+
+/**
+ * The RAM in GB a container of a scanning application starts with: one `clamscan` over a batch peaks at about 1 GB
+ * resident while it loads its signatures (measured with ClamAV 1.4), beside the application's own process.
+ */
+export const ZEROPS_SCAN_MIN_RAM_GB = 2
+
+/** What a scanning application adds: ClamAV in the image with its first signatures, refreshed at start and daily. */
+const SCANNER_PACKAGE = 'clamav'
+const FRESHCLAM = 'sudo freshclam --stdout --quiet'
+const FRESHCLAM_SCHEDULE = '17 4 * * *'
+
+/** What the generated run section needs from a contract; derived from the artifact by `zeropsContractRun`. */
+export interface ZeropsContractRun {
+	/** The contract digest the application compares at startup (`FABRIKA_CONTRACT_DIGEST`). */
+	readonly digest: string
+	/** The path of the contract's health endpoint, which the readiness and health checks request. */
+	readonly readinessPath: string
+	readonly jobs: readonly ZeropsContractJob[]
+	/** Present when the contract declares a file collection: the crontab runs the sweep of removed files. */
+	readonly files?: true
+	/** Present when a file collection scans its uploads: the build installs ClamAV and the crontab runs the scan. */
+	readonly scan?: true
+}
+
+/** Everything one locked execution descriptor is rendered from. */
+export interface ZeropsLockedExecution {
+	readonly appId: string
+	readonly contract: ZeropsContractRun
+	/** A `${host_…}` reference to the application's PostgreSQL service, or null when it has none. */
+	readonly databaseUrl: string | null
+	/** The hostname of the application's one object-storage service, or null when it has none. */
+	readonly storageHostname: string | null
+	readonly runtimePackages: readonly ZeropsRuntimePackage[]
+}
+
+/** The application ids the generated scripts may name: the contract's own id rule, so a script needs no quoting. */
+export const LOCKED_APP_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/
+
+export const CONTRACT_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/
+
+const byName = <T extends { readonly name: string }>(left: T, right: T): number => left.name < right.name ? -1 : left.name > right.name ? 1 : 0
+
+/** The run facts of a contract. A contract without a health endpoint has nothing a readiness check can request. */
+export function zeropsContractRun(artifact: ContractArtifact): ZeropsContractRun {
+	const health = artifact.endpoints.filter((row) => row.kind === 'health').sort((left, right) => left.id < right.id ? -1 : 1)[0]
+	if (health === undefined) {
+		throw new Error(
+			"fabrika app build: a contract application on Zerops needs a health endpoint for its readiness check (allowed form: health: c.health('/healthz'))",
+		)
+	}
+	return {
+		digest: contractDigest(artifact),
+		readinessPath: health.path,
+		jobs: Object.entries(artifact.jobs).map(([name, job]) => ({ name, schedule: job.schedule })).sort(byName),
+		...(Object.keys(artifact.files).length > 0 ? { files: true } : {}),
+		...(Object.values(artifact.files).some((collection) => collection.scan === true) ? { scan: true } : {}),
+	}
+}
+
+/**
+ * A scanning application's deploy service must start its containers with `ZEROPS_SCAN_MIN_RAM_GB`: below it the
+ * scanner is killed for memory, and every upload stays quarantined. Zerops ignores a changed `verticalAutoscaling` of
+ * an existing service on a re-import, so an existing service is raised through Zerops itself.
+ */
+export function assertScanMemory(services: readonly { readonly [key: string]: JsonValue }[], deployService: string, run: ZeropsContractRun): void {
+	if (run.scan !== true) return
+	const service = services.find((candidate) => candidate['hostname'] === deployService)
+	const scaling = service?.['verticalAutoscaling']
+	const minRam = isMapping(scaling) ? scaling['minRam'] : undefined
+	if (typeof minRam !== 'number' || minRam < ZEROPS_SCAN_MIN_RAM_GB) {
+		throw new Error(
+			`fabrika app build: a contract with scan: true scans uploads with ClamAV, which needs ${ZEROPS_SCAN_MIN_RAM_GB} GB of RAM; set verticalAutoscaling: { minRam: ${ZEROPS_SCAN_MIN_RAM_GB} } on the service \`${deployService}\``,
+		)
+	}
+}
+
+// ── Refusals ─────────────────────────────────────────────────────────────────────────────────────
+
+const LOCKED_BUILD_FORM = 'only `build.base`, `build.os` and the SPA commands in `build.buildCommands`'
+
+const RUN_REASON = 'the platform generates the run section: the entrypoint, `fabrika db migrate`, the readiness check and the crontab'
+
+/** Every key the authored selected setup may not carry, with why. Any key not listed and not authorable is refused too. */
+const REFUSED_KEYS: Readonly<Record<string, string>> = {
+	extends: 'an inherited setup brings keys the platform generates',
+	deploy: 'the platform generates the deploy gate',
+	'deploy.temporaryShutdown': 'the platform decides how a version replaces the running one',
+	'deploy.readinessCheck': 'the platform generates the readiness check against the contract health endpoint',
+	'build.addToRunPrepare': 'a file copied into the runtime image skips the build checks',
+	'build.deployFiles': 'the platform deploys the checked build',
+	'build.deploy': 'the platform deploys the checked build',
+	'build.prepareCommands': 'a build-image command runs before the checks and outside them',
+	'build.cache': 'a cached path survives into the next build unchecked',
+	'build.envVariables': 'a build variable can redirect the generated checks',
+}
+
+const AUTHORED_SETUP_KEYS: ReadonlySet<string> = new Set(['setup', 'build'])
+const AUTHORED_BUILD_KEYS: ReadonlySet<string> = new Set(['base', 'os', 'buildCommands'])
+
+const isMapping = (value: JsonValue | undefined): value is { readonly [key: string]: JsonValue } =>
+	typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const isStringList = (value: JsonValue): value is string[] => Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+
+const refuse = (setup: string, key: string, reason: string): never => {
+	throw new Error(`invalid fabrika manifest: zerops.yaml setup \`${setup}\` sets \`${key}\`; ${reason} (allowed form: ${LOCKED_BUILD_FORM})`)
+}
+
+interface AuthoredBuild {
+	readonly base: string | string[] | null
+	readonly os: string | null
+	readonly commands: string[]
+}
+
+/** Refuse every key of a contract application's setup the platform owns, and return what it keeps. */
+export function lockedAuthoredBuild(entry: { readonly [key: string]: JsonValue }, setup: string): AuthoredBuild {
+	for (const key of Object.keys(entry)) {
+		if (key === 'run') {
+			const run = entry[key]
+			const first = isMapping(run) ? Object.keys(run)[0] : undefined
+			refuse(setup, first === undefined ? 'run' : `run.${first}`, RUN_REASON)
+		}
+		if (key === 'deploy') {
+			const deploy = entry[key]
+			const first = isMapping(deploy) ? Object.keys(deploy)[0] : undefined
+			const path = first === undefined ? 'deploy' : `deploy.${first}`
+			refuse(setup, path, REFUSED_KEYS[path] ?? REFUSED_KEYS['deploy'] ?? '')
+		}
+		if (!AUTHORED_SETUP_KEYS.has(key)) refuse(setup, key, REFUSED_KEYS[key] ?? 'the platform generates every other setup key')
+	}
+	const build = entry['build']
+	if (build === undefined) return { base: null, os: null, commands: [] }
+	if (!isMapping(build)) return refuse(setup, 'build', 'a build is a mapping')
+	for (const key of Object.keys(build)) {
+		if (!AUTHORED_BUILD_KEYS.has(key)) refuse(setup, `build.${key}`, REFUSED_KEYS[`build.${key}`] ?? 'the platform generates every other build key')
+	}
+	const base = build['base']
+	const os = build['os']
+	const commands = build['buildCommands']
+	if (base !== undefined && typeof base !== 'string' && !isStringList(base)) refuse(setup, 'build.base', 'a base is a name or a list of names')
+	if (os !== undefined && typeof os !== 'string') refuse(setup, 'build.os', 'an os is a name')
+	if (commands !== undefined && !isStringList(commands)) refuse(setup, 'build.buildCommands', 'build commands are a list of strings')
+	return {
+		base: typeof base === 'string' || (base !== undefined && isStringList(base)) ? base : null,
+		os: typeof os === 'string' ? os : null,
+		commands: commands !== undefined && isStringList(commands) ? commands : [],
+	}
+}
+
+// ── Generation ───────────────────────────────────────────────────────────────────────────────────
+
+const SOURCE_ROOT = '/build/source'
+const RUNTIME_ROOT = '/var/www'
+const FABRIKA_BIN = './node_modules/.bin/fabrika'
+const MIGRATE_SCRIPT = 'fabrika/migrate.generated.sh'
+const START_SCRIPT = 'fabrika/start.generated.sh'
+const PLATFORM_TSCONFIG = 'fabrika/tsconfig.platform.json'
+
+/** The compiler options of the platform's type check; the application's own `tsconfig.json` and its `paths` are not read. */
+const PLATFORM_TSCONFIG_CONTENTS = JSON.stringify({
+	compilerOptions: {
+		target: 'ES2022',
+		module: 'ESNext',
+		moduleResolution: 'bundler',
+		lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+		types: ['bun'],
+		strict: true,
+		noUncheckedIndexedAccess: true,
+		noImplicitOverride: true,
+		forceConsistentCasingInFileNames: true,
+		skipLibCheck: true,
+		resolveJsonModule: true,
+		isolatedModules: true,
+		noEmit: true,
+	},
+	include: ['../fabrika.contract.ts', '../src', 'entry.generated.ts'],
+})
+
+/** One `printf` writing `lines` to `path`. Each line is single-quoted, so it may hold neither `'` nor an expansion. */
+const writeFileCommand = (path: string, lines: readonly string[]): string => {
+	for (const line of lines) {
+		if (line.includes("'") || line.includes('$')) throw new Error('zerops: a generated file line must not contain a quote or an expansion')
+	}
+	return `printf '%s\\n' ${lines.map((line) => `'${line}'`).join(' ')} > ${path}`
+}
+
+const migrateScript = (appId: string): readonly string[] => [
+	'#!/bin/sh',
+	'set -eu',
+	`cd ${RUNTIME_ROOT}`,
+	`FABRIKA_APP_ID=${appId} exec ${FABRIKA_BIN} db migrate`,
+]
+
+// The server starts only after the migrations it expects are applied, the committed schema types match the migrated
+// schema and every generated isolation test passed on a throwaway schema, so any failure fails the readiness check,
+// whether or not a failed `initCommands` stops the activation (an unverified platform fact). The build has no
+// database, so this is where the types and the generated tests run.
+const startScript = (appId: string, database: boolean): readonly string[] => [
+	'#!/bin/sh',
+	'set -eu',
+	`cd ${RUNTIME_ROOT}`,
+	...(database
+		? [
+			`sh ${RUNTIME_ROOT}/${MIGRATE_SCRIPT}`,
+			`FABRIKA_APP_ID=${appId} ${FABRIKA_BIN} db codegen --verify`,
+			`FABRIKA_APP_ID=${appId} ${FABRIKA_BIN} db test-isolation`,
+		]
+		: []),
+	'exec bun fabrika/entry.generated.ts',
+]
+
+const INSTALL = 'bun install --frozen-lockfile --ignore-scripts'
+
+/**
+ * The generated build commands, in order; the authored SPA commands run before all of them. The application's tests
+ * run first: they are authored code, so everything after them is reinstalled, regenerated or checked again.
+ */
+export function generatedBuildCommands(execution: ZeropsLockedExecution): readonly string[] {
+	if (!LOCKED_APP_ID_PATTERN.test(execution.appId)) throw new Error('zerops: a contract application id must match [a-z0-9][a-z0-9-]*')
+	const database = execution.databaseUrl !== null
+	return [
+		INSTALL,
+		'bun test --pass-with-no-tests',
+		`rm -rf node_modules && ${INSTALL}`,
+		`bun -e "await import('@fabrika/app/build').then((build) => build.writeGeneratedEntry('.', 'bun'))"`,
+		`cd /tmp && bun x --bun -p @fabrika/check@${FABRIKA_CHECK_VERSION} fabrika-check ${SOURCE_ROOT}`,
+		writeFileCommand(PLATFORM_TSCONFIG, [PLATFORM_TSCONFIG_CONTENTS]),
+		`cd /tmp && bun x --bun -p typescript@${PLATFORM_TYPESCRIPT_VERSION} tsc -p ${SOURCE_ROOT}/${PLATFORM_TSCONFIG}`,
+		...(database ? [writeFileCommand(MIGRATE_SCRIPT, migrateScript(execution.appId))] : []),
+		writeFileCommand(START_SCRIPT, startScript(execution.appId, database)),
+	]
+}
+
+const sortedUnique = (values: readonly string[]): string[] => [...new Set(values)].sort()
+
+type StorageVariable = Extract<FrameworkVariableName, `FABRIKA_APP_STORAGE_${string}`>
+
+/** The file collections' object storage, as references Zerops resolves at runtime: no credential passes through Fabrika. */
+const storageVariables = (hostname: string): Record<StorageVariable, string> => ({
+	FABRIKA_APP_STORAGE_ENDPOINT: `\${${hostname}_apiUrl}`,
+	FABRIKA_APP_STORAGE_BUCKET: `\${${hostname}_bucketName}`,
+	FABRIKA_APP_STORAGE_ACCESS_KEY_ID: `\${${hostname}_accessKeyId}`,
+	FABRIKA_APP_STORAGE_SECRET_ACCESS_KEY: `\${${hostname}_secretAccessKey}`,
+})
+
+/** The generated selected setup: the authored build kept, everything else the platform's. */
+export function renderLockedSetup(
+	setup: string,
+	authored: AuthoredBuild,
+	release: string | null,
+	execution: ZeropsLockedExecution,
+): { readonly [key: string]: JsonValue } {
+	const { contract } = execution
+	if (!CONTRACT_DIGEST_PATTERN.test(contract.digest)) throw new Error('zerops: a contract digest must be sha256:<64 hex digits>')
+	const probe = { port: ZEROPS_APPLICATION_PORT, path: contract.readinessPath }
+	const envVariables: Record<string, string> = {
+		PORT: String(ZEROPS_APPLICATION_PORT),
+		[FABRIKA_CONTRACT_DIGEST]: contract.digest,
+		...(release === null ? {} : { FABRIKA_RELEASE: release }),
+		...(execution.databaseUrl === null ? {} : { FABRIKA_APP_DATABASE_URL: execution.databaseUrl }),
+		...(execution.storageHostname === null ? {} : storageVariables(execution.storageHostname)),
+	}
+	const scan = contract.scan === true
+	const packages = sortedUnique([...execution.runtimePackages, ...(scan ? [SCANNER_PACKAGE] : [])])
+	const crontab = [
+		...contract.jobs.map((job) => ({ timing: job.schedule, command: `${FABRIKA_BIN} job run ${job.name}`, allContainers: false })),
+		...(contract.files === true
+			? [{ timing: FILE_SWEEP_SCHEDULE, command: `${FABRIKA_BIN} job run ${ZEROPS_FILE_SWEEP_JOB}`, allContainers: false }]
+			: []),
+		// Every container keeps its own signatures; one scan pass at a time holds the job's lease.
+		...(scan
+			? [
+				{ timing: '* * * * *', command: `${FABRIKA_BIN} job run ${ZEROPS_FILE_SCAN_JOB}`, allContainers: false },
+				{ timing: FRESHCLAM_SCHEDULE, command: FRESHCLAM, allContainers: true },
+			]
+			: []),
+	]
+	// A container starts from the prepared image, whose signatures are as old as its build; a failed refresh leaves
+	// them to the daily one, and the scanner refuses signatures older than three days, so the scan fails closed.
+	const initCommands = [
+		...(scan ? [`${FRESHCLAM} || echo 'fabrika: freshclam did not refresh the malware signatures'`] : []),
+		...(execution.databaseUrl === null ? [] : [`sh ${RUNTIME_ROOT}/${MIGRATE_SCRIPT}`]),
+	]
+	const prepareCommands = packages.length === 0 ? [] : [`sudo apk add --no-cache ${packages.join(' ')}`, ...(scan ? [FRESHCLAM] : [])]
+	return {
+		setup,
+		build: {
+			base: authored.base ?? [ZEROPS_APPLICATION_RUNTIME],
+			...(authored.os === null ? {} : { os: authored.os }),
+			buildCommands: [...authored.commands, ...generatedBuildCommands(execution)],
+			deployFiles: ['./'],
+			cache: ['node_modules'],
+		},
+		deploy: {
+			readinessCheck: { httpGet: probe, retryPeriod: '10s', failureTimeout: '180s' },
+		},
+		run: {
+			base: ZEROPS_APPLICATION_RUNTIME,
+			...(prepareCommands.length === 0 ? {} : { prepareCommands }),
+			...(initCommands.length === 0 ? {} : { initCommands }),
+			start: `sh ${RUNTIME_ROOT}/${START_SCRIPT}`,
+			ports: [{ port: ZEROPS_APPLICATION_PORT, httpSupport: true }],
+			healthCheck: { httpGet: probe, execPeriod: '10s', disconnectTimeout: '30s', recoveryTimeout: '10s', failureTimeout: '120s' },
+			...(crontab.length === 0 ? {} : { crontab }),
+			envVariables,
+		},
+	}
+}
+
+/**
+ * The execution descriptor of a contract application: only the selected setup, generated. The source descriptor's
+ * bytes and digest stay the artifact's identity; this document is what the build request carries.
+ */
+export function renderLockedExecutionDescriptor(
+	contents: string,
+	setup: string | undefined,
+	release: string | null,
+	execution: ZeropsLockedExecution,
+): PreparedZeropsDescriptor {
+	if (release?.includes('${') === true) throw new Error('zerops: a release name must not contain `${`')
+	const parsed = parseZeropsDescriptor(contents)
+	assertAuthoredManagedDocument(parsed.document)
+	const selected = selectZeropsDescriptorSetup(parsed, setup)
+	const entries = parsed.document['zerops']
+	const entry = Array.isArray(entries) ? entries.find((candidate) => isMapping(candidate) && candidate['setup'] === selected) : undefined
+	if (!isMapping(entry)) throw new Error('zerops: descriptor requires setup entries')
+	const authored = lockedAuthoredBuild(entry, selected)
+	return { contents: renderYaml({ zerops: [renderLockedSetup(selected, authored, release, execution)] }), setup: selected }
+}