@fabrika/app 0.4.5 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.4.5",
+	"version": "0.4.6",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -93,13 +93,13 @@
 		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.4.5",
-		"@fabrika/auth-core": "^0.4.5",
-		"@fabrika/db": "^0.4.5",
-		"@fabrika/jwks": "^0.4.5",
-		"@fabrika/platform": "^0.4.5",
-		"@fabrika/platform-node": "^0.4.5",
-		"@fabrika/proxy-core": "^0.4.5",
+		"@fabrika/auth": "^0.4.6",
+		"@fabrika/auth-core": "^0.4.6",
+		"@fabrika/db": "^0.4.6",
+		"@fabrika/jwks": "^0.4.6",
+		"@fabrika/platform": "^0.4.6",
+		"@fabrika/platform-node": "^0.4.6",
+		"@fabrika/proxy-core": "^0.4.6",
 		"jose": "^5.9.0"
 	},
 	"peerDependencies": {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.4.5
+version: 0.4.6
 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.4.5",
-		"@fabrika/db": "^0.4.5",
-		"@fabrika/provider-zerops": "^0.4.5",
-		"@fabrika/proxy-core": "^0.4.5",
-		"@fabrika/ui": "^0.4.5",
+		"@fabrika/app": "^0.4.6",
+		"@fabrika/db": "^0.4.6",
+		"@fabrika/provider-zerops": "^0.4.6",
+		"@fabrika/proxy-core": "^0.4.6",
+		"@fabrika/ui": "^0.4.6",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "^0.4.5",
-		"@fabrika/cli": "^0.4.5",
-		"@fabrika/platform": "^0.4.5",
+		"@fabrika/check": "^0.4.6",
+		"@fabrika/cli": "^0.4.6",
+		"@fabrika/platform": "^0.4.6",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",

package/skill/references/errors.md

@@ -100,9 +100,24 @@ message. The codes you meet most:
 | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `query_refused`      | the data layer refused a statement or an operation: `undeclared_reach`, `sql_read_only`, `unknown_column`, `read_only`, `sql_outside_transaction` …; the reason's text names the rule |
 | `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), or one kept past its request (`ended`, `foreign_work`)    |
-| `handler_failed`     | your handler threw something else; the log has no more, so test the handler                                                                                                           |
+| `handler_failed`     | your handler threw something else; the log has no more: the Operations issue has the stack, or test the handler                                                                       |
 
-With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. A job attempt names its failure with the
+With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
+threw: the error's type, its message, its stack and its `cause` chain. Read the stack there, not in the log. A crash
+outside a request (an uncaught exception, an unhandled rejection, a failed start) is an issue too, titled by the error.
+
+The framework removes the values of your secrets and anything shaped like a credential (a token, a key, a password in a
+URL) from the message before it leaves. It cannot recognize personal data or a secret it was not told about:
+
+- never put an e-mail address, a name, a record's text or any other personal data into an error message; name the
+  record by its id;
+- never put a secret, a token or a request header into an error message;
+- name an application variable that holds a secret so its name says so (`STRIPE_SECRET_KEY`, `MAIL_API_TOKEN`): only
+  such a name tells the framework to remove its value;
+- keep the original error as `cause` when you rethrow (`throw new Error('could not load the invoice', { cause })`), so
+  the chain shows both.
+
+A job attempt names its failure with the
 same codes and reasons: `fabrika job run` prints `job <name> failed after 1 attempt: query_refused: undeclared_reach`,
 its log line adds the text, and `kit.runJob` answers `{ status: 'failed', code, reason }`. A `DatabaseError` carries
 only the SQLSTATE: `23505` is a unique violation, `23503` a foreign key, `23502` a null in a `NOT NULL` column.

package/src/bun.ts

@@ -15,7 +15,8 @@ import { diskAssets } from './disk-assets.js'
 import type { FetchService, RequestExecutionContext } from './fetch.js'
 import { clamscanScanner } from './files/clamscan.js'
 import { boot, BootError, type IamKeySource } from './implement/boot.js'
-import { captureEnvironment } from './implement/environment.js'
+import { type CrashEvents, environmentCrashReporter, type ProcessCrashKind, reportFatalCrashes, reportWithin } from './implement/crashes.js'
+import { type CapturedEnvironment, captureEnvironment } from './implement/environment.js'
 import { type ContractImplementation, isContractImplementation } from './implement/implement.js'
 import { issuerWorkloadTokens, type WorkloadTokenSource } from './implement/workload.js'
 import { JOB_CHECK_INTERVAL_MS, type JobRunOptions, type JobRunResult } from './jobs/runner.js'
@@ -253,17 +254,84 @@ function workloadTokensOf(framework: Readonly<Record<string, string>>): Workload
 /** 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>
+}
+
+/** The process's own crash events: listening suppresses Bun's default, so `failAsBefore` restores it. */
+function processCrashEvents(): CrashEvents {
+	return {
+		listen(listener) {
+			const exception = (error: unknown) => listener('uncaught_exception', error)
+			const rejection = (reason: unknown) => listener('unhandled_rejection', reason)
+			process.on('uncaughtException', exception)
+			process.on('unhandledRejection', rejection)
+			return () => {
+				process.off('uncaughtException', exception)
+				process.off('unhandledRejection', rejection)
+			}
+		},
+	}
+}
+
+/** Raised again with no listener left: Bun prints it and exits with 1, exactly as without a report. */
+function failAsBefore(kind: ProcessCrashKind, error: unknown): void {
+	if (kind === 'unhandled_rejection') {
+		void Promise.reject(error)
+		return
+	}
+	setTimeout(() => {
+		throw error
+	})
+}
+
 /**
  * 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 async function serveContract(load: ImplementationLoader, env: Readonly<Record<string, string | undefined>>): Promise<ContractServer> {
+export async function serveContract(
+	load: ImplementationLoader,
+	env: Readonly<Record<string, string | undefined>>,
+	options: ContractServerOptions = {},
+): Promise<ContractServer> {
 	if (holdsProvisioningCredential(env)) {
 		return relaunchAsRuntime(env)
 	}
 	const environment = captureEnvironment(env)
+	const crashes = environmentCrashReporter(environment, options.operationsFetch)
+	let server: ContractServer
+	try {
+		server = await startContractServer(load, environment, options.operationsFetch)
+	} catch (error) {
+		if (crashes !== null) {
+			await reportWithin(crashes, 'boot_failed', error)
+		}
+		throw error
+	}
+	if (crashes === null) {
+		return server
+	}
+	const stopListening = reportFatalCrashes({ events: options.crashes ?? processCrashEvents(), reporter: crashes, fail: failAsBefore })
+	return {
+		port: server.port,
+		stop: () => {
+			stopListening()
+			return server.stop()
+		},
+	}
+}
+
+async function startContractServer(
+	load: ImplementationLoader,
+	environment: CapturedEnvironment,
+	operationsFetch: ContractServerOptions['operationsFetch'],
+): Promise<ContractServer> {
 	const port = Number.parseInt(environment.application['PORT'] === undefined ? '3000' : String(environment.application['PORT']), 10)
 	if (!Number.isInteger(port) || port < 0 || port > 65535) {
 		throw new Error('PORT must be an integer between 0 and 65535')
@@ -285,6 +353,7 @@ export async function serveContract(load: ImplementationLoader, env: Readonly<Re
 		membership,
 		workloadTokens,
 		requireProxySecret: true,
+		...(operationsFetch === undefined ? {} : { operationsFetch }),
 	})
 	// The work a request leaves running (a failure's report, a job a form kicked) is drained before the database closes.
 	const handler = createBunHandler({ fetch: (request, _env: undefined, exec) => served.fetch(request, exec) }, undefined, {

package/src/cloudflare.ts

@@ -6,6 +6,7 @@ import { parseJwks } from '@fabrika/jwks'
 import type { FetchService, RequestExecutionContext } from './fetch.js'
 import { boot, type ContractApp, type IamKeySource } from './implement/boot.js'
 import { CONNECT_BINDING_PREFIX, type ConnectFetch } from './implement/connect.js'
+import { type CrashEvents, environmentCrashReporter, reportSurvivedCrashes } from './implement/crashes.js'
 import type { SpaAssets } from './implement/dispatch.js'
 import { captureEnvironment } from './implement/environment.js'
 import type { ContractImplementation } from './implement/implement.js'
@@ -146,32 +147,70 @@ function connectBindings(env: Readonly<Record<string, unknown>>): Record<string,
 /** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
 export type ImplementationLoader = () => Promise<{ readonly default: ContractImplementation }>
 
+export interface ContractWorkerOptions {
+	/** Where the isolate hears of an unhandled rejection; the global `unhandledrejection` event by default. */
+	readonly rejections?: CrashEvents
+	/** What posts a report to Operations' ingest; `fetch` by default. */
+	readonly operationsFetch?: (request: Request) => Promise<Response>
+}
+
+/** The isolate's `unhandledrejection` event. Listening leaves the runtime's own handling, its log line, in place. */
+function globalRejectionEvents(): CrashEvents {
+	return {
+		listen(listener) {
+			const rejection = (event: Event) => listener('unhandled_rejection', Reflect.get(event, 'reason'))
+			globalThis.addEventListener('unhandledrejection', rejection)
+			return () => globalThis.removeEventListener('unhandledrejection', rejection)
+		},
+	}
+}
+
 /**
  * A Worker module for a contract application, called only by the generated entrypoint. A Worker receives its
  * environment with the first request, so the framework captures it, scrubs the process environment and only then
- * imports the application and boots it, once per environment object.
+ * imports the application and boots it, once per environment object. With an Operations DSN, the first failed boot
+ * of an isolate is reported, and once one booted, every unhandled rejection of the isolate is, within a budget.
  */
-export function createContractWorker(load: ImplementationLoader): {
+export function createContractWorker(load: ImplementationLoader, options: ContractWorkerOptions = {}): {
 	fetch(request: Request, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<Response>
 } {
 	const booted = new WeakMap<object, Promise<ContractApp>>()
-	const bootFor = async (env: Readonly<Record<string, unknown>>): Promise<ContractApp> => {
+	let bootFailureReported = false
+	let watchingRejections = false
+	const bootFor = async (env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<ContractApp> => {
 		const variables = Object.fromEntries(Object.entries(env).filter(([name]) => !FRAMEWORK_BINDINGS.has(name)))
 		const environment = captureEnvironment(variables)
-		const { default: app } = await load()
-		return boot(app, {
-			environment,
-			iam: bindingKeySource(env['IAM']),
-			assets: bindingAssets(env['ASSETS']),
-			membership: bindingMembership(env['IAM']),
-			connectBindings: connectBindings(env),
-		})
+		const crashes = environmentCrashReporter(environment, options.operationsFetch)
+		let contractApp: ContractApp
+		try {
+			const { default: app } = await load()
+			contractApp = boot(app, {
+				environment,
+				iam: bindingKeySource(env['IAM']),
+				assets: bindingAssets(env['ASSETS']),
+				membership: bindingMembership(env['IAM']),
+				connectBindings: connectBindings(env),
+				...(options.operationsFetch === undefined ? {} : { operationsFetch: options.operationsFetch }),
+			})
+		} catch (error) {
+			// Every request of a failed isolate boots again; one report says it.
+			if (crashes !== null && !bootFailureReported) {
+				bootFailureReported = true
+				exec.waitUntil(crashes.report('boot_failed', error))
+			}
+			throw error
+		}
+		if (crashes !== null && !watchingRejections) {
+			watchingRejections = true
+			reportSurvivedCrashes(options.rejections ?? globalRejectionEvents(), crashes)
+		}
+		return contractApp
 	}
 	return {
 		async fetch(request, env, exec) {
 			let contractApp = booted.get(env)
 			if (contractApp === undefined) {
-				contractApp = bootFor(env)
+				contractApp = bootFor(env, exec)
 				booted.set(env, contractApp)
 				// A failed boot is not cached: the next request boots again and fails with the same problems.
 				contractApp.catch(() => booted.delete(env))

package/src/implement/boot.ts

@@ -46,6 +46,7 @@ import { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE, FILE_SWEEP_TIMEOUT_MS, fileCollect
 import { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE, type FileScanner, SCAN_LIMITS } from '../files/scan'
 import { logReporter, type OperationsReporter, operationsReporter, operationsSettings, type ReportSource } from '../jobs/report'
 import { bindJobs, type ContractJobs, type HandlerErrorSink } from '../jobs/runner'
+import { environmentScrubber } from '../jobs/scrub'
 import { browserConfigs } from './browser-config'
 import { createCapabilityIssuer, requestIsReadOnly } from './capability'
 import { type ChallengeFetch, type ChallengeVerifier, turnstileVerifier } from './challenge'
@@ -589,10 +590,11 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 	checkContractDigest(options.environment.framework, artifact, problems)
 	const proxySecret = readProxySecret(options.environment.framework, options.requireProxySecret === true, problems)
 	const operations = operationsSettings(options.environment.framework, problems)
+	const scrubber = environmentScrubber(options.environment)
 	const reporterFor = (source: ReportSource): OperationsReporter | null =>
 		operations === null
 			? null
-			: operationsReporter({ ...operations, source, ...(options.operationsFetch === undefined ? {} : { fetch: options.operationsFetch }) })
+			: operationsReporter({ ...operations, source, scrubber, ...(options.operationsFetch === undefined ? {} : { fetch: options.operationsFetch }) })
 	const owned = new Set(Object.values(artifact.tables).flatMap((table) => table.scope.mode === 'dimension' ? [table.scope.dimension] : []))
 	// A file collection's dimension is located through its own table and its owner's.
 	for (const name of Object.keys(artifact.files)) {

package/src/implement/crashes.ts

@@ -0,0 +1,84 @@
+// A failure outside any request or job run (ADR-0059): a boot that throws, an uncaught exception, an unhandled
+// rejection. Each is one Operations event of what was thrown, scrubbed like every other report. A request's and a job
+// run's failures are caught and reported where they happen, so none of them reaches these listeners.
+
+import { type CrashKind, type CrashReporter, crashReporter, operationsSettings } from '../jobs/report'
+import { environmentScrubber } from '../jobs/scrub'
+import type { CapturedEnvironment } from './environment'
+import { MAX_FAILURE_REPORTS_PER_MINUTE, MinuteBudget } from './failures'
+
+/** How long a crash or a failed boot waits for its report before the process fails as it would have without one. */
+export const CRASH_FLUSH_MS = 2_000
+
+export type ProcessCrashKind = Exclude<CrashKind, 'boot_failed'>
+
+export interface CrashEvents {
+	/** Starts listening; the returned function stops, which gives the runtime its own handling back. */
+	listen(listener: (kind: ProcessCrashKind, error: unknown) => void): () => void
+}
+
+/** The reporter of `environment`'s DSN, or `null` without a usable one: `boot` reports a DSN that is not one. */
+export function environmentCrashReporter(
+	environment: CapturedEnvironment,
+	fetch: ((request: Request) => Promise<Response>) | undefined,
+): CrashReporter | null {
+	const settings = operationsSettings(environment.framework, [])
+	if (settings === null) {
+		return null
+	}
+	return crashReporter({ ...settings, scrubber: environmentScrubber(environment), ...(fetch === undefined ? {} : { fetch }) })
+}
+
+/** Reports and waits for the delivery, at most `flushMs`. Never rejects. */
+export async function reportWithin(reporter: CrashReporter, kind: CrashKind, error: unknown, flushMs = CRASH_FLUSH_MS): Promise<void> {
+	let timer: ReturnType<typeof setTimeout> | undefined
+	const elapsed = new Promise<void>((resolve) => {
+		timer = setTimeout(resolve, flushMs)
+	})
+	try {
+		await Promise.race([reporter.report(kind, error), elapsed])
+	} finally {
+		clearTimeout(timer)
+	}
+}
+
+export interface FatalCrashOptions {
+	readonly events: CrashEvents
+	readonly reporter: CrashReporter
+	/** Fails the process as the runtime would have without a listener: the listeners are stopped by then. */
+	readonly fail: (kind: ProcessCrashKind, error: unknown) => void
+	readonly flushMs?: number
+}
+
+/**
+ * A process that dies of a crash (Bun): the first crash is reported, then the listeners stop and `fail` hands it back
+ * to the runtime, which prints it and exits as before. A second crash during that wait is not reported: the process is
+ * already failing.
+ */
+export function reportFatalCrashes(options: FatalCrashOptions): () => void {
+	let crashing = false
+	const stop = options.events.listen((kind, error) => {
+		if (crashing) {
+			return
+		}
+		crashing = true
+		void reportWithin(options.reporter, kind, error, options.flushMs).then(() => {
+			stop()
+			options.fail(kind, error)
+		})
+	})
+	return stop
+}
+
+/**
+ * An isolate that survives an unhandled rejection (a Worker): each one is reported, at most
+ * `MAX_FAILURE_REPORTS_PER_MINUTE` per minute, and the runtime keeps its own handling.
+ */
+export function reportSurvivedCrashes(events: CrashEvents, reporter: CrashReporter, now: () => number = Date.now): () => void {
+	const budget = new MinuteBudget(MAX_FAILURE_REPORTS_PER_MINUTE, now)
+	return events.listen((kind, error) => {
+		if (budget.admit()) {
+			void reporter.report(kind, error)
+		}
+	})
+}

package/src/implement/failures.ts

@@ -1,6 +1,8 @@
-// A request that answered 5xx: one server log line and, with an Operations DSN, one error event. Both carry fixed codes
-// and bounded identifiers only, never an error's name or message: application code, drivers and even the framework's
-// own refusals can put request data there. A framework failure adds its reason and the reason's catalog text.
+// A request that answered 5xx: one server log line and, with an Operations DSN, one error event. The log line carries
+// fixed codes and bounded identifiers only, never an error's name or message: application code, drivers and even the
+// framework's own refusals can put request data there. The event adds what was thrown as its cause chain, scrubbed of
+// the environment's secrets and of credential patterns, a framework failure's message replaced by its catalog text
+// (ADR-0059).
 
 import { CAPABILITY_ERRORS, CapabilityError, QUERY_REFUSALS, QueryRefusedError } from '@fabrika/db/framework'
 import { isStructuralError } from '../errors'
@@ -69,16 +71,37 @@ export interface RequestFailure {
 	readonly error: unknown
 }
 
-export class FailureReports {
-	readonly #reporter: OperationsReporter | null
+/** At most `limit` admissions per minute of `now`; the next minute starts again. */
+export class MinuteBudget {
+	readonly #limit: number
 	readonly #now: () => number
 	#window = -1
-	#reported = 0
+	#admitted = 0
+
+	constructor(limit: number, now: () => number = Date.now) {
+		this.#limit = limit
+		this.#now = now
+	}
+
+	admit(): boolean {
+		const window = Math.floor(this.#now() / MINUTE_MS)
+		if (window !== this.#window) {
+			this.#window = window
+			this.#admitted = 0
+		}
+		this.#admitted++
+		return this.#admitted <= this.#limit
+	}
+}
+
+export class FailureReports {
+	readonly #reporter: OperationsReporter | null
+	readonly #budget: MinuteBudget
 
 	/** `reporter` is `null` without an Operations DSN: the log line is then the only record. */
 	constructor(reporter: OperationsReporter | null, now: () => number = Date.now) {
 		this.#reporter = reporter
-		this.#now = now
+		this.#budget = new MinuteBudget(MAX_FAILURE_REPORTS_PER_MINUTE, now)
 	}
 
 	/** Never rejects. The returned delivery may outlive the response; a runtime with `waitUntil` keeps it alive. */
@@ -86,7 +109,7 @@ export class FailureReports {
 		const code = failureCode(failure.error)
 		const why = failureReason(failure.error)
 		console.error(`fabrika: ${failure.endpoint}: ${code}${why === null ? '' : `: ${why.reason}: ${why.text}`}`)
-		if (this.#reporter === null || !this.#admit()) {
+		if (this.#reporter === null || !this.#budget.admit()) {
 			return Promise.resolve()
 		}
 		const tags: Record<string, string> = { endpoint: failure.endpoint, code, status: String(failure.status) }
@@ -101,16 +124,7 @@ export class FailureReports {
 			type: 'RequestFailed',
 			message: `endpoint '${failure.endpoint}' answered ${failure.status}: ${code}`,
 			tags,
+			error: failure.error,
 		})
 	}
-
-	#admit(): boolean {
-		const window = Math.floor(this.#now() / MINUTE_MS)
-		if (window !== this.#window) {
-			this.#window = window
-			this.#reported = 0
-		}
-		this.#reported++
-		return this.#reported <= MAX_FAILURE_REPORTS_PER_MINUTE
-	}
 }

package/src/implement/index.ts

@@ -12,8 +12,9 @@ export {
 	type ScanObject,
 	type ScanVerdict,
 } from '../files/scan'
-export type { OperationsReport, OperationsReporter } from '../jobs/report'
+export { crashEnvelope, type OperationsReport, type OperationsReporter, reportEnvelope } from '../jobs/report'
 export { type ContractJobs, type JobClock, JobError, type JobFailureCode, type JobRunOptions, type JobRunResult } from '../jobs/runner'
+export { secretScrubber } from '../jobs/scrub'
 export type { JobContext, JobHandler, JobHandlersOf, JobPrincipal } from '../jobs/types'
 export { LINK_BOOTSTRAP_SCRIPT } from './anonymous'
 export { boot, BootError, type BootOptions, type ContractApp, type IamKeySource } from './boot'

package/src/jobs/exception.ts

@@ -0,0 +1,139 @@
+// A thrown value as the Sentry exception values Operations ingests (ADR-0059): its type, its scrubbed message, its
+// stack frames and its cause chain, each bounded so one event stays far below the ingest's size limit.
+
+import { isStructuralError } from '../errors'
+import { failureReason } from '../implement/failures'
+import type { Scrubber } from './scrub'
+
+/** A message is cut to this many characters. */
+export const MAX_MESSAGE_LENGTH = 2_048
+/** A file or function name is cut to this many characters. */
+export const MAX_FRAME_FIELD_LENGTH = 512
+/** The frames nearest the throw are kept. */
+export const MAX_FRAMES = 50
+/** The thrown value and at most this many minus one causes. */
+export const MAX_CAUSE_DEPTH = 5
+/** The encoded exception values stay within this; Operations refuses an ingest message above 120 KiB. */
+export const MAX_EXCEPTION_BYTES = 64 * 1024
+
+/** One stack frame in Sentry's shape. */
+export interface ReportedFrame {
+	readonly filename: string
+	readonly function?: string
+	readonly lineno?: number
+	readonly colno?: number
+	/** `false` for a dependency's or the runtime's own frame. */
+	readonly in_app: boolean
+}
+
+/** One exception value in Sentry's shape. */
+export interface ReportedException {
+	readonly type: string
+	readonly value: string
+	readonly stacktrace?: { readonly frames: readonly ReportedFrame[] }
+}
+
+const FRAME_LINE = /^\s*at\s+(.*)$/
+const LOCATION = /^(.*?)(?::(\d+))?(?::(\d+))?$/
+const CALL = /^(.*?) \((.*)\)$/
+/** An error's name is reported only when it is an identifier; anything else might be data. */
+const TYPE_NAME = /^[A-Za-z_$][\w$.]{0,127}$/
+
+function cut(text: string, length: number): string {
+	return text.length <= length ? text : `${text.slice(0, length)}…`
+}
+
+/** A frame of the runtime, of a dependency, or without a position is no frame of the application. */
+function inApp(filename: string, line: number | undefined): boolean {
+	return line !== undefined
+		&& !filename.includes('/node_modules/')
+		&& !/^(?:node|bun|internal|native|wasm):/.test(filename)
+		&& !/^(?:native|<anonymous>|\d*)$/.test(filename)
+}
+
+function parseFrame(text: string, scrubber: Scrubber): ReportedFrame | null {
+	const body = FRAME_LINE.exec(text)?.[1]?.replace(/^async\s+/, '').trim()
+	if (body === undefined || body === '') {
+		return null
+	}
+	const call = CALL.exec(body)
+	const name = call?.[1]?.trim()
+	const where = LOCATION.exec(call?.[2] ?? body)
+	const filename = cut(scrubber.scrub(where?.[1] ?? body), MAX_FRAME_FIELD_LENGTH)
+	const line = where?.[2] === undefined ? undefined : Number(where[2])
+	const column = where?.[3] === undefined ? undefined : Number(where[3])
+	return {
+		filename,
+		...(name === undefined || name === '' ? {} : { function: cut(scrubber.scrub(name), MAX_FRAME_FIELD_LENGTH) }),
+		...(line === undefined ? {} : { lineno: line }),
+		...(column === undefined ? {} : { colno: column }),
+		in_app: inApp(filename, line),
+	}
+}
+
+/**
+ * The frames of a V8 (Cloudflare Workers) or JavaScriptCore (Bun) `stack`, oldest call first as Sentry orders them,
+ * the `MAX_FRAMES` nearest the throw kept. The message lines before the first frame are not read.
+ */
+export function parseStack(stack: string, scrubber: Scrubber): ReportedFrame[] {
+	const frames = stack.split('\n').flatMap((line) => {
+		const frame = parseFrame(line, scrubber)
+		return frame === null ? [] : [frame]
+	})
+	return frames.slice(0, MAX_FRAMES).reverse()
+}
+
+function describe(error: unknown, scrubber: Scrubber): ReportedException {
+	if (error instanceof Error) {
+		const type = TYPE_NAME.test(error.name) ? scrubber.scrub(error.name) : 'Error'
+		// A framework failure's message may quote request data or a row; its catalog text says the same without them.
+		const why = failureReason(error)
+		const value = why === null ? cut(scrubber.scrub(error.message), MAX_MESSAGE_LENGTH) : `${why.reason}: ${why.text}`
+		const frames = typeof error.stack === 'string' ? parseStack(error.stack, scrubber) : []
+		return frames.length === 0 ? { type, value } : { type, value, stacktrace: { frames } }
+	}
+	if (isStructuralError(error)) {
+		return { type: TYPE_NAME.test(error.type) ? error.type : 'HttpError', value: cut(scrubber.scrub(error.message), MAX_MESSAGE_LENGTH) }
+	}
+	if (typeof error === 'string') {
+		return { type: 'Error', value: cut(scrubber.scrub(error), MAX_MESSAGE_LENGTH) }
+	}
+	return { type: 'Error', value: `a thrown ${error === null ? 'null' : typeof error} that is not an Error` }
+}
+
+/**
+ * `error` and its causes, at most `MAX_CAUSE_DEPTH`, the deepest cause first and `error` last, as Sentry orders a
+ * chain. Every text is scrubbed and cut; the chain is then fitted within `MAX_EXCEPTION_BYTES`.
+ */
+export function exceptionChain(error: unknown, scrubber: Scrubber): ReportedException[] {
+	const chain: ReportedException[] = []
+	const seen = new Set<unknown>()
+	let next: unknown = error
+	while (chain.length < MAX_CAUSE_DEPTH && !seen.has(next)) {
+		seen.add(next)
+		chain.push(describe(next, scrubber))
+		if (!(next instanceof Error) || next.cause === undefined) {
+			break
+		}
+		next = next.cause
+	}
+	return fitWithin(chain.reverse(), MAX_EXCEPTION_BYTES)
+}
+
+const encodedSize = (values: readonly ReportedException[]): number => new TextEncoder().encode(JSON.stringify(values)).length
+
+/** Drops the deepest causes, then halves the frames of what is left, until `values` encodes within `maxBytes`. */
+export function fitWithin(values: readonly ReportedException[], maxBytes: number): ReportedException[] {
+	let fitted = [...values]
+	while (fitted.length > 1 && encodedSize(fitted) > maxBytes) {
+		fitted = fitted.slice(1)
+	}
+	while (encodedSize(fitted) > maxBytes && fitted.some((value) => (value.stacktrace?.frames.length ?? 0) > 0)) {
+		fitted = fitted.map((value) => {
+			const frames = value.stacktrace?.frames ?? []
+			const kept = frames.slice(Math.ceil(frames.length / 2))
+			return kept.length === 0 ? { type: value.type, value: value.value } : { ...value, stacktrace: { frames: kept } }
+		})
+	}
+	return fitted
+}

package/src/jobs/report.ts

@@ -1,15 +1,21 @@
 // What the framework tells Operations, through the ingest every application already has (`FABRIKA_OPERATIONS_DSN`, the
-// Sentry envelope): a failed or missed job run, and a request that answered 5xx. Operations groups by the
-// fingerprint and raises its new-issue and regression alerts, so each kind of failure becomes one issue.
+// Sentry envelope): a failed or missed job run, a request that answered 5xx, and a process that crashed. Operations
+// groups a framework report by its fingerprint and raises its new-issue and regression alerts, so each kind of
+// failure becomes one issue. What was thrown travels scrubbed as the report's cause chain (ADR-0059).
+
+import { exceptionChain, type ReportedException } from './exception'
+import type { Scrubber } from './scrub'
 
 export interface OperationsReport {
 	/** Grouping in Operations: one issue per kind of problem and job or endpoint. */
 	readonly fingerprint: readonly string[]
 	/** The exception type Operations shows, e.g. `JobFailed`. */
 	readonly type: string
-	/** Framework-authored text only: fixed codes and declared names, never an application error's name or message. */
+	/** Framework-authored text only: fixed codes and declared names. What was thrown travels as `error`. */
 	readonly message: string
 	readonly tags: Readonly<Record<string, string>>
+	/** What was thrown, when something was: sent scrubbed as the cause chain of the framework's exception. */
+	readonly error?: unknown
 }
 
 export interface OperationsReporter {
@@ -43,18 +49,20 @@ export function operationsTarget(dsn: string): OperationsTarget | null {
 }
 
 /** The envelope's `logger`: which part of the framework reported. */
-export type ReportSource = 'fabrika.jobs' | 'fabrika.requests'
+export type ReportSource = 'fabrika.jobs' | 'fabrika.requests' | 'fabrika.process'
 
 export interface OperationsReporterOptions {
 	readonly target: OperationsTarget
 	readonly release: string | null
 	readonly environment: string | null
 	readonly source: ReportSource
+	/** What every text of a thrown value passes before it leaves the process. */
+	readonly scrubber: Scrubber
 	readonly fetch?: (request: Request) => Promise<Response>
 }
 
 /** Where the reports of one application environment go: the ingest of its DSN, its release and its environment. */
-export type OperationsSettings = Omit<OperationsReporterOptions, 'source' | 'fetch'>
+export type OperationsSettings = Omit<OperationsReporterOptions, 'source' | 'scrubber' | 'fetch'>
 
 /**
  * The settings of `FABRIKA_OPERATIONS_DSN`, `FABRIKA_RELEASE` and `FABRIKA_ENVIRONMENT`; `null` without a DSN. A DSN
@@ -75,12 +83,18 @@ export function operationsSettings(variables: Readonly<Record<string, string>>,
 
 const hexId = (): string => crypto.randomUUID().replaceAll('-', '')
 
+type EnvelopeOptions = Pick<OperationsReporterOptions, 'release' | 'environment' | 'source' | 'scrubber'>
+
+interface EventFields {
+	/** Absent: Operations groups by the last value's type and in-app frames. */
+	readonly fingerprint?: readonly string[]
+	readonly tags: Readonly<Record<string, string>>
+	/** Oldest cause first; the last value is the one Operations titles the issue by. */
+	readonly values: readonly ReportedException[]
+}
+
 /** The envelope of one error event: a header line, an item header line and the event. */
-export function reportEnvelope(
-	report: OperationsReport,
-	options: Pick<OperationsReporterOptions, 'release' | 'environment' | 'source'>,
-	now: Date,
-): string {
+function eventEnvelope(fields: EventFields, options: EnvelopeOptions, now: Date): string {
 	const { release, environment } = options
 	const eventId = hexId()
 	const event = {
@@ -89,39 +103,75 @@ export function reportEnvelope(
 		level: 'error',
 		platform: 'javascript',
 		logger: options.source,
-		fingerprint: [...report.fingerprint],
-		tags: { ...report.tags },
-		exception: { values: [{ type: report.type, value: report.message }] },
+		...(fields.fingerprint === undefined ? {} : { fingerprint: [...fields.fingerprint] }),
+		tags: { ...fields.tags },
+		exception: { values: [...fields.values] },
 		...(release === null ? {} : { release }),
 		...(environment === null ? {} : { environment }),
 	}
 	return [JSON.stringify({ event_id: eventId, sent_at: now.toISOString() }), JSON.stringify({ type: 'event' }), JSON.stringify(event), ''].join('\n')
 }
 
-export function operationsReporter(options: OperationsReporterOptions): OperationsReporter {
+/** A framework report: its own exception last, so the issue keeps the framework's title, after what was thrown. */
+export function reportEnvelope(report: OperationsReport, options: EnvelopeOptions, now: Date): string {
+	const cause = report.error === undefined ? [] : exceptionChain(report.error, options.scrubber)
+	return eventEnvelope(
+		{
+			fingerprint: report.fingerprint,
+			tags: report.tags,
+			values: [...cause, { type: report.type, value: report.message }],
+		},
+		options,
+		now,
+	)
+}
+
+/** How a process failed outside any request or job run. */
+export type CrashKind = 'uncaught_exception' | 'unhandled_rejection' | 'boot_failed'
+
+/** A crash: what was thrown is the issue itself, grouped by Operations from its type and in-app frames. */
+export function crashEnvelope(kind: CrashKind, error: unknown, options: EnvelopeOptions, now: Date): string {
+	return eventEnvelope({ tags: { crash: kind }, values: exceptionChain(error, options.scrubber) }, options, now)
+}
+
+async function deliver(options: OperationsReporterOptions, body: string): Promise<void> {
 	const send = options.fetch ?? ((request: Request) => fetch(request))
-	return {
-		async report(report) {
-			const request = new Request(options.target.envelopeUrl, {
-				method: 'POST',
-				headers: {
-					'content-type': 'application/x-sentry-envelope',
-					'x-sentry-auth': `Sentry sentry_version=7, sentry_key=${options.target.publicKey}`,
-				},
-				body: reportEnvelope(report, options, new Date()),
-				signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
-			})
-			try {
-				const response = await send(request)
-				await response.body?.cancel()
-				if (!response.ok) {
-					console.error(`fabrika: a report to Operations answered ${response.status}`)
-				}
-			} catch {
-				// The error may quote the ingest URL with its key.
-				console.error('fabrika: a report to Operations could not be delivered')
-			}
+	const request = new Request(options.target.envelopeUrl, {
+		method: 'POST',
+		headers: {
+			'content-type': 'application/x-sentry-envelope',
+			'x-sentry-auth': `Sentry sentry_version=7, sentry_key=${options.target.publicKey}`,
 		},
+		body,
+		signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+	})
+	try {
+		const response = await send(request)
+		await response.body?.cancel()
+		if (!response.ok) {
+			console.error(`fabrika: a report to Operations answered ${response.status}`)
+		}
+	} catch {
+		// The error may quote the ingest URL with its key.
+		console.error('fabrika: a report to Operations could not be delivered')
+	}
+}
+
+export function operationsReporter(options: OperationsReporterOptions): OperationsReporter {
+	return {
+		report: (report) => deliver(options, reportEnvelope(report, options, new Date())),
+	}
+}
+
+export interface CrashReporter {
+	/** Never throws: a report that cannot be delivered is one log line. */
+	report(kind: CrashKind, error: unknown): Promise<void>
+}
+
+export function crashReporter(options: Omit<OperationsReporterOptions, 'source'>): CrashReporter {
+	const reporting: OperationsReporterOptions = { ...options, source: 'fabrika.process' }
+	return {
+		report: (kind, error) => deliver(reporting, crashEnvelope(kind, error, reporting, new Date())),
 	}
 }
 

package/src/jobs/runner.ts

@@ -50,7 +50,7 @@ const UNIT_MS: Readonly<Record<string, number>> = { s: 1_000, m: 60_000, h: 3_60
 
 /**
  * Why a run failed. Fixed codes only: an application error's name and message may carry a secret, so neither is
- * ever logged, returned or reported.
+ * ever logged or returned. Only the report to Operations carries them, scrubbed (ADR-0059).
  */
 export type JobFailureCode =
 	| 'timeout'
@@ -516,6 +516,8 @@ async function runLeased(
 interface JobFailure {
 	readonly code: JobFailureCode
 	readonly why: FailureReason | null
+	/** What the attempt threw, which only the report carries, scrubbed (ADR-0059); never a log line or the result. */
+	readonly thrown?: unknown
 }
 
 const failure = (code: JobFailureCode): JobFailure => ({ code, why: null })
@@ -531,7 +533,13 @@ async function failed(job: { readonly name: string }, attempts: number, outcome:
 	if (why !== null) {
 		tags['reason'] = why.reason
 	}
-	await reporter.report({ fingerprint: ['fabrika-job-failed', job.name], type: 'JobFailed', message, tags })
+	await reporter.report({
+		fingerprint: ['fabrika-job-failed', job.name],
+		type: 'JobFailed',
+		message,
+		tags,
+		...('thrown' in outcome ? { error: outcome.thrown } : {}),
+	})
 	return why === null ? { status: 'failed', attempts, code } : { status: 'failed', attempts, code, reason: why.reason }
 }
 
@@ -630,7 +638,9 @@ function failureOf(error: unknown): JobFailure {
 		return failure('lease_lost')
 	}
 	const code = failureCode(error)
-	return code === 'query_refused' || code === 'capability_refused' ? { code, why: failureReason(error) } : failure('handler_failed')
+	return code === 'query_refused' || code === 'capability_refused'
+		? { code, why: failureReason(error), thrown: error }
+		: { code: 'handler_failed', why: null, thrown: error }
 }
 
 function jobContext(

package/src/jobs/scrub.ts

@@ -0,0 +1,98 @@
+// What an error report must not carry (ADR-0059): the values of the application's secrets, and anything shaped like a
+// credential — a JWT, an `Authorization` scheme or header, a URL's userinfo, a sensitive query parameter.
+
+import { FABRIKA_CONTRACT_DIGEST, FABRIKA_IAM_APP_ID, FABRIKA_IAM_ISSUER } from '@fabrika/auth-core'
+import type { CapturedEnvironment } from '../implement/environment'
+
+export const REDACTED = '[redacted]'
+
+/** A shorter value is no credential the platform generates, and scrubbing it would mangle ordinary text. */
+export const MIN_SECRET_LENGTH = 8
+
+/** The framework variables that are public by design; every other `FABRIKA_*` value is treated as a secret. */
+const PUBLIC_FRAMEWORK_VARIABLES: ReadonlySet<string> = new Set([
+	'FABRIKA_RELEASE',
+	'FABRIKA_APP_ID',
+	'FABRIKA_ENVIRONMENT',
+	'FABRIKA_IAM_RPC_URL',
+	FABRIKA_CONTRACT_DIGEST,
+	FABRIKA_IAM_APP_ID,
+	FABRIKA_IAM_ISSUER,
+])
+
+/**
+ * An application variable whose name says it holds a secret. The runtime does not know which names the application
+ * declared as secrets, so the name decides (backlog 176).
+ */
+const SECRET_NAME = /secret|token|passw|private|credential|key|auth|dsn|salt|connection|cookie|session|signature|cert/i
+
+const JWT = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g
+const AUTHORIZATION_SCHEME = /\b(Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{8,}/gi
+const CREDENTIAL_HEADER = /\b(authorization|proxy-authorization|cookie|set-cookie|x-fabrika-token|x-api-key)(["']?\s*[:=]\s*["']?)[^\s"',;]+/gi
+const URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/?#@]*@/gi
+const SENSITIVE_QUERY_PARAMETER = /([?&][^=&#\s]*(?:token|key|secret|passw|signature|sig|auth|code|session|credential)[^=&#\s]*=)[^&#\s"'<>]*/gi
+
+export interface Scrubber {
+	scrub(text: string): string
+}
+
+function urlCredentials(value: string): string[] {
+	let url: URL
+	try {
+		url = new URL(value)
+	} catch {
+		return []
+	}
+	return [url.username, url.password].flatMap((part) => {
+		const decoded = safeDecode(part)
+		return decoded === part ? [part] : [part, decoded]
+	})
+}
+
+function safeDecode(part: string): string {
+	try {
+		return decodeURIComponent(part)
+	} catch {
+		return part
+	}
+}
+
+/** Every value of `environment` that is a secret, with the user and password of a URL-shaped one. */
+export function secretValues(environment: CapturedEnvironment): string[] {
+	const values: string[] = []
+	for (const [name, value] of Object.entries(environment.framework)) {
+		if (!PUBLIC_FRAMEWORK_VARIABLES.has(name)) {
+			values.push(value, ...urlCredentials(value))
+		}
+	}
+	for (const [name, value] of Object.entries(environment.application)) {
+		if (typeof value === 'string' && SECRET_NAME.test(name)) {
+			values.push(value, ...urlCredentials(value))
+		}
+	}
+	const kept = values.map((value) => value.trim()).filter((value) => value.length >= MIN_SECRET_LENGTH)
+	// The longest first, so a value that contains another is replaced whole.
+	return [...new Set(kept)].sort((a, b) => b.length - a.length)
+}
+
+export function secretScrubber(secrets: readonly string[]): Scrubber {
+	return {
+		scrub(text) {
+			let scrubbed = text
+			for (const secret of secrets) {
+				scrubbed = scrubbed.replaceAll(secret, REDACTED)
+			}
+			return scrubbed
+				.replace(JWT, REDACTED)
+				.replace(AUTHORIZATION_SCHEME, `$1 ${REDACTED}`)
+				.replace(CREDENTIAL_HEADER, `$1$2${REDACTED}`)
+				.replace(URL_USERINFO, `$1${REDACTED}@`)
+				.replace(SENSITIVE_QUERY_PARAMETER, `$1${REDACTED}`)
+		},
+	}
+}
+
+/** The scrubber of one application environment: its secrets' values, then the credential patterns. */
+export function environmentScrubber(environment: CapturedEnvironment): Scrubber {
+	return secretScrubber(secretValues(environment))
+}