@fabrika/app 0.8.2 → 0.9.0-cloudflare.1

package/src/dev/output.ts

@@ -0,0 +1,72 @@
+// The launcher's view of output: every line of the application and of the commands it runs is forwarded to its own
+// stream, as Zerops' runtime log reads it, and the newest lines are kept to report. Secret values never reach either.
+
+import { DEV_REPORT_MAX_LINE_CHARACTERS, type DevLogLine } from './wire.js'
+
+export type OutputStream = DevLogLine['stream']
+
+export interface OutputSink {
+	write(stream: OutputStream, line: string): void
+}
+
+/** The launcher process's own stdout and stderr. */
+export const processOutput: OutputSink = {
+	write(stream, line) {
+		;(stream === 'stdout' ? process.stdout : process.stderr).write(`${line}\n`)
+	},
+}
+
+/**
+ * The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. A
+ * mark starts the lines a report carries: those of the newest sync or reset, and the output after it.
+ */
+export class OutputRing {
+	private readonly lines: DevLogLine[] = []
+	private next = 0
+	private marked = 0
+
+	constructor(private readonly capacity: number, private readonly secrets: readonly string[], private readonly sink: OutputSink) {}
+
+	push(stream: OutputStream, text: string): void {
+		const line = this.redact(text)
+		this.sink.write(stream, line)
+		this.lines.push({ n: this.next, stream, text: line.slice(0, DEV_REPORT_MAX_LINE_CHARACTERS) })
+		this.next += 1
+		if (this.lines.length > this.capacity) this.lines.shift()
+	}
+
+	/** Report from the next line on: the lines before it belong to an older head. */
+	mark(): void {
+		this.marked = this.next
+	}
+
+	/** The newest `count` lines since the mark, oldest first. */
+	tail(count: number): DevLogLine[] {
+		const since = this.lines.filter((line) => line.n >= this.marked)
+		return since.slice(Math.max(0, since.length - count))
+	}
+
+	private redact(text: string): string {
+		let line = text
+		for (const secret of this.secrets) line = line.replaceAll(secret, '[redacted]')
+		return line
+	}
+}
+
+/** Feed `stream` to `onLine` one line at a time; a last line without a newline is fed when the stream ends. */
+export async function readLines(stream: ReadableStream<Uint8Array>, onLine: (line: string) => void): Promise<void> {
+	const decoder = new TextDecoder()
+	const reader = stream.getReader()
+	let pending = ''
+	for (let read = await reader.read(); !read.done; read = await reader.read()) {
+		pending += decoder.decode(read.value, { stream: true })
+		let end = pending.indexOf('\n')
+		while (end !== -1) {
+			onLine(pending.slice(0, end).replace(/\r$/, ''))
+			pending = pending.slice(end + 1)
+			end = pending.indexOf('\n')
+		}
+	}
+	pending += decoder.decode()
+	if (pending !== '') onLine(pending)
+}

package/src/dev/wire.ts

@@ -0,0 +1,136 @@
+// The wire of the platform transport's source receiver (ADR-0064): what the launcher of a `dev` environment asks
+// Control and what it reports back. Both sides import it, so the shapes and the one parser of each message cannot drift
+// apart. Runtime-neutral: zod and Web APIs only.
+
+import { z } from 'zod/v4'
+
+/** The long poll under the receiver's URL (`FABRIKA_PLATFORM_SOURCE_URL`). */
+export const DEV_SOURCE_WAIT_PATH = '/platform/source/wait'
+/** Where the launcher reports what it serves. */
+export const DEV_SOURCE_REPORT_PATH = '/platform/source/report'
+
+/** How long Control holds a wait before it answers `idle`: below every proxy's idle timeout on the way. */
+export const DEV_SOURCE_WAIT_MS = 25_000
+
+/** The most log lines one report carries, and the longest line. */
+export const DEV_REPORT_MAX_LINES = 200
+export const DEV_REPORT_MAX_LINE_CHARACTERS = 2_000
+export const DEV_REPORT_MAX_MESSAGE_CHARACTERS = 500
+
+const commitSha = z.string().regex(/^[0-9a-f]{40}$/)
+const generation = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER)
+
+/**
+ * Repository-relative with forward slashes: no leading slash, no backslash, no empty, `.` or `..` segment, no control
+ * character. The launcher writes these paths under its root, so nothing it receives may name a path outside it.
+ */
+export function isSourcePath(path: string): boolean {
+	return path.length > 0 && path.length <= 512 && !path.startsWith('/') && !path.includes('\\')
+		&& ![...path].some((character) => character.charCodeAt(0) <= 0x1f || character.charCodeAt(0) === 0x7f)
+		&& path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
+}
+
+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. */
+	reset: generation.nullable(),
+	/** The check request it ran last; null as for `reset`. */
+	checks: generation.nullable(),
+	/** False at boot: answer at once, so the launcher reconciles before it serves. */
+	hold: z.boolean(),
+}).strict()
+
+export type DevWaitRequest = z.infer<typeof devWaitRequestSchema>
+
+/** One changed file at the target commit; `content` null deletes it. */
+export const devSourceFileSchema = z.object({ path: sourcePath, content: z.string().nullable() }).strict()
+
+export type DevSourceFile = z.infer<typeof devSourceFileSchema>
+
+/** The files that bring the container from `from` to `to`. */
+export const devSyncSchema = z.object({ from: commitSha, to: commitSha, files: z.array(devSourceFileSchema) }).strict()
+
+export type DevSync = z.infer<typeof devSyncSchema>
+
+/**
+ * What to do. `sync` is null when the container holds the recorded head (or a head it refused). `reset` and `checks` are
+ * the environment's current generations: one past what the container applied asks it to reset its schema, or to run
+ * the check chain.
+ */
+export const devWaitAnswerSchema = z.object({ sync: devSyncSchema.nullable(), reset: generation, checks: generation }).strict()
+
+export type DevWaitAnswer = z.infer<typeof devWaitAnswerSchema>
+
+export const DEV_STATUSES = ['syncing', 'serving', 'failed', 'needs_bootstrap', 'resetting', 'checking'] as const
+
+export type DevStatus = (typeof DEV_STATUSES)[number]
+
+export const devLogLineSchema = z.object({
+	/** The line's number in the launcher's output since it started; it only grows. */
+	n: z.number().int().min(0),
+	stream: z.enum(['stdout', 'stderr']),
+	text: z.string().max(DEV_REPORT_MAX_LINE_CHARACTERS),
+}).strict()
+
+export type DevLogLine = z.infer<typeof devLogLineSchema>
+
+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()
+
+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),
+	/** The commit the launcher is syncing to or refused; null when it has none. */
+	target: commitSha.nullable(),
+	/** One line: why a sync was refused or failed. */
+	message: z.string().max(DEV_REPORT_MAX_MESSAGE_CHARACTERS).nullable(),
+	/** 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(),
+	/** 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>
+
+/** The body of a wait as JSON text. */
+export function encodeDevWaitRequest(request: DevWaitRequest): string {
+	return JSON.stringify(devWaitRequestSchema.parse(request))
+}
+
+/** The body of a report as JSON text. */
+export function encodeDevReport(report: DevReport): string {
+	return JSON.stringify(devReportSchema.parse(report))
+}
+
+export type DevParse<T> = { readonly ok: true; readonly value: T } | { readonly ok: false }
+
+function parseWith<T>(schema: z.ZodType<T>, json: unknown): DevParse<T> {
+	const parsed = schema.safeParse(json)
+	return parsed.success ? { ok: true, value: parsed.data } : { ok: false }
+}
+
+/** The one parser of a wait request; a field this release does not know is refused, never dropped. */
+export const parseDevWaitRequest = (json: unknown): DevParse<DevWaitRequest> => parseWith(devWaitRequestSchema, json)
+export const parseDevWaitAnswer = (json: unknown): DevParse<DevWaitAnswer> => parseWith(devWaitAnswerSchema, json)
+export const parseDevReport = (json: unknown): DevParse<DevReport> => parseWith(devReportSchema, json)

package/src/files/archive.ts

@@ -4,7 +4,7 @@
 // stored or deflated entries, no encryption, a layout in which every byte belongs to an entry or the directory, sizes
 // and CRCs that match, bounded counts and sizes, and nested ZIPs to a small depth. Any other archive is refused.
 
-import { inflateRawSync } from 'node:zlib'
+import { crc32, inflateRawSync } from 'node:zlib'
 
 export const ARCHIVE_LIMITS = {
 	/** Entries of one archive, nested ones counted with their parent's. */
@@ -236,7 +236,7 @@ function unpacked(entry: Entry, data: Uint8Array, budget: Budget): Uint8Array {
 			throw new Refused('malformed')
 		}
 	}
-	if (content.length !== entry.uncompressed || Bun.hash.crc32(content) !== entry.crc) throw new Refused('malformed')
+	if (content.length !== entry.uncompressed || crc32(content) !== entry.crc) throw new Refused('malformed')
 	return content
 }
 

package/src/files/job-names.ts

@@ -0,0 +1,12 @@
+// The framework's own file jobs, in a module of their own: the build recipe schedules them without the file stack.
+
+/** The reserved name of the scan job: a `c.cron` job name cannot contain `-`, so no application job takes it. */
+export const FILE_SCAN_JOB = 'fabrika-file-scan'
+export const FILE_SCAN_SCHEDULE = '* * * * *'
+
+/**
+ * The framework's sweep job: hourly, it deletes the files no declared column references and the pending ones past the
+ * grace, so none waits for the next request. A reserved name with `-`, which no `c.cron` name can take.
+ */
+export const FILE_SWEEP_JOB = 'fabrika-file-sweep'
+export const FILE_SWEEP_SCHEDULE = '41 * * * *'

package/src/files/kinds.ts

@@ -29,13 +29,7 @@ import { bytesAreOfType, SNIFF_BYTES, SNIFFABLE_TYPES } from './sniff'
 import { cleanName, digesting, isNamed, readExactly, readHead } from './streams'
 import { FileDownload } from './treatment'
 
-/**
- * The framework's sweep job: hourly, it deletes the files no declared column references and the pending ones past the
- * grace, so none waits for the next request. A reserved name with `-`, which no `c.cron` name can take;
- * `@fabrika/provider-zerops` writes it into the crontab on this schedule (`ZEROPS_FILE_SWEEP_JOB`).
- */
-export const FILE_SWEEP_JOB = 'fabrika-file-sweep'
-export const FILE_SWEEP_SCHEDULE = '41 * * * *'
+export { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE } from './job-names'
 export const FILE_SWEEP_TIMEOUT_MS = 10 * 60_000
 /** How long a staged file waits for its first reference before the sweep may delete it. */
 export const FILE_PENDING_GRACE_MS = 60 * 60 * 1000
@@ -67,6 +61,7 @@ export class FileWork {
 	readonly holder: object
 	readonly request: string
 	readonly #staged: string[] = []
+	readonly #written = new Map<string, string>()
 
 	constructor(holder: object, request: string) {
 		this.holder = holder
@@ -77,9 +72,18 @@ export class FileWork {
 		this.#staged.push(id)
 	}
 
+	/** The work wrote the object of a file it staged, under a key no other file has. */
+	wrote(id: string, objectKey: string): void {
+		this.#written.set(id, objectKey)
+	}
+
 	get stagedIds(): readonly string[] {
 		return [...this.#staged]
 	}
+
+	writtenKey(id: string): string | null {
+		return this.#written.get(id) ?? null
+	}
 }
 
 interface Kind {
@@ -188,6 +192,7 @@ export class StoredFileKinds {
 		const body = digesting(stream, null)
 		try {
 			const { size } = await this.#store.write(objectKey, body.stream, { contentType: type, maxBytes: artifact.maxBytes })
+			work.wrote(id, objectKey)
 			const sha256 = body.digest()
 			await this.#files.written(id, { size, sha256 })
 			return fileReference({ id, kind: kind.name, name, type, size, status: 'pending' }, work.holder, true)
@@ -212,6 +217,13 @@ export class StoredFileKinds {
 		try {
 			const objectKey = await this.#files.abandon(id, work.request)
 			if (objectKey === null) {
+				// On SQLite the pending row is written in the work's own transaction and rolled back with it, so only the
+				// work knows the object; a row still there is a file something claimed, whose object stays.
+				const written = work.writtenKey(id)
+				if (written !== null && (await this.#files.find(id)) === null) {
+					step = 'object_delete_failed'
+					await this.#store.delete(written)
+				}
 				return
 			}
 			step = 'object_delete_failed'

package/src/files/scan.ts

@@ -7,13 +7,12 @@
 
 import type { QuarantinedStoredFile } from '@fabrika/db/framework'
 import type { FileObjectStore } from '@fabrika/platform'
+import { createHash } from 'node:crypto'
 import type { OperationsReporter } from '../jobs/report'
 import { type ArchiveRefusal, checkArchive } from './archive'
 import { ZIP_TYPES } from './sniff'
 
-/** The reserved name of the scan job: a `c.cron` job name cannot contain `-`, so no application job takes it. */
-export const FILE_SCAN_JOB = 'fabrika-file-scan'
-export const FILE_SCAN_SCHEDULE = '* * * * *'
+export { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE } from './job-names'
 
 export const SCAN_LIMITS = {
 	/** One pass scans at most this many files, and at most `batchBytes` of them; the next pass takes the rest. */
@@ -181,7 +180,7 @@ class ScanPass {
 		}
 		const bytes = object.size === file.size ? await readExactly(object.body, file.size, signal) : null
 		if (object.size !== file.size) await object.body.cancel()
-		if (bytes === null || new Bun.CryptoHasher('sha256').update(bytes).digest('hex') !== file.sha256) {
+		if (bytes === null || createHash('sha256').update(bytes).digest('hex') !== file.sha256) {
 			if (!signal.aborted) this.#states.set(file.id, { kind: 'mismatch' })
 			throw new Error('the object differs from its upload')
 		}

package/src/files/streams.ts

@@ -1,6 +1,8 @@
 // The byte streams of a stored file on its way in and out: the head the sniff reads, the digest and the deadline of a
 // write, the exact read of a file a site opens, and the client's file name as metadata.
 
+import { createHash } from 'node:crypto'
+
 const MAX_NAME_CODE_POINTS = 255
 
 /** The client's file name, metadata only: at most 255 code points, never half a character, no control characters. */
@@ -62,7 +64,7 @@ export function digesting(body: ReadableStream<Uint8Array>, timeoutMs: number |
 	timedOut(): boolean
 	stop(): void
 } {
-	const hasher = new Bun.CryptoHasher('sha256')
+	const hasher = createHash('sha256')
 	let timer: ReturnType<typeof setTimeout> | undefined
 	let expired = false
 	const stream = body.pipeThrough(

package/src/implement/anonymous.ts

@@ -4,7 +4,7 @@
 
 import { LINK_BOOTSTRAP_FILE, SHARE_KEY_GLOBAL } from '../contract/defaults'
 import { HttpError } from '../errors'
-import { readBoundedBytes } from './bounded'
+import { deadline, readBoundedBytes } from './bounded'
 
 /** The slowest body a procedure waits for, in bytes per second: its deadline is `maxBytes` at this rate, 30 s at least. */
 export const BODY_RATE_FLOOR = 16 * 1024
@@ -36,6 +36,16 @@ export async function readBoundedBody(request: Request, maxBytes: number, deadli
 	return body
 }
 
+/** `readBoundedBody` within the deadline `maxBytes` derives; the deadline ends with the read. */
+export async function readBodyInTime(request: Request, maxBytes: number): Promise<Uint8Array<ArrayBuffer>> {
+	const timer = deadline(bodyDeadlineMs(maxBytes))
+	try {
+		return await readBoundedBody(request, maxBytes, timer.signal)
+	} finally {
+		timer.clear()
+	}
+}
+
 /** What a request answers whose body did not arrive whole: nobody reads it, and no failure is reported. */
 export function abortedBody(): HttpError {
 	return new HttpError(400, 'aborted', 'The body could not be read to its end')

package/src/implement/boot.ts

@@ -17,13 +17,21 @@ import {
 	FABRIKA_IAM_APP_ID,
 	FABRIKA_PROXY_SECRET,
 	type IamMembershipRpc,
+	type IamTerminalRpc,
 	isLoopbackHost,
 	type Jwks,
 	parseAppEnvironmentId,
 } from '@fabrika/auth-core'
 import type { Database } from '@fabrika/db'
 import type { CapabilityAuthority } from '@fabrika/db/capability'
-import { bindScopedDatabase, type DataAccess, dataAccessOf, type FrameworkTables, frameworkTablesOf, isScopedDatabase } from '@fabrika/db/framework'
+import {
+	bindScopedDatabaseProvisionally,
+	type DataAccess,
+	dataAccessOf,
+	type FrameworkTables,
+	frameworkTablesOf,
+	isScopedDatabase,
+} from '@fabrika/db/framework'
 import type { DataKind } from '@fabrika/db/tables'
 import type { EmailProviderRegistry } from '@fabrika/email'
 import { builtinEmailProviders } from '@fabrika/email/providers'
@@ -101,6 +109,11 @@ export interface BootOptions {
 	 * creates scopes, manages members or issues share links does not boot.
 	 */
 	readonly membership?: IamMembershipRpc
+	/**
+	 * IAM's identification operations at a terminal (ADR-0067): the IAM binding on Cloudflare, `HttpIamTerminals`
+	 * elsewhere. Without it, a contract that declares a terminal does not boot.
+	 */
+	readonly terminals?: IamTerminalRpc
 	/**
 	 * Cloudflare service bindings to the owners' proxy Workers, by binding name (`FABRIKA_CONNECT_<IMPORT>`). An import
 	 * without one calls its owner with `fetch`.
@@ -262,6 +275,23 @@ function readProxySecret(framework: Readonly<Record<string, string>>, required:
 	return proxySecretDigest(secret)
 }
 
+/** What an application's SQLite database (a Durable Object's, ADR-0065) cannot serve: raw SQL and a scanning file kind. */
+function sqliteProblems(artifact: ContractArtifact, database: Database | undefined, problems: string[]): void {
+	if (database?.dialect !== 'sqlite') {
+		return
+	}
+	for (const [site, reach] of Object.entries(artifact.declared ?? {})) {
+		if (reach.sql !== null) {
+			problems.push(`'${site}' declares sql: '${reach.sql}'; ctx.sql runs only on Postgres, and this application's database is SQLite (Cloudflare)`)
+		}
+	}
+	for (const [name, kind] of Object.entries(artifact.fileKinds ?? {})) {
+		if (kind.scan === true) {
+			problems.push(`files '${name}' declares scan: true; no malware scanner runs on Cloudflare, so a scanning file kind is not served there`)
+		}
+	}
+}
+
 /** What this version cannot serve yet; a contract that declares it does not boot rather than answer nothing. */
 function unservable(
 	artifact: ContractArtifact,
@@ -350,6 +380,8 @@ interface BoundDatabase {
 	readonly framework: FrameworkTables | null
 	/** The mini-ORM behind a staged-kit site's `ctx.db`; only a `scoped(tables)` layer has it. */
 	readonly data: DataAccess | null
+	/** Disconnects a `scoped(tables)` layer this boot bound; `null` for any other database. */
+	readonly release: (() => void) | null
 }
 
 /**
@@ -367,7 +399,7 @@ function contractDatabase(
 	}
 	if (!isScopedDatabase(database)) {
 		if ('locate' in database) {
-			return { database, framework: null, data: null }
+			return { database, framework: null, data: null, release: null }
 		}
 		problems.push('serve(contract, { database }) takes the scoped(tables) result of @fabrika/db itself, not a copy or a wrapper of it')
 		return null
@@ -377,8 +409,8 @@ function contractDatabase(
 		return null
 	}
 	try {
-		const locate = bindScopedDatabase(database, { database: connection, capabilities, readOnly: requestIsReadOnly })
-		return { database: { tables: database.tables, locate }, framework: frameworkTablesOf(database), data: dataAccessOf(database) }
+		const { locate, release } = bindScopedDatabaseProvisionally(database, { database: connection, capabilities, readOnly: requestIsReadOnly })
+		return { database: { tables: database.tables, locate }, framework: frameworkTablesOf(database), data: dataAccessOf(database), release }
 	} catch {
 		problems.push('the data layer was bound before boot; only the framework binds it, so remove @fabrika/db/framework from the application')
 		return null
@@ -651,11 +683,28 @@ function runtimePurposes(contract: AnyContract, artifact: ContractArtifact): Rea
 }
 
 export function boot(app: ContractImplementation, options: BootOptions): ContractApp {
+	const binding: Binding = { release: null }
+	try {
+		return bootOnce(app, options, binding)
+	} catch (error) {
+		// A failed boot releases the data layer it bound, so a later boot of the same application binds it again.
+		binding.release?.()
+		throw error
+	}
+}
+
+/** What `bootOnce` bound: released when the boot fails, kept when it succeeds. */
+interface Binding {
+	release: (() => void) | null
+}
+
+function bootOnce(app: ContractImplementation, options: BootOptions, binding: Binding): ContractApp {
 	const problems: string[] = []
 	installEgressGuard()
 	// What a handler reaches through these is the platform's own request, which no site's egress covers.
 	const objects = options.files === undefined ? undefined : platformFacility(options.files)
 	const membershipRpc = options.membership === undefined ? undefined : platformFacility(options.membership)
+	const terminalRpc = options.terminals === undefined ? undefined : platformFacility(options.terminals)
 	const workloadTokens = options.workloadTokens === undefined ? undefined : platformFacility(options.workloadTokens)
 	const variables = readFramework(options.environment.framework, app.contract.vocabulary.app, problems)
 	const artifact = compileContract(app.contract, app.database?.tables ?? {})
@@ -673,10 +722,12 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 	const owned = new Set(Object.values(artifact.tables).flatMap((table) => table.scope.mode === 'dimension' ? [table.scope.dimension] : []))
 	const containers = containersOf(artifact)
 	unservable(artifact, options.assets, owned, containers, problems)
+	sqliteProblems(artifact, options.database, problems)
 	// This runtime's own: what another `boot` call mints, application code's included, its stores refuse.
 	const issuer = createCapabilityIssuer()
 	const fileKinds = storedFileKinds(artifact, app.database, objects, problems)
 	const bound = contractDatabase(app.database, options.database, issuer.authority, problems)
+	binding.release = bound?.release ?? null
 	const framework = bound?.framework ?? null
 	frameworkProblems(artifact, framework, problems)
 	const database = bound?.database ?? null
@@ -896,6 +947,11 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 	if (site !== undefined && data === null) {
 		problems.push(`'${site.row.id}' reaches data through ctx.db, which runs on @fabrika/db: pass serve(contract, { database: scoped(tables) })`)
 	}
+	if (artifact.terminal !== undefined && options.terminals === undefined) {
+		problems.push(
+			'the contract declares a terminal, and the runtime adapter supplies no IAM transport for its identifications (the IAM binding on Cloudflare; FABRIKA_IAM_RPC_URL and FABRIKA_IAM_RPC_KEY on Bun)',
+		)
+	}
 	const asking = [...endpoints.values()].find(asksIam)
 	if (asking !== undefined && options.membership === undefined) {
 		problems.push(
@@ -919,6 +975,7 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 		containers,
 		assets: options.assets ?? null,
 		membership,
+		terminals: artifact.terminal === undefined ? null : (terminalRpc ?? null),
 		framework,
 		mint: issuer.mint,
 		capabilities: issuer.authority,

package/src/implement/bounded.ts

@@ -8,9 +8,28 @@
  */
 export const REQUEST_BUDGET_MS = 10_000
 
+/** A signal that aborts once its time passed, and a `clear` its work calls when it settles. */
+export interface Deadline {
+	readonly signal: AbortSignal
+	clear(): void
+}
+
+/**
+ * Aborts like `AbortSignal.timeout(ms)`, or when `parent` aborts. Its timer is cleared by `clear`, which every caller
+ * runs in `finally`: workerd counts a pending timer as work, so an uncleared one keeps a Durable Object awake.
+ */
+export function deadline(ms: number, parent?: AbortSignal): Deadline {
+	const controller = new AbortController()
+	const timer = setTimeout(() => controller.abort(new DOMException('The operation timed out.', 'TimeoutError')), ms)
+	return {
+		signal: parent === undefined ? controller.signal : AbortSignal.any([parent, controller.signal]),
+		clear: () => clearTimeout(timer),
+	}
+}
+
 /** A handler's `ctx.signal`: aborted when the client leaves (`request.signal`) or once `budgetMs` passed. */
-export function handlerSignal(request: Request, budgetMs: number = REQUEST_BUDGET_MS): AbortSignal {
-	return AbortSignal.any([request.signal, AbortSignal.timeout(budgetMs)])
+export function handlerSignal(request: Request, budgetMs: number = REQUEST_BUDGET_MS): Deadline {
+	return deadline(budgetMs, request.signal)
 }
 
 export interface BoundedRead {

package/src/implement/capability.ts

@@ -269,14 +269,18 @@ export class Within<D extends string, A extends string> implements WithinCapabil
 		principal: string,
 		values: readonly string[] | 'all',
 		containers: readonly ContainerGrant[],
+		contained: readonly ContainerGrant[],
 	) {
 		if (token !== MINT) {
 			throw new CapabilityRefusedError('not_minted', 'a Within is minted by the framework only; declare the access form in fabrika.contract.ts')
 		}
 		const held = values === 'all' ? freeze([]) : containerGrantsOf(containers)
+		const inside = values === 'all' ? freeze([]) : containerGrantsOf(contained)
 		let count = values === 'all' ? 0 : values.length
-		for (let index = 0; index < held.length; index++) {
-			count += held[index]?.values.length ?? 0
+		for (const group of [held, inside]) {
+			for (let index = 0; index < group.length; index++) {
+				count += group[index]?.values.length ?? 0
+			}
 		}
 		if (count > MAX_WITHIN_VALUES) {
 			throw new CapabilityLimitError(
@@ -292,6 +296,7 @@ export class Within<D extends string, A extends string> implements WithinCapabil
 			principal,
 			values: values === 'all' ? 'all' : copyOf(values),
 			containers: held,
+			contained: inside,
 		})
 		this.#frame = frame
 		this.#issuer = issuer
@@ -315,6 +320,11 @@ export class Within<D extends string, A extends string> implements WithinCapabil
 		return this.#grant.containers
 	}
 
+	/** The dimensions inside this one in which the caller holds the action: `note → [n1]` for a workspace list. */
+	get contained(): readonly ContainerGrant[] {
+		return this.#grant.contained
+	}
+
 	static {
 		readWithin = (value) =>
 			typeof value === 'object' && value !== null && #grant in value ? { grant: value.#grant, frame: value.#frame, issuer: value.#issuer } : undefined
@@ -434,6 +444,7 @@ export interface CapabilityMint {
 		principal: string,
 		values: readonly string[] | 'all',
 		containers?: readonly ContainerGrant[],
+		contained?: readonly ContainerGrant[],
 	): Within<D, A>
 	app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>
 }
@@ -469,8 +480,9 @@ export function createCapabilityIssuer(): CapabilityIssuer {
 			principal: string,
 			values: readonly string[] | 'all',
 			containers: readonly ContainerGrant[] = [],
+			contained: readonly ContainerGrant[] = [],
 		): Within<D, A> {
-			return new Within(MINT, issuer, frame, dimension, action, principal, values, containers)
+			return new Within(MINT, issuer, frame, dimension, action, principal, values, containers, contained)
 		},
 		app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A> {
 			return new AppCapability(MINT, issuer, frame, action, principal)