@fabrika/provider-zerops 0.8.1 → 0.9.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.8.1",
+	"version": "0.9.0-dev.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,27 +12,28 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./cli": {
 			"bun": "./src/cli.ts",
-			"types": "./src/cli.ts",
+			"types": "./types/src/cli.d.ts",
 			"default": "./src/cli.ts"
 		},
 		"./installation": {
 			"bun": "./src/installation/index.ts",
-			"types": "./src/installation/index.ts",
+			"types": "./types/src/installation/index.d.ts",
 			"default": "./src/installation/index.ts"
 		},
 		"./installation/topology": {
 			"bun": "./src/installation/topology/index.ts",
-			"types": "./src/installation/topology/index.ts",
+			"types": "./types/src/installation/topology/index.d.ts",
 			"default": "./src/installation/topology/index.ts"
 		}
 	},
@@ -43,14 +44,14 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth": "0.8.1",
-		"@fabrika/auth-core": "0.8.1",
-		"@fabrika/email": "0.8.1",
-		"@fabrika/iam-contract": "0.8.1",
-		"@fabrika/installation-init": "0.8.1",
-		"@fabrika/operations-contract": "0.8.1",
-		"@fabrika/provider-contract": "0.8.1",
-		"@fabrika/proxy-core": "0.8.1",
+		"@fabrika/auth": "0.9.0-dev.2",
+		"@fabrika/auth-core": "0.9.0-dev.2",
+		"@fabrika/email": "0.9.0-dev.2",
+		"@fabrika/iam-contract": "0.9.0-dev.2",
+		"@fabrika/installation-init": "0.9.0-dev.2",
+		"@fabrika/operations-contract": "0.9.0-dev.2",
+		"@fabrika/provider-contract": "0.9.0-dev.2",
+		"@fabrika/proxy-core": "0.9.0-dev.2",
 		"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/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,
@@ -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
 
 /**
@@ -245,15 +262,20 @@ 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. */
+/**
+ * The compiler options of the platform's type check; the application's own `tsconfig.json` and its `paths` are not read.
+ * It covers the SPA under `web/` too: Bun bundles the SPA without checking its types.
+ */
 const PLATFORM_TSCONFIG_CONTENTS = JSON.stringify({
 	compilerOptions: {
 		target: 'ES2022',
 		module: 'ESNext',
 		moduleResolution: 'bundler',
 		lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+		jsx: 'react-jsx',
 		types: ['bun'],
 		strict: true,
 		noUncheckedIndexedAccess: true,
@@ -264,7 +286,7 @@ const PLATFORM_TSCONFIG_CONTENTS = JSON.stringify({
 		isolatedModules: true,
 		noEmit: true,
 	},
-	include: ['../fabrika.contract.ts', '../src', 'entry.generated.ts'],
+	include: ['../fabrika.contract.ts', '../src', '../web', 'entry.generated.ts'],
 })
 
 /** One `printf` writing `lines` to `path`. Each line is single-quoted, so it may hold neither `'` nor an expansion. */
@@ -294,16 +316,119 @@ const verifyScript = (appId: string): readonly string[] => [
 	`FABRIKA_APP_ID=${appId} exec ${FABRIKA_BIN} db test-isolation`,
 ]
 
-const startScript: readonly string[] = ['#!/bin/sh', 'set -eu', `cd ${RUNTIME_ROOT}`, 'exec bun fabrika/entry.generated.ts']
+// 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}`,
+]
 
-/** The scripts the build writes and every container's init commands run, in this order. */
+/** 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, in its order, as the dev launcher runs it in the application root on what the container holds. */
+const devChecks = (release: string): DevLauncherConfig['checks'] => [
+	{ name: 'tests', command: TESTS_COMMAND },
+	{ name: 'tsc', command: `cd /tmp && bun x --bun -p typescript@${PLATFORM_TYPESCRIPT_VERSION} tsc -p ${RUNTIME_ROOT}/${PLATFORM_TSCONFIG}` },
+	{ name: 'fabrika-check', command: `cd /tmp && bun x --bun -p @fabrika/check@${release} fabrika-check ${RUNTIME_ROOT}` },
+]
+
+/** 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) }]
+		: [
+			{ 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'
 
+/**
+ * What `@fabrika/db/testing` prints after the label of a test file it skips without `FABRIKA_TEST_POSTGRES_URL`. Every
+ * framework release prints it, so the platform counts it for any application's release.
+ */
+const DATABASE_TEST_SKIP_MARKER = ' skipped: set FABRIKA_TEST_POSTGRES_URL to run the Postgres-backed tests'
+
+/** The prefix of the line the tests command prints after the test run. */
+const TESTS_REPORT_PREFIX = 'fabrika-tests:'
+
+/** One `bun -e "…"` running `script`, which may hold none of the characters a double-quoted shell word expands. */
+const bunEvalCommand = (script: readonly string[]): string => {
+	const source = script.join(' ')
+	if (/["$`\\!]/.test(source)) throw new Error('zerops: a generated bun -e script must not contain a quote, an expansion or a backslash')
+	return `bun -e "${source}"`
+}
+
+// The build has no database, so every Postgres-backed test file skips and the run still passes. This command runs the
+// tests as before and then says how many files did not run, so a green test step does not read as a tested database.
+const TESTS_COMMAND = bunEvalCommand([
+	"const child = Bun.spawn([process.execPath, 'test', '--isolate', '--pass-with-no-tests'], { stdout: 'inherit', stderr: 'pipe' });",
+	'const decoder = new TextDecoder();',
+	"let output = '';",
+	'for await (const chunk of child.stderr) { process.stderr.write(chunk); output += decoder.decode(chunk, { stream: true }) }',
+	'const code = await child.exited;',
+	`const marker = '${DATABASE_TEST_SKIP_MARKER}';`,
+	'const skipped = output.split(String.fromCharCode(10)).filter((line) => line.includes(marker)).map((line) => line.slice(0, line.indexOf(marker)).trim());',
+	`const prefix = '${TESTS_REPORT_PREFIX}';`,
+	"console.warn(skipped.length === 0 ? prefix + ' no Postgres-backed test file skipped' : prefix + ' ' + skipped.length + ' Postgres-backed test files did not run, because the build has no database: ' + skipped.join(', '));",
+	'process.exit(code);',
+])
+
 // After every check: a map is uploaded only for a build that can deploy. A failed upload never fails the build; the
 // provider reads the state from the report line.
 const sourceMapUpload = (release: string): string => `cd /tmp && bun x --bun -p @fabrika/check@${release} fabrika-source-maps ${SOURCE_ROOT} || true`
@@ -322,21 +447,25 @@ const sourceMapBuildVariables = (upload: OperationsSourceMapBuildUpload): Record
 /**
  * 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. They run
- * `--isolate`, as the application skill runs them: a test file's DOM globals otherwise leak into the next file.
+ * `--isolate`, as the application skill runs them: a test file's DOM globals otherwise leak into the next file. `tsc`
+ * runs before the checker, as in the skill's loop: the usual quick fix of a type error is a cast or an `any`, which only
+ * the checker refuses, so the checker is the last word on the code.
  */
-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')
 	return [
 		INSTALL,
-		'bun test --isolate --pass-with-no-tests',
+		TESTS_COMMAND,
 		`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@${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}`,
+		`cd /tmp && bun x --bun -p @fabrika/check@${execution.checkRelease} fabrika-check ${SOURCE_ROOT}`,
 		...initScripts(execution).map((script) => writeFileCommand(script.path, script.lines)),
-		writeFileCommand(START_SCRIPT, startScript),
+		...(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)]),
 	]
 }
@@ -371,7 +500,7 @@ export function generatedInitCommands(execution: ZeropsLockedExecution): string[
 		// 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'`] : []),
-		...initScripts(execution).map((script) => `sh ${RUNTIME_ROOT}/${script.path}`),
+		...initCommandScripts(execution).map((script) => `sh ${RUNTIME_ROOT}/${script}`),
 	]
 }
 
@@ -404,13 +533,13 @@ export function renderLockedSetup(
 		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,
@@ -418,7 +547,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 init commands need",
+		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
@@ -690,6 +693,7 @@ const withMinRam = (custom: ZeropsServiceAutoscaling, minRam: number): ZeropsSer
  */
 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
@@ -712,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'>