@fabrika/provider-zerops 0.8.0 → 0.9.0-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.8.0",
+	"version": "0.9.0-dev.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -43,14 +43,14 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth": "0.8.0",
-		"@fabrika/auth-core": "0.8.0",
-		"@fabrika/email": "0.8.0",
-		"@fabrika/iam-contract": "0.8.0",
-		"@fabrika/installation-init": "0.8.0",
-		"@fabrika/operations-contract": "0.8.0",
-		"@fabrika/provider-contract": "0.8.0",
-		"@fabrika/proxy-core": "0.8.0",
+		"@fabrika/auth": "0.9.0-dev.1",
+		"@fabrika/auth-core": "0.9.0-dev.1",
+		"@fabrika/email": "0.9.0-dev.1",
+		"@fabrika/iam-contract": "0.9.0-dev.1",
+		"@fabrika/installation-init": "0.9.0-dev.1",
+		"@fabrika/operations-contract": "0.9.0-dev.1",
+		"@fabrika/provider-contract": "0.9.0-dev.1",
+		"@fabrika/proxy-core": "0.9.0-dev.1",
 		"yaml": "^2.9.1"
 	}
 }

package/src/api/client.ts

@@ -346,6 +346,12 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 			await request('enable subdomain access', 'PUT', `/service-stack/${serviceId}/enable-subdomain-access`, { signal })
 		},
 
+		startService: async ({ serviceId, signal }) =>
+			readResponse('start service', processSchema, await request('start service', 'PUT', `/service-stack/${serviceId}/start`, { signal })),
+
+		stopService: async ({ serviceId, signal }) =>
+			readResponse('stop service', processSchema, await request('stop service', 'PUT', `/service-stack/${serviceId}/stop`, { signal })),
+
 		configureAutoscaling: async ({ serviceId, autoscalingProfileId, signal }) => {
 			const payload = await request('configure autoscaling', 'PUT', `/service-stack/${serviceId}/autoscaling`, {
 				body: { autoscalingProfileId },

package/src/api/types.ts

@@ -472,6 +472,18 @@ export interface ZeropsApi {
 	 */
 	enableSubdomainAccess(input: { serviceId: string; signal: AbortSignal }): Promise<void>
 
+	// ── service-stack: running state ──────────────────────────────────────────────
+
+	/**
+	 * Start a stopped service. VERIFIED AS A SHAPE: `PUT /service-stack/{id}/start` (`StartServiceStack`), no body,
+	 * `ResponseProcess`. Measured 2026-10-21: a stopped Bun service served again about 9 s after the call. Files written
+	 * at runtime survive a stop and a start; a deploy replaces the container and loses them.
+	 */
+	startService(input: { serviceId: string; signal: AbortSignal }): Promise<ZeropsProcess>
+
+	/** Stop a service. VERIFIED AS A SHAPE: `PUT /service-stack/{id}/stop` (`StopServiceStack`), no body, `ResponseProcess`. */
+	stopService(input: { serviceId: string; signal: AbortSignal }): Promise<ZeropsProcess>
+
 	// ── service-stack: autoscaling ────────────────────────────────────────────────
 
 	/**

package/src/control.ts

@@ -8,6 +8,7 @@ import type {
 	ProviderDeployInput,
 	ProviderDeploymentNamespace,
 	ProviderDeployOutcome,
+	ProviderDevEnvironmentInput,
 	ProviderEnvelope,
 	ProviderEnvironment,
 	ProviderReconcileOutcome,
@@ -322,6 +323,26 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 		return { commitSha: result.commitSha }
 	}
 
+	/** Stop or start the service of a `dev` environment outside a run, and wait for the platform's process. */
+	const runningState = async (input: ProviderDevEnvironmentInput, action: 'start' | 'stop'): Promise<void> => {
+		if (input.environment.kind !== 'dev') throw new Error('zerops: only a dev environment is stopped and started outside a run')
+		const placement = resolvedEnvironment(input.environment, { requireReady: false })
+		const serviceId = placement.target.serviceId
+		// Idempotent: Control's record of a stopped service can lag behind a start from elsewhere.
+		const status = (await api.getService({ serviceId, signal: input.signal })).status
+		if (status === (action === 'stop' ? 'STOPPED' : 'ACTIVE')) return
+		const process = action === 'stop'
+			? await api.stopService({ serviceId, signal: input.signal })
+			: await api.startService({ serviceId, signal: input.signal })
+		await waitForProcess({
+			api,
+			processId: process.id,
+			sleep: options.sleep ?? defaultSleep,
+			signal: input.signal,
+			label: `the ${action} of ${input.environment.appId}/${input.environment.env}`,
+		})
+	}
+
 	const controlProvider: ControlProvider = {
 		id: 'zerops',
 		normalizeRegistration,
@@ -380,6 +401,7 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 			const result = await deployRun({
 				appId: input.app.id,
 				env: input.environment.env,
+				...(input.environment.kind === 'dev' && source !== undefined ? { dev: { head: source.commitSha } } : {}),
 				...(input.returnOrigins === undefined ? {} : { returnOrigins: input.returnOrigins }),
 				secrets: input.secrets,
 				vars: input.vars,
@@ -395,6 +417,10 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 			input.signal.throwIfAborted()
 			return { state: result.status, ...(result.artifactState === undefined ? {} : { artifactState: result.artifactState }) }
 		},
+		devEnvironments: {
+			stop: (input) => runningState(input, 'stop'),
+			start: (input) => runningState(input, 'start'),
+		},
 		cancel: async (input): Promise<ProviderCancelOutcome> => {
 			const signal = input.signal
 			signal.throwIfAborted()

package/src/database-budget.ts

@@ -15,7 +15,7 @@ export const ZEROPS_POSTGRES_MIN_RAM_GB = 0.25
 export const ZEROPS_POSTGRES_UNAVAILABLE_CONNECTIONS = 7
 
 /**
- * The most connections one container's start script holds at once: `fabrika db test-isolation` peaks at 4 since the
+ * The most connections one container's init commands hold at once: `fabrika db test-isolation` peaks at 4 since the
  * test kit opens a file's connections together, and at 5 with a `@fabrika/db` before that (measured locally,
  * 2026-10-16, with the Notes and CRM examples). Migrating and reading the schema take fewer, one after the other.
  */
@@ -53,7 +53,7 @@ export function zeropsPostgresMaxConnections(ramGB: number, profile: string | un
 const poolHolders = (demand: ZeropsDatabaseDemand): number => 2 * demand.maxContainers + demand.jobs
 
 /**
- * The connections each process may open so that all of them, with one container's start script, stay within what the
+ * The connections each process may open so that all of them, with one container's init commands, stay within what the
  * application's roles can take; `null` when that is below `MIN_PROCESS_CONNECTIONS`.
  */
 export function zeropsProcessConnections(maxConnections: number, demand: ZeropsDatabaseDemand): number | null {

package/src/execution.ts

@@ -4,6 +4,10 @@
 
 import {
 	type ContractArtifact,
+	DEV_LAUNCHER_CONFIG_FILE,
+	DEV_LAUNCHER_MODULE,
+	DEV_LAUNCHER_STATE_FILE,
+	type DevLauncherConfig,
 	FABRIKA_CONTRACT_DIGEST,
 	FABRIKA_SOURCE_MAP_UPLOAD,
 	FABRIKA_SOURCE_MAP_UPLOAD_KEY,
@@ -55,7 +59,7 @@ const FILE_SWEEP_SCHEDULE = '41 * * * *'
 export const ZEROPS_SCAN_MIN_RAM_GB = 2
 
 /**
- * The RAM in GB a container of an application with a database starts with. Its start script runs `fabrika db
+ * The RAM in GB a container of an application with a database starts with. Its init commands run `fabrika db
  * test-isolation`, whose CLI and `bun test` child together peak at 161 MiB of anonymous memory for the Notes example
  * and 225 MiB for the CRM example (measured locally, 2026-10-15), beside Bun's own mapped binary. Zerops' 0.125 GB
  * floor kills that within a second, faster than vertical autoscaling reacts.
@@ -107,6 +111,16 @@ export interface ZeropsLockedExecution {
 	readonly runtimePackages: readonly ZeropsRuntimePackage[]
 	/** Where the build uploads its source maps, without the bearer; null when Control minted no upload for the run. */
 	readonly sourceMaps: OperationsSourceMapBuildUpload | null
+	/**
+	 * Present for an environment of kind `dev` (ADR-0049): `run.start` runs the dev launcher instead of the serving
+	 * entry. The environment's kind selects it; an application never authors it.
+	 */
+	readonly dev?: ZeropsDevExecution
+}
+
+export interface ZeropsDevExecution {
+	/** The commit the bootstrap run builds: what a new container holds before the launcher's first sync. */
+	readonly head: string
 }
 
 /** The application ids the generated scripts may name: the contract's own id rule, so a script needs no quoting. */
@@ -114,6 +128,9 @@ export const LOCKED_APP_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/
 
 export const CONTRACT_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/
 
+/** A literal path of unreserved characters: it is written into the generated probes unquoted by any shell. */
+export const READINESS_PATH_PATTERN = /^(?:\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)+$/
+
 const byName = <T extends { readonly name: string }>(left: T, right: T): number => left.name < right.name ? -1 : left.name > right.name ? 1 : 0
 
 /**
@@ -243,7 +260,9 @@ 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 VERIFY_SCRIPT = 'fabrika/verify.generated.sh'
 const START_SCRIPT = 'fabrika/start.generated.sh'
+const DEV_INIT_SCRIPT = 'fabrika/dev-init.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. */
@@ -281,24 +300,98 @@ const migrateScript = (appId: string): readonly string[] => [
 	`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 (it does, verified live). The build has no
-// database, so this is where the types and the generated tests run.
-const startScript = (appId: string, database: boolean): readonly string[] => [
+// The committed schema types must match the migrated schema and every generated isolation test must pass on a throwaway
+// schema. The build has no database, so they run at container start, after the migrations, as init commands: a failed
+// init command stops the activation, and the readiness window opens only with `run.start`, after the init commands (both
+// verified live), so a run as long as the CRM's ~3 minutes of generated cases does not race it.
+const verifyScript = (appId: string): 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',
+	`FABRIKA_APP_ID=${appId} ${FABRIKA_BIN} db codegen --verify`,
+	`FABRIKA_APP_ID=${appId} exec ${FABRIKA_BIN} db test-isolation`,
 ]
 
+// The readiness check is retried no sooner than every 10 s (the platform's floor), and a server is rarely listening at
+// the first attempt, one second after `run.start`. So one attempt waits for the health endpoint itself, for less than
+// the retry period; it passes only on a 2xx, like the `httpGet` it replaces.
+const readinessCommand = (path: string): string => {
+	if (!READINESS_PATH_PATTERN.test(path)) throw new Error('zerops: a readiness path must be a literal path of unreserved characters')
+	const url = `http://127.0.0.1:${ZEROPS_APPLICATION_PORT}${path}`
+	return `bun -e "const end = Date.now() + 9000; while (Date.now() < end) { try { if ((await fetch('${url}', { signal: AbortSignal.timeout(2000) })).ok) process.exit(0) } catch {} await Bun.sleep(200) } process.exit(1)"`
+}
+
+const SERVE_ENTRY = 'fabrika/entry.generated.ts'
+
+const startScript: readonly string[] = ['#!/bin/sh', 'set -eu', `cd ${RUNTIME_ROOT}`, `exec bun ${SERVE_ENTRY}`]
+
+// A dev environment starts the launcher of the application's own framework release, which runs the serving entry as its
+// child. Double quotes inside: a generated file line may hold no single quote.
+const devStartScript: readonly string[] = [
+	'#!/bin/sh',
+	'set -eu',
+	`cd ${RUNTIME_ROOT}`,
+	`exec bun -e "await import(\\"${DEV_LAUNCHER_MODULE}\\").then((dev) => dev.runDevLauncher(process.env))"`,
+]
+
+// The init commands of a dev container migrate and verify only what the bootstrap run built. A container that restarts
+// after a stop keeps the files the launcher synced since, and its state file: the launcher reconciles that one itself.
+const devInitScript: readonly string[] = [
+	'#!/bin/sh',
+	'set -eu',
+	`cd ${RUNTIME_ROOT}`,
+	`if [ -f ${DEV_LAUNCHER_STATE_FILE} ]; then exit 0; fi`,
+	`sh ${RUNTIME_ROOT}/${MIGRATE_SCRIPT}`,
+	`sh ${RUNTIME_ROOT}/${VERIFY_SCRIPT}`,
+]
+
+/** One command writing `content` to `path` through base64: the content may hold quotes and expansions, the command none. */
+const writeBase64Command = (path: string, content: string): string => {
+	const encoded = btoa(String.fromCharCode(...new TextEncoder().encode(content)))
+	return `printf '%s' '${encoded}' | base64 -d > ${path}`
+}
+
+/** The build's check chain as the dev launcher runs it in the application root, on what the container holds. */
+const devChecks = (release: string): DevLauncherConfig['checks'] => [
+	{ name: 'tests', command: 'bun test --isolate --pass-with-no-tests' },
+	{ name: 'fabrika-check', command: `cd /tmp && bun x --bun -p @fabrika/check@${release} fabrika-check ${RUNTIME_ROOT}` },
+	{ name: 'tsc', command: `cd /tmp && bun x --bun -p typescript@${PLATFORM_TYPESCRIPT_VERSION} tsc -p ${RUNTIME_ROOT}/${PLATFORM_TSCONFIG}` },
+]
+
+/** What the dev launcher reads (`DEV_LAUNCHER_CONFIG_FILE`): the platform's, written after the checks. */
+export function devLauncherConfig(execution: ZeropsLockedExecution, authoredSpa: readonly string[]): DevLauncherConfig {
+	const dev = execution.dev
+	if (dev === undefined) throw new Error('zerops: a dev launcher configuration needs a dev environment')
+	if (!/^[0-9a-f]{40}$/.test(dev.head)) throw new Error('zerops: a dev environment builds an exact commit')
+	return {
+		format: 1,
+		appId: execution.appId,
+		head: dev.head,
+		port: ZEROPS_APPLICATION_PORT,
+		healthPath: execution.contract.readinessPath,
+		serve: ['bun', SERVE_ENTRY],
+		migrate: [FABRIKA_BIN, 'db', 'migrate'],
+		spaBuild: authoredSpa,
+		checks: devChecks(execution.checkRelease),
+	}
+}
+
+const devLauncherConfigJson = (execution: ZeropsLockedExecution, authoredSpa: readonly string[]): string =>
+	JSON.stringify(devLauncherConfig(execution, authoredSpa))
+
+/** The scripts the build writes, and the ones every container's init commands run, in this order. */
+const initScripts = (execution: ZeropsLockedExecution): readonly { readonly path: string; readonly lines: readonly string[] }[] =>
+	execution.databaseUrl === null
+		? []
+		: [
+			{ path: MIGRATE_SCRIPT, lines: migrateScript(execution.appId) },
+			{ path: VERIFY_SCRIPT, lines: verifyScript(execution.appId) },
+			...(execution.dev === undefined ? [] : [{ path: DEV_INIT_SCRIPT, lines: devInitScript }]),
+		]
+
+const initCommandScripts = (execution: ZeropsLockedExecution): readonly string[] =>
+	execution.databaseUrl === null ? [] : execution.dev === undefined ? [MIGRATE_SCRIPT, VERIFY_SCRIPT] : [DEV_INIT_SCRIPT]
+
 const INSTALL = 'bun install --frozen-lockfile --ignore-scripts'
 
 // After every check: a map is uploaded only for a build that can deploy. A failed upload never fails the build; the
@@ -321,10 +414,9 @@ const sourceMapBuildVariables = (upload: OperationsSourceMapBuildUpload): Record
  * run first: they are authored code, so everything after them is reinstalled, regenerated or checked again. They run
  * `--isolate`, as the application skill runs them: a test file's DOM globals otherwise leak into the next file.
  */
-export function generatedBuildCommands(execution: ZeropsLockedExecution): readonly string[] {
+export function generatedBuildCommands(execution: ZeropsLockedExecution, authoredSpa: readonly string[] = []): 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-]*')
 	if (!FRAMEWORK_RELEASE_PATTERN.test(execution.checkRelease)) throw new Error('zerops: the checker release must be a release version')
-	const database = execution.databaseUrl !== null
 	return [
 		INSTALL,
 		'bun test --isolate --pass-with-no-tests',
@@ -333,8 +425,10 @@ export function generatedBuildCommands(execution: ZeropsLockedExecution): readon
 		`cd /tmp && bun x --bun -p @fabrika/check@${execution.checkRelease} 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)),
+		...initScripts(execution).map((script) => writeFileCommand(script.path, script.lines)),
+		...(execution.dev === undefined
+			? [writeFileCommand(START_SCRIPT, startScript)]
+			: [writeFileCommand(START_SCRIPT, devStartScript), writeBase64Command(DEV_LAUNCHER_CONFIG_FILE, devLauncherConfigJson(execution, authoredSpa))]),
 		...(execution.sourceMaps === null ? [] : [sourceMapUpload(execution.checkRelease)]),
 	]
 }
@@ -363,6 +457,16 @@ const jobCrontab = (contract: ZeropsContractRun): { readonly timing: string; rea
 /** How many job processes the crontab may run at once, each opening the application's database. */
 export const zeropsJobProcesses = (contract: ZeropsContractRun): number => jobCrontab(contract).length
 
+/** The commands every container runs before `run.start`, in order; any failure stops the activation. */
+export function generatedInitCommands(execution: ZeropsLockedExecution): string[] {
+	return [
+		// 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.
+		...(execution.contract.scan === true ? [`${FRESHCLAM} || echo 'fabrika: freshclam did not refresh the malware signatures'`] : []),
+		...initCommandScripts(execution).map((script) => `sh ${RUNTIME_ROOT}/${script}`),
+	]
+}
+
 /** The generated selected setup: the authored build kept, everything else the platform's. */
 export function renderLockedSetup(
 	setup: string,
@@ -385,25 +489,20 @@ export function renderLockedSetup(
 	const packages = sortedUnique([...execution.runtimePackages, ...(scan ? [SCANNER_PACKAGE] : [])])
 	// Every container keeps its own signatures; one scan pass at a time holds the job's lease.
 	const crontab = [...jobCrontab(contract), ...(scan ? [{ 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 initCommands = generatedInitCommands(execution)
 	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)],
+			buildCommands: [...authored.commands, ...generatedBuildCommands(execution, authored.commands)],
 			...(execution.sourceMaps === null ? {} : { envVariables: sourceMapBuildVariables(execution.sourceMaps) }),
 			deployFiles: ['./'],
 			cache: ['node_modules'],
 		},
 		deploy: {
-			readinessCheck: { httpGet: probe, retryPeriod: '10s', failureTimeout: '180s' },
+			readinessCheck: { exec: { command: readinessCommand(contract.readinessPath) }, retryPeriod: '10s', failureTimeout: '180s' },
 		},
 		run: {
 			base: ZEROPS_APPLICATION_RUNTIME,
@@ -411,7 +510,11 @@ export function renderLockedSetup(
 			...(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' },
+			// A dev container keeps its launcher running while the application it respawns fails: Zerops restarting it
+			// would only boot the same failing head again.
+			...(execution.dev === undefined
+				? { healthCheck: { httpGet: probe, execPeriod: '10s', disconnectTimeout: '30s', recoveryTimeout: '10s', failureTimeout: '120s' } }
+				: {}),
 			...(crontab.length === 0 ? {} : { crontab }),
 			envVariables,
 		},

package/src/installation/generated/platform-proxy-manifest.ts

@@ -258,6 +258,16 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
 						admission: null,
 						oauth: null,
 					},
+					{
+						id: 'dev-source',
+						kind: 'protocol',
+						method: 'POST',
+						path: '/platform/source/*',
+						callers: [],
+						requirement: null,
+						admission: null,
+						oauth: null,
+					},
 					{
 						id: 'webhooks-root',
 						kind: 'service',
@@ -453,6 +463,16 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
 						admission: null,
 						oauth: null,
 					},
+					{
+						id: 'dev-source',
+						kind: 'protocol',
+						method: 'POST',
+						path: '/platform/source/*',
+						callers: [],
+						requirement: null,
+						admission: null,
+						oauth: null,
+					},
 					{
 						id: 'webhooks-root',
 						kind: 'service',

package/src/manifest.ts

@@ -12,10 +12,12 @@ import {
 	FABRIKA_CHECK_VERSION,
 	LOCKED_APP_ID_PATTERN,
 	lockedAuthoredBuild,
+	READINESS_PATH_PATTERN,
 	ZEROPS_RUNTIME_PACKAGES,
 	zeropsAssetRoots,
 	type ZeropsContractRun,
 	zeropsContractRun,
+	type ZeropsDevExecution,
 	type ZeropsLockedExecution,
 	type ZeropsRuntimePackage,
 } from './execution'
@@ -310,14 +312,12 @@ const importDocumentSchema = z.object({ project: importProjectSchema.optional(),
 /** The import document a manifest carries: every service already holds the ADR-0004 invariants. */
 export type FabrikaManifestImportDocument = z.infer<typeof importDocumentSchema>
 
-/** A literal path of unreserved characters: it is written into the generated probes unquoted by any shell. */
-const READINESS_PATH = /^(?:\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)+$/
 const JOB_NAME = /^[A-Za-z][A-Za-z0-9_]*$/
 const CRON_SCHEDULE = /^[0-9*/,-]+(?: [0-9*/,-]+){4}$/
 
 const contractRunSchema = z.object({
 	digest: z.string().regex(CONTRACT_DIGEST_PATTERN),
-	readinessPath: z.string().regex(READINESS_PATH),
+	readinessPath: z.string().regex(READINESS_PATH_PATTERN),
 	jobs: z.array(z.object({ name: z.string().regex(JOB_NAME), schedule: z.string().regex(CRON_SCHEDULE) }).strict()),
 	files: z.literal(true).optional(),
 	scan: z.literal(true).optional(),
@@ -476,8 +476,11 @@ export const lockedExecutionOf = (manifest: FabrikaManifest): ZeropsLockedExecut
 	}
 }
 
-/** What Control lets a provider publish for one environment (`ProviderEnvironment.access`). */
-export type ZeropsAccess = Pick<ProviderEnvironment, 'access'>
+/**
+ * What Control lets a provider publish for one environment (`ProviderEnvironment.access`), and, for an environment of
+ * kind `dev`, the commit its bootstrap builds.
+ */
+export type ZeropsAccess = Pick<ProviderEnvironment, 'access'> & { readonly dev?: ZeropsDevExecution }
 
 /**
  * The execution descriptor's lock-down at deploy (ADR-0050): Control's approved contract decides it, not the artifact,
@@ -506,6 +509,7 @@ export function lockedExecutionFor(
 		storageHostname: applicationStorageHostname(manifest.target.importDocument.services),
 		runtimePackages: manifest.target.runtimePackages ?? [],
 		sourceMaps: artifactUpload === undefined ? null : sourceMapUpload(artifactUpload, access.contract),
+		...(granted.dev === undefined ? {} : { dev: granted.dev }),
 	}
 }
 

package/src/namespace/provisioning.ts

@@ -222,6 +222,7 @@ const deployProxy = async (
 	target: NormalizedZeropsNamespaceTarget,
 	options: ZeropsNamespaceOptions,
 	wait: ProviderNamespaceRepublishInput['wait'],
+	reuseActive: boolean,
 ): Promise<{ namespace: ProviderDeploymentNamespace; target: NormalizedZeropsNamespaceTarget }> => {
 	let currentNamespace = namespace
 	const manifest = compileNamespaceProxyManifest(namespace.id, input.members)
@@ -236,6 +237,7 @@ const deployProxy = async (
 		iamKey: options.iamKey,
 		signal: input.signal,
 		wait,
+		reuseActive,
 		sleep: options.sleep ?? defaultSleep,
 		boundary: () => input.events.boundary(),
 		checkpoint: async next => {
@@ -255,7 +257,7 @@ const republishNamespace = async (
 	if (target.proxyServiceId === undefined || (target.proxyBuild === undefined && !target.ready)) {
 		throw new Error(`Namespace ${namespace.id} is not ready`)
 	}
-	const deployed = await deployProxy(input, namespace, target, options, input.wait)
+	const deployed = await deployProxy(input, namespace, target, options, input.wait, true)
 	return { namespace: deployed.namespace, settled: deployed.target.proxyBuild === undefined && deployed.target.ready }
 }
 
@@ -433,7 +435,7 @@ const runNamespaceMutation = async (
 	}
 	namespace = await checkpoint(input, namespace, target)
 
-	const deployed = await deployProxy(input, namespace, target, options, 'active')
+	const deployed = await deployProxy(input, namespace, target, options, 'active', false)
 	namespace = deployed.namespace
 	target = { ...deployed.target, proxyConfigured: true }
 	// After the deploy, because the platform refuses a service with no HTTP port — and never before `ready`

package/src/namespace/proxy-attempt.ts

@@ -44,6 +44,11 @@ export interface ZeropsProxyRepublishInput {
 	/** Aborts with `lease_lost` when the namespace lease goes, and with `cancel_requested` when a deploy is cancelled. */
 	readonly signal: AbortSignal
 	readonly wait: 'started' | 'active'
+	/**
+	 * Reuse the proxy's ACTIVE version when it was built from this pin with this manifest identity. A deploy and a
+	 * registry change pass true; provisioning and reconcile rebuild, so an operator's repair always reaches the platform.
+	 */
+	readonly reuseActive: boolean
 	/** Persist the target; the caller fences the write on the namespace lease. */
 	readonly checkpoint: (target: ZeropsNamespaceTarget) => Promise<void>
 	readonly boundary: () => Promise<void>
@@ -88,6 +93,28 @@ const writeProxyIam = async (input: ZeropsProxyRepublishInput, serviceId: string
 const proxySecretsDigest = async (secrets: ReadonlyMap<string, string>): Promise<string> =>
 	digest([...secrets].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([key, value]) => `${key}=${value}`).join('\n'))
 
+/**
+ * Whether the proxy already runs `manifestSha256` on this pin: the recorded deployment names both, and its version is
+ * still the service's ACTIVE one. Any doubt, a failed read included, answers false, and the proxy is rebuilt.
+ */
+const servesManifest = async (input: ZeropsProxyRepublishInput, target: ZeropsNamespaceTarget, manifestSha256: string): Promise<boolean> => {
+	const deployed = target.proxyDeployment
+	const pin = target.proxySource
+	if (
+		target.ready !== true || deployed === undefined || deployed.manifestSha256 !== manifestSha256
+		|| deployed.commitSha !== pin.commitSha || deployed.descriptorSha256 !== pin.descriptor.sha256
+		|| deployed.repository.owner !== pin.repository.owner || deployed.repository.name !== pin.repository.name
+	) return false
+	await input.boundary()
+	try {
+		const version = await input.api.getAppVersion({ appVersionId: deployed.appVersionId, signal: input.signal })
+		return version.id === deployed.appVersionId && version.status === ZEROPS_ACTIVE && version.serviceStackId === target.proxyServiceId
+	} catch {
+		input.signal.throwIfAborted()
+		return false
+	}
+}
+
 /**
  * Rebuild the namespace proxy with `manifest` (ADR-0044). The attempt is recorded as `proxyBuild` and never
  * resumed: an inherited attempt not yet `triggered` is deleted, a triggered one is polled to a terminal state.
@@ -173,6 +200,8 @@ export async function republishProxy(input: ZeropsProxyRepublishInput): Promise<
 		if (inherited.manifestSha256 === manifestSha256) return target
 	}
 
+	if (input.reuseActive && target.proxyBuild === undefined && await servesManifest(input, target, manifestSha256)) return target
+
 	if (input.source === undefined) throw new Error('Zerops namespace source client is required')
 	const runId = crypto.randomUUID()
 	const resolved = await input.source.resolve({

package/src/plan.ts

@@ -48,7 +48,7 @@ export const buildZeropsPlan = (manifest: FabrikaManifest, target: ZeropsRuntime
 	steps.push({
 		id: 'raise-start-memory',
 		kind: 'raise-start-memory',
-		description: "Raise the deploy service's minimum RAM to what its start script needs",
+		description: "Raise the deploy service's minimum RAM to what its init commands need, and pin a dev environment to one container",
 	})
 	steps.push({
 		id: 'size-database',

package/src/provider.ts

@@ -50,6 +50,7 @@ import {
 import {
 	PLATFORM_TYPESCRIPT_VERSION,
 	renderLockedExecutionDescriptor,
+	type ZeropsDevExecution,
 	zeropsJobProcesses,
 	type ZeropsLockedExecution,
 	zeropsStartMinRam,
@@ -108,6 +109,8 @@ export interface ZeropsDeployRun {
 	readonly access?: ProviderApprovedAccess
 	/** The run-scoped source-map destination Control minted; the build uploads to it. */
 	readonly artifactUpload?: ProviderDeployInput['artifactUpload']
+	/** Present for an environment of kind `dev`: the launcher starts instead of the serving entry, on one container. */
+	readonly dev?: ZeropsDevExecution
 	readonly dryRun: boolean
 	readonly signal: AbortSignal
 	readonly events: ProviderRunEvents
@@ -280,14 +283,27 @@ export function interpolateManifest(
 }
 
 /** Human-readable failure for a version that finished in a non-`ACTIVE` state. */
-const terminalFailure = (version: ZeropsAppVersion): string => {
+const terminalFailure = (version: ZeropsAppVersion, checks: boolean): string => {
 	if (version.status === 'BACKUP') {
 		return `app-version ${version.id} was superseded by a newer version before it went live`
 	}
 	if (version.status === 'CANCELLED') {
 		return `app-version ${version.id} was cancelled`
 	}
-	return `Zerops pipeline failed: app-version ${version.id} is ${version.status ?? 'in an unknown state'}`
+	return `Zerops pipeline failed: app-version ${version.id} is ${version.status ?? 'in an unknown state'}${activationHint(version, checks)}`
+}
+
+/**
+ * What a version that built but did not activate tells the operator. Zerops' own log of it is the refused readiness
+ * attempts, which read as a server that never started whatever stopped it. `checks`: the generated init commands run
+ * the migrations, the schema check and the isolation tests, as for a contract application with a database.
+ */
+const activationHint = (version: ZeropsAppVersion, checks: boolean): string => {
+	if (version.status !== 'DEPLOY_FAILED') return ''
+	const failed = ': an init command failed or the readiness check never answered'
+	return checks
+		? `${failed}. The init commands run the migrations, the schema check and the generated isolation tests; the runtime lines above show how far they got`
+		: failed
 }
 
 /**
@@ -415,7 +431,7 @@ const openLog = async (env: StepEnv): Promise<ZeropsLogAccess | null> => {
  * poll loop without telling it leaves a build container burning through the pipeline's hour. A lost lease
  * gives no such permission (ADR-0044), so it stops without touching the build.
  */
-const awaitVersion = async (env: StepEnv, appVersionId: string, processId: string | undefined): Promise<void> => {
+const awaitVersion = async (env: StepEnv, appVersionId: string, processId: string | undefined, checks: boolean): Promise<void> => {
 	const { zerops, signal, log } = env
 	const access = await openLog(env)
 	const seen = new Set<string>()
@@ -461,14 +477,16 @@ const awaitVersion = async (env: StepEnv, appVersionId: string, processId: strin
 
 		if (process?.status !== undefined && ZEROPS_PROCESS_TERMINAL.has(process.status) && process.status !== ZEROPS_PROCESS_FINISHED) {
 			throw new Error(
-				`zerops: pipeline process ${process.id} is ${process.status} while app-version ${appVersionId} is ${version.status ?? 'in an unknown state'}`,
+				`zerops: pipeline process ${process.id} is ${process.status} while app-version ${appVersionId} is ${version.status ?? 'in an unknown state'}${
+					activationHint(version, checks)
+				}`,
 			)
 		}
 		if (version.status !== undefined && ZEROPS_TERMINAL.has(version.status)) {
 			if (version.status === ZEROPS_ACTIVE) {
 				return
 			}
-			throw new Error(terminalFailure(version))
+			throw new Error(terminalFailure(version, checks))
 		}
 		if (Date.now() > env.deadlineMs) await timedOut()
 		await zerops.sleep(POLL_INTERVAL_MS, signal)
@@ -669,12 +687,13 @@ const withMinRam = (custom: ZeropsServiceAutoscaling, minRam: number): ZeropsSer
 })
 
 /**
- * Raises the deploy service's minimum RAM to what the generated start script needs (`zeropsStartMinRam`), before the
+ * Raises the deploy service's minimum RAM to what the generated init commands need (`zeropsStartMinRam`), before the
  * version's containers start. An import cannot: Zerops ignores a changed `verticalAutoscaling` of an existing service,
  * so an existing service converges here, on every deploy. It only raises, and decides by reading the service back.
  */
 const raiseStartMemory = async (env: StepEnv): Promise<void> => {
 	const { run, zerops, log, signal, dryRun } = env
+	if (run.dev !== undefined) await pinOneContainer(env)
 	const locked = lockedExecutionFor(run.artifact, run, dryRun)
 	const minRam = locked === null ? null : zeropsStartMinRam(locked)
 	const hostname = run.artifact.target.deployService
@@ -697,6 +716,42 @@ const raiseStartMemory = async (env: StepEnv): Promise<void> => {
 	log(`  minimum RAM of ${hostname}: ${before ?? 'the platform default'} → ${after} GB`)
 }
 
+/**
+ * A dev environment runs on exactly one container: the launcher writes the files it syncs into that container, and a
+ * second one would serve the bootstrap head. Sends the custom autoscaling whole with only the container counts changed,
+ * and decides by reading it back.
+ */
+const pinOneContainer = async (env: StepEnv): Promise<void> => {
+	const { run, zerops, log, signal, dryRun } = env
+	const hostname = run.artifact.target.deployService
+	if (dryRun) {
+		log(`  [dry-run] would pin ${hostname} to one container`)
+		return
+	}
+	assertRunning(signal)
+	const service = await zerops.api.getService({ serviceId: run.target.serviceId, signal })
+	const custom = service.customAutoscaling
+	const horizontal = service.currentAutoscaling?.horizontal
+	if (horizontal?.minContainerCount === 1 && horizontal.maxContainerCount === 1) {
+		log(`  ${hostname} runs on one container, unchanged`)
+		return
+	}
+	if (custom === undefined) throw new Error(`zerops: ${hostname} did not report its autoscaling whole, so it cannot be pinned to one container`)
+	const process = await zerops.api.configureCustomAutoscaling({
+		serviceId: service.id,
+		autoscaling: { ...custom, horizontal: { minContainerCount: 1, maxContainerCount: 1 } },
+		signal,
+	})
+	if (process !== null) {
+		await waitForProcess({ api: zerops.api, processId: process.id, sleep: zerops.sleep, signal, label: `the autoscaling change of ${hostname}` })
+	}
+	const after = (await zerops.api.getService({ serviceId: service.id, signal })).currentAutoscaling?.horizontal
+	if (after?.minContainerCount !== 1 || after.maxContainerCount !== 1) {
+		throw new Error(`zerops: ${hostname} reads back ${after?.maxContainerCount ?? 'no'} container(s) after it was pinned to one`)
+	}
+	log(`  ${hostname} pinned to one container`)
+}
+
 /** What raising a minimum RAM calls; the deploy's collaborators, and the live platform-facts probe of the same path. */
 export interface MinRamRaise {
 	zerops: Pick<ZeropsCollaborators, 'api' | 'sleep'>
@@ -970,7 +1025,8 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 			}
 			const appVersionId = requireVersion(env, 'await-version')
 			assertRunning(signal)
-			await awaitVersion(env, appVersionId, attempt.processId)
+			const locked = lockedExecutionFor(artifact, run, dryRun)
+			await awaitVersion(env, appVersionId, attempt.processId, locked !== null && locked.databaseUrl !== null)
 			return
 		}