@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.3",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -14,87 +14,88 @@
 	"files": [
 		"src",
 		"skill",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./bun": {
 			"bun": "./src/bun.ts",
-			"types": "./src/bun.ts",
+			"types": "./types/src/bun.d.ts",
 			"default": "./src/bun.ts"
 		},
 		"./cloudflare": {
 			"bun": "./src/cloudflare.ts",
-			"types": "./src/cloudflare.ts",
+			"types": "./types/src/cloudflare.d.ts",
 			"default": "./src/cloudflare.ts"
 		},
 		"./contract": {
 			"bun": "./src/contract/index.ts",
-			"types": "./src/contract/index.ts",
+			"types": "./types/src/contract/index.d.ts",
 			"default": "./src/contract/index.ts"
 		},
 		"./client": {
 			"bun": "./src/client/index.ts",
-			"types": "./src/client/index.ts",
+			"types": "./types/src/client/index.d.ts",
 			"default": "./src/client/index.ts"
 		},
 		"./react": {
 			"bun": "./src/react/index.ts",
-			"types": "./src/react/index.ts",
+			"types": "./types/src/react/index.d.ts",
 			"default": "./src/react/index.ts"
 		},
 		"./react/testing": {
 			"bun": "./src/react/testing.ts",
-			"types": "./src/react/testing.ts",
+			"types": "./types/src/react/testing.d.ts",
 			"default": "./src/react/testing.ts"
 		},
 		"./implement": {
 			"bun": "./src/implement/index.ts",
-			"types": "./src/implement/index.ts",
+			"types": "./types/src/implement/index.d.ts",
 			"default": "./src/implement/index.ts"
 		},
 		"./service": {
 			"bun": "./src/service/index.ts",
-			"types": "./src/service/index.ts",
+			"types": "./types/src/service/index.d.ts",
 			"default": "./src/service/index.ts"
 		},
 		"./build": {
 			"bun": "./src/build.ts",
-			"types": "./src/build.ts",
+			"types": "./types/src/build.d.ts",
 			"default": "./src/build.ts"
 		},
 		"./testing": {
 			"bun": "./src/testing/index.ts",
-			"types": "./src/testing/index.ts",
+			"types": "./types/src/testing/index.d.ts",
 			"default": "./src/testing/index.ts"
 		},
 		"./testing/isolation": {
 			"bun": "./src/testing/isolation.ts",
-			"types": "./src/testing/isolation.ts",
+			"types": "./types/src/testing/isolation.d.ts",
 			"default": "./src/testing/isolation.ts"
 		},
 		"./testing/preload": {
 			"bun": "./src/testing/preload.ts",
-			"types": "./src/testing/preload.ts",
+			"types": "./types/src/testing/preload.d.ts",
 			"default": "./src/testing/preload.ts"
 		},
 		"./dev": {
 			"bun": "./src/dev/index.ts",
-			"types": "./src/dev/index.ts",
+			"types": "./types/src/dev/index.d.ts",
 			"default": "./src/dev/index.ts"
 		},
 		"./dev/wire": {
 			"bun": "./src/dev/wire.ts",
-			"types": "./src/dev/wire.ts",
+			"types": "./types/src/dev/wire.d.ts",
 			"default": "./src/dev/wire.ts"
 		},
 		"./agent-skill": {
 			"bun": "./src/agent-skill.ts",
-			"types": "./src/agent-skill.ts",
+			"types": "./types/src/agent-skill.d.ts",
 			"default": "./src/agent-skill.ts"
 		}
 	},
@@ -103,14 +104,14 @@
 		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "0.9.0-dev.1",
-		"@fabrika/auth-core": "0.9.0-dev.1",
-		"@fabrika/db": "0.9.0-dev.1",
-		"@fabrika/email": "0.9.0-dev.1",
-		"@fabrika/jwks": "0.9.0-dev.1",
-		"@fabrika/platform": "0.9.0-dev.1",
-		"@fabrika/platform-node": "0.9.0-dev.1",
-		"@fabrika/proxy-core": "0.9.0-dev.1",
+		"@fabrika/auth": "0.9.0-dev.3",
+		"@fabrika/auth-core": "0.9.0-dev.3",
+		"@fabrika/db": "0.9.0-dev.3",
+		"@fabrika/email": "0.9.0-dev.3",
+		"@fabrika/jwks": "0.9.0-dev.3",
+		"@fabrika/platform": "0.9.0-dev.3",
+		"@fabrika/platform-node": "0.9.0-dev.3",
+		"@fabrika/proxy-core": "0.9.0-dev.3",
 		"altcha-lib": "2.6.0",
 		"jose": "^5.9.0"
 	},

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.9.0-dev.1
+version: 0.9.0-dev.3
 description: >
   How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
   slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors

package/skill/references/app-setup.md

@@ -19,20 +19,20 @@ the SPA is added with it.
 		"test": "bun test --isolate"
 	},
 	"dependencies": {
-		"@fabrika/app": "0.9.0-dev.1",
-		"@fabrika/db": "0.9.0-dev.1",
-		"@fabrika/provider-zerops": "0.9.0-dev.1",
-		"@fabrika/proxy-core": "0.9.0-dev.1",
-		"@fabrika/ui": "0.9.0-dev.1",
+		"@fabrika/app": "0.9.0-dev.3",
+		"@fabrika/db": "0.9.0-dev.3",
+		"@fabrika/provider-zerops": "0.9.0-dev.3",
+		"@fabrika/proxy-core": "0.9.0-dev.3",
+		"@fabrika/ui": "0.9.0-dev.3",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "0.9.0-dev.1",
-		"@fabrika/cli": "0.9.0-dev.1",
-		"@fabrika/platform": "0.9.0-dev.1",
+		"@fabrika/check": "0.9.0-dev.3",
+		"@fabrika/cli": "0.9.0-dev.3",
+		"@fabrika/platform": "0.9.0-dev.3",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",

package/src/dev/changes.ts

@@ -1,64 +1,26 @@
 // What a sync changes, read off its paths: whether the build owns one (then the commit needs a bootstrap run), whether
-// the migrations changed, and whether a web source did. Pure: the caller reads the files.
+// the migrations changed, and whether a web source did. Whether the contract changed is the digest's to say, not a path's.
 
-import { posix } from 'node:path'
 import { CONTRACT_FILE } from '../build.js'
 
 /** The application's migrations, as `fabrika db migrate` reads them. */
 export const MIGRATIONS_DIRECTORY = 'db/migrations/'
 
-/** Files whose change the build turns into something else: an install, the contract digest and proxy table, a generated file. */
+/** Files whose change the build turns into something else: an install, or the generated run and build descriptors. */
 const BUILD_OWNED_FILES: ReadonlySet<string> = new Set(['package.json', 'bun.lock', 'bun.lockb', 'bunfig.toml', 'zerops.yaml', 'zerops.yml'])
 const BUILD_OWNED_DIRECTORIES = ['fabrika/', 'node_modules/'] as const
 
 /** Server code and the database: a change only there leaves the SPA as it is. */
 const SERVER_DIRECTORIES = ['src/', 'db/'] as const
 
-/** Reads a file at the head the sync brings, or null when it does not exist there. */
-export type SourceReader = (path: string) => string | null
-
-const RELATIVE_IMPORT = /(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)['"](\.{1,2}\/[^'"]+)['"]/g
-
-/** The repository paths a relative specifier of `from` may name, in the order Bun resolves a TypeScript import. */
-function candidates(from: string, specifier: string): string[] {
-	const base = posix.normalize(posix.join(posix.dirname(from), specifier))
-	if (base.startsWith('../')) return []
-	const withoutJs = base.endsWith('.js') ? base.slice(0, -3) : base
-	return [base, `${withoutJs}.ts`, `${withoutJs}.tsx`, `${withoutJs}/index.ts`]
-}
-
-/** `fabrika.contract.ts` and every module it reaches by a relative import, read through `read`. */
-export function contractModules(read: SourceReader): Set<string> {
-	const modules = new Set<string>()
-	const pending = [CONTRACT_FILE]
-	while (pending.length > 0) {
-		const path = pending.pop() ?? ''
-		if (modules.has(path)) continue
-		const text = read(path)
-		if (text === null) continue
-		modules.add(path)
-		for (const match of text.matchAll(RELATIVE_IMPORT)) {
-			const resolved = candidates(path, match[1] ?? '').find((candidate) => read(candidate) !== null)
-			if (resolved !== undefined) pending.push(resolved)
-		}
-	}
-	return modules
-}
-
-/**
- * Why the change needs a bootstrap run, in one line, or null when the launcher may apply it. `before` reads the
- * container's files, `after` the files at the target: a module the contract imports at either counts.
- */
-export function bootstrapReason(paths: readonly string[], before: SourceReader, after: SourceReader): string | null {
-	const contract = new Set([...contractModules(before), ...contractModules(after)])
+/** Why the change needs a bootstrap run, in one line, or null when the launcher may apply it. */
+export function bootstrapReason(paths: readonly string[]): string | null {
 	for (const path of paths) {
 		const why = BUILD_OWNED_FILES.has(path)
 			? 'the dependencies, the lockfile or the build descriptor'
 			: BUILD_OWNED_DIRECTORIES.some((directory) => path.startsWith(directory))
 			? 'the generated files or the installed packages'
-			: contract.has(path)
-			? 'the contract or a module it imports (its digest and the proxy table change)'
-			: path.startsWith('fabrika.') && !path.includes('/')
+			: path !== CONTRACT_FILE && path.startsWith('fabrika.') && !path.includes('/')
 			? 'a fabrika.* file'
 			: null
 		if (why !== null) return `${path} changed, which is ${why}; that needs a bootstrap run: call bind_dev again`

package/src/dev/contract-digest.ts

@@ -0,0 +1,17 @@
+// The launcher's child that answers whether a commit changed the contract (ADR-0049). It runs in the application root
+// with no credential in its environment, loads the application module the launcher itself never loads, and prints the
+// digest the application's boot compares with `FABRIKA_CONTRACT_DIGEST`.
+
+import { contractDigest } from '@fabrika/auth-core'
+import { join } from 'node:path'
+import { IMPLEMENTATION_FILE } from '../build.js'
+import { compileContract } from '../contract/compile.js'
+import { isContractImplementation } from '../implement/implement.js'
+
+const module: unknown = await import(join(process.cwd(), IMPLEMENTATION_FILE))
+const app = typeof module === 'object' && module !== null ? Reflect.get(module, 'default') : undefined
+if (!isContractImplementation(app)) {
+	console.error(`${IMPLEMENTATION_FILE} does not default-export serve(contract, { … })`)
+	process.exit(1)
+}
+console.log(contractDigest(compileContract(app.contract, app.database?.tables ?? {})))

package/src/dev/index.ts

@@ -1,6 +1,6 @@
 // @fabrika/app/dev — the launcher of a `dev` environment, which the generated dev entrypoint runs (Bun only).
 
-export { bootstrapReason, contractModules, migrationsChanged, webSourceChanged } from './changes.js'
+export { bootstrapReason, migrationsChanged, webSourceChanged } from './changes.js'
 export {
 	type DevLauncher,
 	type DevLauncherOptions,

package/src/dev/launcher.ts

@@ -4,14 +4,20 @@
 // files, which it writes, then it migrates when `db/migrations/` changed, runs the SPA commands when a web source
 // changed, and respawns the application. A change the build owns is refused with one line: it needs a bootstrap run.
 
-import { DEV_LAUNCHER_CONFIG_FILE, DEV_LAUNCHER_STATE_FILE, type DevLauncherConfig, platformTransportVariables } from '@fabrika/auth-core'
+import {
+	DEV_LAUNCHER_CONFIG_FILE,
+	DEV_LAUNCHER_STATE_FILE,
+	type DevLauncherConfig,
+	FABRIKA_CONTRACT_DIGEST,
+	platformTransportVariables,
+} from '@fabrika/auth-core'
 import { applicationRuntimeUrl, dropApplicationDatabase } from '@fabrika/platform-node'
-import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { z } from 'zod/v4'
 import { makeProcessUndumpable } from '../undumpable.js'
-import { bootstrapReason, migrationsChanged, type SourceReader, webSourceChanged } from './changes.js'
+import { bootstrapReason, migrationsChanged, webSourceChanged } from './changes.js'
 import { OutputRing, type OutputSink, processOutput, readLines } from './output.js'
 import {
 	DEV_SOURCE_REPORT_PATH,
@@ -41,6 +47,9 @@ const STOP_GRACE_MS = 3_000
 const CHECK_TIMEOUT_MS = 10 * 60_000
 const CRASH_BACKOFF_MS = [1_000, 2_000, 5_000, 10_000] as const
 const FORWARDED_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'] as const
+const DIGEST_TIMEOUT_MS = 60_000
+const CONTRACT_DIGEST = /^sha256:[0-9a-f]{64}$/
+const CONTRACT_DIGEST_CHILD = fileURLToPath(new URL('./contract-digest.ts', import.meta.url))
 
 const commitSha = z.string().regex(/^[0-9a-f]{40}$/)
 /** A literal path of unreserved characters, as the provider's readiness probe requests it. */
@@ -118,9 +127,14 @@ interface CommandResult {
 }
 
 type SyncOutcome =
-	| { readonly kind: 'applied'; readonly migrations: boolean; readonly web: boolean }
+	| { readonly kind: 'applied'; readonly migrations: boolean; readonly spaFailure: string | null }
 	| { readonly kind: 'refused'; readonly reason: string }
 
+/** Control answers 409 to the container of a bootstrap run that a newer one replaced. */
+class SupersededError extends Error {}
+
+const SUPERSEDED = 'a newer bootstrap run replaced this container; it stops following Control and serves until it is stopped'
+
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
 
 /** Every value of the environment a log line must never show: the database credentials and every key, secret or token. */
@@ -167,6 +181,8 @@ class Launcher {
 	private crashes = 0
 	private stopped = false
 	private reportFailing = false
+	/** A newer bootstrap run replaced this container: it keeps serving until the platform stops it, and asks nothing. */
+	private superseded = false
 
 	constructor(private readonly options: DevLauncherOptions) {
 		this.root = options.root
@@ -216,7 +232,12 @@ class Launcher {
 		while (!this.stopped) {
 			try {
 				return await this.wait(false)
-			} catch {
+			} catch (error) {
+				if (error instanceof SupersededError) {
+					this.say(SUPERSEDED, 'stderr')
+					this.superseded = true
+					return null
+				}
 				if (Date.now() >= deadline) {
 					this.say('Control did not answer at boot; serving the files this container holds', 'stderr')
 					return null
@@ -229,13 +250,18 @@ class Launcher {
 
 	private async follow(): Promise<void> {
 		let backoff = 1_000
-		while (!this.stopped) {
+		while (!this.stopped && !this.superseded) {
 			let answer: DevWaitAnswer
 			try {
 				answer = await this.wait(true)
 				backoff = 1_000
-			} catch {
+			} catch (error) {
 				if (this.stopped) return
+				if (error instanceof SupersededError) {
+					this.say(SUPERSEDED, 'stderr')
+					this.superseded = true
+					return
+				}
 				this.say(`the long poll on Control failed; retrying in ${backoff / 1000} s`, 'stderr')
 				await sleep(backoff)
 				backoff = Math.min(backoff * 2, 15_000)
@@ -246,9 +272,19 @@ class Launcher {
 	}
 
 	private async wait(hold: boolean): Promise<DevWaitAnswer> {
-		const body = encodeDevWaitRequest({ head: this.state.head, reset: this.state.reset, checks: this.state.checks, hold })
+		const body = encodeDevWaitRequest({
+			bootstrap: this.config.head,
+			head: this.state.head,
+			reset: this.state.reset,
+			checks: this.state.checks,
+			hold,
+		})
 		const signal = AbortSignal.any([this.controller.signal, AbortSignal.timeout(DEV_SOURCE_WAIT_MS + 15_000)])
 		const response = await this.fetch(this.request(DEV_SOURCE_WAIT_PATH, body, signal))
+		if (response.status === 409) {
+			await response.body?.cancel()
+			throw new SupersededError()
+		}
 		if (!response.ok) throw new Error(`the source receiver answered ${response.status}`)
 		const parsed = parseDevWaitAnswer(await response.json())
 		if (!parsed.ok) throw new Error('the source receiver answered a body this release does not read')
@@ -265,7 +301,9 @@ class Launcher {
 	}
 
 	private async report(): Promise<void> {
+		if (this.superseded) return
 		const body = encodeDevReport({
+			bootstrap: this.config.head,
 			head: this.state.head,
 			status: this.status,
 			target: this.target,
@@ -290,7 +328,7 @@ class Launcher {
 		if (this.state.checks === null) this.state = { ...this.state, checks: answer.checks }
 		let changed = boot
 		let migrate = boot
-		let web = false
+		let spaFailure: string | null = null
 		if (answer.sync !== null) {
 			const outcome = await this.writeSync(answer.sync)
 			if (outcome.kind === 'refused') {
@@ -302,28 +340,28 @@ class Launcher {
 			} else {
 				changed = true
 				migrate ||= outcome.migrations
-				web = outcome.web
+				spaFailure = outcome.spaFailure
 			}
 		}
 		const reset = answer.reset > (this.state.reset ?? answer.reset)
-		if (changed || reset) await this.converge({ migrate: migrate || reset, reset, web, resetTo: answer.reset })
+		if (changed || reset) await this.converge({ migrate: migrate || reset, reset, spaFailure, resetTo: answer.reset })
 		if (answer.checks > (this.state.checks ?? answer.checks)) await this.check(answer.checks)
 	}
 
 	/** Bring the database, the SPA and the running application to the files on disk, then report. */
-	private async converge(steps: { migrate: boolean; reset: boolean; web: boolean; resetTo: number }): Promise<void> {
+	private async converge(steps: { migrate: boolean; reset: boolean; spaFailure: string | null; resetTo: number }): Promise<void> {
 		this.status = steps.reset ? 'resetting' : 'syncing'
 		void this.report()
 		let failure: string | null = null
 		// A migration's ALTER would queue behind the live version's locks, and a reset drops the role it connects as.
 		if (this.provisioningUrl !== null && steps.migrate) await this.stopApplication()
 		if (steps.reset) {
-			failure = await this.resetDatabase()
+			failure = await this.timed('the reset', () => this.resetDatabase())
 			this.state = { ...this.state, reset: steps.resetTo }
 		}
-		if (failure === null && steps.migrate) failure = await this.migrate()
-		if (failure === null && steps.web) failure = await this.buildSpa()
-		const served = await this.restartApplication()
+		if (failure === null && steps.migrate) failure = await this.timed('the migration', () => this.migrate())
+		if (failure === null) failure = steps.spaFailure
+		const served = await this.timed('the restart until healthy', () => this.restartApplication())
 		failure ??= served
 		this.status = failure === null ? 'serving' : 'failed'
 		this.target = null
@@ -332,17 +370,44 @@ class Launcher {
 		await this.report()
 	}
 
+	/** Run one step of a sync and log how long it took: what a slow `apply_changes` is read from. */
+	private async timed(step: string, run: () => Promise<string | null>): Promise<string | null> {
+		const started = performance.now()
+		const failure = await run()
+		this.say(`${step} ${failure === null ? 'took' : 'failed after'} ${Math.round(performance.now() - started)} ms`)
+		return failure
+	}
+
 	private async writeSync(sync: DevSync): Promise<SyncOutcome> {
 		if (sync.from !== this.state.head) {
 			return { kind: 'refused', reason: `Control sent changes from ${sync.from}, and this container holds ${this.state.head}; call bind_dev again` }
 		}
 		const paths = sync.files.map((file) => file.path)
-		const incoming = new Map(sync.files.map((file) => [file.path, file.content]))
-		const before: SourceReader = (path) => this.readLocal(path)
-		const after: SourceReader = (path) => incoming.has(path) ? incoming.get(path) ?? null : this.readLocal(path)
-		const reason = bootstrapReason(paths, before, after)
+		const reason = bootstrapReason(paths)
 		if (reason !== null) return { kind: 'refused', reason }
-		for (const file of sync.files) {
+		const previous = await Promise.all(
+			sync.files.map(async (file) => ({ path: file.path, content: await readFile(join(this.root, file.path)).catch(() => null) })),
+		)
+		await this.writeFiles(sync.files)
+		const web = this.config.spaBuild.length > 0 && webSourceChanged(paths)
+		// The SPA build runs beside the digest: a refusal is rare, and then the build runs again over the restored files.
+		const [changedContract, spaFailure] = await Promise.all([this.contractChange(), web ? this.spaBuild() : null])
+		if (changedContract !== null) {
+			await this.writeFiles(previous)
+			if (web) await this.spaBuild()
+			return { kind: 'refused', reason: changedContract }
+		}
+		this.state = { ...this.state, head: sync.to }
+		this.say(`synced ${sync.files.length} files to ${sync.to}`)
+		return { kind: 'applied', migrations: migrationsChanged(paths), spaFailure }
+	}
+
+	private spaBuild(): Promise<string | null> {
+		return this.timed('the SPA build', () => this.buildSpa())
+	}
+
+	private async writeFiles(files: readonly { readonly path: string; readonly content: string | Uint8Array | null }[]): Promise<void> {
+		for (const file of files) {
 			const path = join(this.root, file.path)
 			if (file.content === null) {
 				await rm(path, { force: true })
@@ -352,19 +417,37 @@ class Launcher {
 			await writeFile(`${path}.fabrika-dev`, file.content)
 			await rename(`${path}.fabrika-dev`, path)
 		}
-		this.state = { ...this.state, head: sync.to }
-		this.say(`synced ${sync.files.length} files to ${sync.to}`)
-		return { kind: 'applied', migrations: migrationsChanged(paths), web: this.config.spaBuild.length > 0 && webSourceChanged(paths) }
 	}
 
-	private readLocal(path: string): string | null {
-		const absolute = join(this.root, path)
-		if (!existsSync(absolute)) return null
-		try {
-			return readFileSync(absolute, 'utf8')
-		} catch {
+	/**
+	 * Why the files on disk need a bootstrap run because their contract digest is not the one the bootstrap run deployed,
+	 * or null. A child computes it: it loads the application module, which the launcher never does, with no credential.
+	 * A digest it cannot compute is no reason: the respawned application then fails to boot and reports why.
+	 */
+	private async contractChange(): Promise<string | null> {
+		const deployed = this.options.environment[FABRIKA_CONTRACT_DIGEST] ?? ''
+		if (deployed === '') return null
+		const started = performance.now()
+		const child = Bun.spawn(['bun', CONTRACT_DIGEST_CHILD], {
+			cwd: this.root,
+			env: { PATH: this.options.environment['PATH'] ?? '', HOME: this.options.environment['HOME'] ?? '' },
+			stdin: 'ignore',
+			stdout: 'pipe',
+			stderr: 'pipe',
+		})
+		const timer = setTimeout(() => child.kill('SIGKILL'), DIGEST_TIMEOUT_MS)
+		const [stdout, stderr] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited])
+		clearTimeout(timer)
+		const digest = stdout.trim()
+		if (child.exitCode !== 0 || !CONTRACT_DIGEST.test(digest)) {
+			for (const line of stderr.split('\n').filter((text) => text.trim() !== '').slice(-5)) this.ring.push('stderr', line)
+			this.say('the contract digest could not be computed; the application is respawned and reports why', 'stderr')
 			return null
 		}
+		this.say(`contract digest computed in ${Math.round(performance.now() - started)} ms`)
+		if (digest === deployed) return null
+		return `the change alters the contract (its digest is ${digest}, and the bootstrap run deployed ${deployed}): the proxy table and `
+			+ 'the approval follow the contract, so that needs a bootstrap run: call bind_dev again'
 	}
 
 	private async persist(): Promise<void> {
@@ -413,15 +496,17 @@ class Launcher {
 		const results: DevCheckResult[] = []
 		for (const check of this.config.checks) {
 			this.say(`check ${check.name}: ${check.command}`)
+			const started = performance.now()
 			const result = await this.run(['sh', '-c', check.command], this.commandEnvironment, CHECK_TIMEOUT_MS)
 			results.push({
 				name: check.name,
 				ok: result.exitCode === 0,
 				exitCode: result.exitCode,
+				durationMs: Math.round(performance.now() - started),
 				output: result.lines.slice(-CHECK_OUTPUT_LINES).map((line) => line.slice(0, 2_000)),
 			})
 		}
-		this.checkResults = { request, results }
+		this.checkResults = { request, head: this.state.head, results }
 		this.state = { ...this.state, checks: request }
 		this.status = before.status
 		this.message = before.message

package/src/dev/wire.ts

@@ -32,7 +32,14 @@ export function isSourcePath(path: string): boolean {
 
 const sourcePath = z.string().refine(isSourcePath, 'not a repository-relative path')
 
+/**
+ * The commit the container's bootstrap run built (`DevLauncherConfig.head`). Control answers only the container of the
+ * newest bootstrap run: a container a newer bootstrap replaces still runs for a while, and must not sync or report.
+ */
+const bootstrap = commitSha
+
 export const devWaitRequestSchema = z.object({
+	bootstrap,
 	/** The commit whose files the container holds now. */
 	head: commitSha,
 	/** The reset generation it applied last; null for a container with no record of one, which adopts the answer's. */
@@ -81,6 +88,7 @@ export const devCheckResultSchema = z.object({
 	name: z.string().min(1).max(64),
 	ok: z.boolean(),
 	exitCode: z.number().int().nullable(),
+	durationMs: z.number().int().min(0),
 	/** The last lines of its output. */
 	output: z.array(z.string().max(DEV_REPORT_MAX_LINE_CHARACTERS)).max(DEV_REPORT_MAX_LINES),
 }).strict()
@@ -88,6 +96,7 @@ export const devCheckResultSchema = z.object({
 export type DevCheckResult = z.infer<typeof devCheckResultSchema>
 
 export const devReportSchema = z.object({
+	bootstrap,
 	/** The commit whose files the container holds now. */
 	head: commitSha,
 	status: z.enum(DEV_STATUSES),
@@ -98,7 +107,8 @@ export const devReportSchema = z.object({
 	/** The newest lines of the application's and the launcher's output, oldest first. */
 	log: z.array(devLogLineSchema).max(DEV_REPORT_MAX_LINES),
 	reset: generation.nullable(),
-	checks: z.object({ request: generation, results: z.array(devCheckResultSchema).max(8) }).strict().nullable(),
+	/** The newest check run: the request it answers, the commit whose files it checked, and each check's result. */
+	checks: z.object({ request: generation, head: commitSha, results: z.array(devCheckResultSchema).max(8) }).strict().nullable(),
 }).strict()
 
 export type DevReport = z.infer<typeof devReportSchema>

package/types/src/agent-skill.d.ts

@@ -0,0 +1,29 @@
+export declare const APP_AGENT_SKILL_NAME = "fabrika-app";
+export interface AppAgentSkillReference {
+    /** The file's path in the skill directory, `references/<topic>.md`: the path `SKILL.md` names it by. */
+    readonly path: string;
+    /** The topic `get_app_rules` answers it under: its file name without `.md`. */
+    readonly topic: string;
+    readonly text: string;
+}
+export interface AppAgentSkill {
+    /** The `version` of the frontmatter: the version of the `@fabrika/app` that ships it. */
+    readonly version: string;
+    /** The whole `SKILL.md`, frontmatter included: what a skill directory holds. */
+    readonly text: string;
+    /** `SKILL.md` without the frontmatter. */
+    readonly body: string;
+    /** The reference files, by path. */
+    readonly references: readonly AppAgentSkillReference[];
+}
+/** The skill of this package. */
+export declare function readAppAgentSkill(): AppAgentSkill;
+/** The skill in `skillDir`, the `skill/` directory of an installed `@fabrika/app`. */
+export declare function readAppAgentSkillAt(skillDir: string): AppAgentSkill;
+/**
+ * The skill of the `@fabrika/app` an application installed: the nearest `node_modules/@fabrika/app` from `appRoot`
+ * up, as Bun resolves the package. `null` when the application has not installed it.
+ */
+export declare function installedAppAgentSkill(appRoot: string): AppAgentSkill | null;
+/** The `AGENTS.md` of an application repository: the skill's body, then each reference file. */
+export declare function renderAgentsFile(skill: AppAgentSkill): string;

package/types/src/build.d.ts

@@ -0,0 +1,11 @@
+/** An application root with this file is a contract application. The paths equal `@fabrika/check`'s layout. */
+export declare const CONTRACT_FILE = "fabrika.contract.ts";
+/** Relative to the application root. */
+export declare const GENERATED_ENTRY_FILE = "fabrika/entry.generated.ts";
+/** The module whose default export is `serve(contract, …)`, relative to the application root. */
+export declare const IMPLEMENTATION_FILE = "src/app.ts";
+export type EntryRuntime = 'bun' | 'cloudflare';
+/** The entrypoint source for one runtime. */
+export declare function generatedEntry(runtime: EntryRuntime): string;
+/** Writes the entrypoint under `root` and returns its path. */
+export declare function writeGeneratedEntry(root: string, runtime: EntryRuntime): Promise<string>;