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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.2",
 	"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.2",
+		"@fabrika/auth-core": "0.9.0-dev.2",
+		"@fabrika/db": "0.9.0-dev.2",
+		"@fabrika/email": "0.9.0-dev.2",
+		"@fabrika/jwks": "0.9.0-dev.2",
+		"@fabrika/platform": "0.9.0-dev.2",
+		"@fabrika/platform-node": "0.9.0-dev.2",
+		"@fabrika/proxy-core": "0.9.0-dev.2",
 		"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.2
 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.2",
+		"@fabrika/db": "0.9.0-dev.2",
+		"@fabrika/provider-zerops": "0.9.0-dev.2",
+		"@fabrika/proxy-core": "0.9.0-dev.2",
+		"@fabrika/ui": "0.9.0-dev.2",
 		"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.2",
+		"@fabrika/cli": "0.9.0-dev.2",
+		"@fabrika/platform": "0.9.0-dev.2",
 		"@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. */
@@ -318,12 +327,12 @@ class Launcher {
 		// 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 && steps.web) failure = await this.timed('the SPA build', () => this.buildSpa())
+		const served = await this.timed('the restart until healthy', () => this.restartApplication())
 		failure ??= served
 		this.status = failure === null ? 'serving' : 'failed'
 		this.target = null
@@ -332,17 +341,37 @@ 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 changedContract = await this.contractChange()
+		if (changedContract !== null) {
+			await this.writeFiles(previous)
+			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), web: this.config.spaBuild.length > 0 && webSourceChanged(paths) }
+	}
+
+	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 +381,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> {
@@ -421,7 +468,7 @@ class Launcher {
 				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

@@ -98,7 +98,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>;

package/types/src/bun.d.ts

@@ -0,0 +1,66 @@
+import type { FileObjectStore } from '@fabrika/platform';
+import type { FetchService, RequestExecutionContext } from './fetch.js';
+import { type IamKeySource } from './implement/boot.js';
+import { type CrashEvents } from './implement/crashes.js';
+import { type ContractImplementation } from './implement/implement.js';
+import { type JobRunOptions, type JobRunResult } from './jobs/runner.js';
+export { diskAssets } from './disk-assets.js';
+export { clamscanArguments, type ClamscanOptions, clamscanScanner } from './files/clamscan.js';
+export { markProductionProcess } from '@fabrika/db/production';
+export interface ManagedBunHandlerOptions {
+    /** Required sink for rejected background tasks. Do not log raw errors or secret-bearing values. */
+    onBackgroundError(error: unknown): void;
+    executionContext?: never;
+}
+export interface ExternalBunHandlerOptions {
+    /** Existing supervised process context. Its owner remains responsible for draining it. */
+    executionContext: RequestExecutionContext;
+    onBackgroundError?: never;
+}
+export type BunHandlerOptions = ManagedBunHandlerOptions | ExternalBunHandlerOptions;
+export interface BunHandler {
+    fetch(request: Request): Promise<Response>;
+    /** Wait until every task registered through `waitUntil()` has settled. */
+    drain(): Promise<void>;
+}
+export declare function createBunHandler<Env>(app: FetchService<Env>, env: Env, options: BunHandlerOptions): BunHandler;
+/** IAM's public key set at the issuer's `/.well-known/jwks.json`, for a process with no IAM binding. */
+export declare function issuerJwks(issuer: unknown): IamKeySource;
+export interface ContractServer {
+    /** The port the server listens on; `PORT=0` picks a free one. */
+    readonly port: number;
+    /** Stops accepting requests and waits for the ones in flight. */
+    stop(): Promise<void>;
+}
+/**
+ * The stored files' object storage (Zerops object storage, path-style), when the platform wrote its variables;
+ * a partial set stops the boot. The credentials are never quoted in a message.
+ */
+export declare function openFileStorage(framework: Readonly<Record<string, string>>): FileObjectStore | undefined;
+/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
+export type ImplementationLoader = () => Promise<{
+    readonly default: ContractImplementation;
+}>;
+export interface ContractServerOptions {
+    /** Where the process hears of an uncaught exception or an unhandled rejection; `process` by default. */
+    readonly crashes?: CrashEvents;
+    /** What posts a report to Operations' ingest; `fetch` by default. */
+    readonly operationsFetch?: (request: Request) => Promise<Response>;
+}
+/**
+ * Captures the framework's variables and scrubs them from the process, then imports the application, boots it and
+ * serves it on `PORT` (default 3000), on every interface: the project's private network is how the proxy reaches
+ * it. Called only by the generated entrypoint, with `process.env`. SIGTERM drains. Given the provisioning credential,
+ * it is the launcher instead: it never loads the application and re-runs the entrypoint as the runtime role.
+ * With an Operations DSN, a startup that throws is reported before it is rethrown, and so is a crash once it serves.
+ */
+export declare function serveContract(load: ImplementationLoader, env: Readonly<Record<string, string | undefined>>, options?: ContractServerOptions): Promise<ContractServer>;
+/** The application module at `path`, imported when the loader runs; its default export must be what `serve` returned. */
+export declare function implementationAt(path: string): ImplementationLoader;
+/**
+ * One run of the job `name` (`fabrika job run <name>`, the crontab's command): the framework's variables are captured
+ * and scrubbed before the application loads, exactly as `serveContract` does, then `boot` binds the job and the run
+ * takes its lease. The connection closes when the run ends. Given the provisioning credential, it re-runs the command
+ * as the runtime role, as `serveContract` does.
+ */
+export declare function runContractJob(load: ImplementationLoader, env: Readonly<Record<string, string | undefined>>, name: string, options?: JobRunOptions): Promise<JobRunResult>;

package/types/src/client/caller.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod/v4';
+declare const PageCallerSchema: z.ZodObject<{
+    label: z.ZodString;
+    email: z.ZodString;
+    actions: z.ZodObject<{
+        /** The actions held as a global grant, so in every value. */
+        app: z.ZodArray<z.ZodString>;
+        /** Each scope value the person holds something in, with those actions; sorted by dimension, then value. */
+        scopes: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            value: z.ZodString;
+            actions: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PageCaller = z.infer<typeof PageCallerSchema>;
+/** The caller document as the framework answers it; throws on any other value. */
+export declare function parsePageCaller(value: unknown): PageCaller;
+export {};