@fabrika/provider-contract 0.8.2 → 0.9.0-cloudflare.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-contract",
-	"version": "0.8.2",
+	"version": "0.9.0-cloudflare.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,18 +12,29 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./installation": {
 			"bun": "./src/installation.ts",
-			"types": "./src/installation.ts",
+			"types": "./types/src/installation.d.ts",
 			"default": "./src/installation.ts"
+		},
+		"./app-cli": {
+			"bun": "./src/app-cli.ts",
+			"types": "./types/src/app-cli.d.ts",
+			"default": "./src/app-cli.ts"
+		},
+		"./conformance": {
+			"bun": "./src/conformance.ts",
+			"types": "./types/src/conformance.d.ts",
+			"default": "./src/conformance.ts"
 		}
 	},
 	"scripts": {
@@ -31,6 +42,7 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "0.8.2"
+		"@fabrika/auth-core": "0.9.0-cloudflare.1",
+		"@fabrika/proxy-core": "0.9.0-cloudflare.1"
 	}
 }

package/src/app-cli.ts

@@ -0,0 +1,81 @@
+// What a provider's `/cli` module offers the `fabrika` command for an application: `app build`, `app deploy`,
+// `app register` and `fabrika namespace`. The command loads the module by the provider's id and never branches on it.
+
+import type { ProviderDeploymentNamespace, ProviderNamespacePlan } from './control'
+
+/** The runtime a contract application's generated entry is written for (`@fabrika/app/build`'s `EntryRuntime`). */
+export type AppEntryRuntime = 'bun' | 'cloudflare'
+
+/** What a namespace command asks of Control. The `fabrika` command holds the Control origin, the credential and the transport. */
+export interface NamespaceControl {
+	create(namespace: ProviderDeploymentNamespace): Promise<unknown>
+	adopt(namespace: ProviderDeploymentNamespace): Promise<unknown>
+	reconcile(namespaceId: string): Promise<unknown>
+}
+
+/** A plan, or the namespace Control answered with; the `fabrika` command validates and prints either. */
+export type NamespaceCommandResult = { readonly plan: ProviderNamespacePlan } | { readonly namespace: unknown }
+
+export interface NamespaceCommandContext {
+	readonly source: Readonly<Record<string, string | undefined>>
+	/** Reads the Control origin and credential, and throws when either is missing: call it after every other input is checked. */
+	control(): NamespaceControl
+}
+
+export interface NamespaceCli {
+	readonly usage: string
+	/** `argv` is the command's own arguments, without the router's `--provider` and `--json`. */
+	run(subcommand: string, argv: readonly string[], context: NamespaceCommandContext): Promise<NamespaceCommandResult>
+}
+
+export interface AppCli {
+	readonly provider: string
+	readonly entryRuntime: AppEntryRuntime
+	/** `fabrika app build`, after the command wrote a contract application's entry; `contract` says whether it did. */
+	build?(argv: readonly string[], context: { readonly contract: boolean }): Promise<void>
+	deploy?(argv: readonly string[]): Promise<void>
+	/** The text `fabrika app register` hands Control: the application's manifest for one environment. */
+	registrationManifest?(options: { readonly config: string; readonly env: string }): Promise<string>
+	readonly namespaces?: NamespaceCli
+}
+
+export interface AppCliModule {
+	readonly appCli: AppCli
+}
+
+const optionalFunction = (value: object, key: string): boolean => {
+	const member: unknown = Reflect.get(value, key)
+	return member === undefined || typeof member === 'function'
+}
+
+const isNamespaceCli = (value: unknown): value is NamespaceCli =>
+	typeof value === 'object'
+	&& value !== null
+	&& 'usage' in value
+	&& typeof value.usage === 'string'
+	&& 'run' in value
+	&& typeof value.run === 'function'
+
+export const isAppCli = (value: unknown): value is AppCli =>
+	typeof value === 'object'
+	&& value !== null
+	&& 'provider' in value
+	&& typeof value.provider === 'string'
+	&& value.provider.trim() !== ''
+	&& 'entryRuntime' in value
+	&& (value.entryRuntime === 'bun' || value.entryRuntime === 'cloudflare')
+	&& optionalFunction(value, 'build')
+	&& optionalFunction(value, 'deploy')
+	&& optionalFunction(value, 'registrationManifest')
+	&& (!('namespaces' in value) || value.namespaces === undefined || isNamespaceCli(value.namespaces))
+
+/** `specifier` names the module in the error, so an operator knows which package to upgrade. */
+export const appCliFromModule = (value: unknown, expectedProvider: string, specifier: string): AppCli => {
+	if (typeof value !== 'object' || value === null || !('appCli' in value) || !isAppCli(value.appCli)) {
+		throw new Error(`${specifier} must export a valid \`appCli\`; a provider release older than this CLI has none`)
+	}
+	if (value.appCli.provider !== expectedProvider) {
+		throw new Error(`${specifier} provides "${value.appCli.provider}", expected "${expectedProvider}"`)
+	}
+	return value.appCli
+}

package/src/conformance.ts

@@ -0,0 +1,221 @@
+// The cases every `ControlProvider` passes, whatever cloud it deploys to. A provider's own test file calls
+// `describeControlProviderConformance` once with a harness over its fake cloud: the harness builds the provider and a
+// deploy its cloud accepts, and reports what the cloud was asked to change and to stop.
+
+import { describe, expect, test } from 'bun:test'
+import {
+	type ControlProvider,
+	type ProviderDeployInput,
+	type ProviderDeployOutcome,
+	ProviderInvocationAbort,
+	type ProviderRunEvents,
+} from './control'
+import type { JsonValue } from './json'
+
+/** What the suite hands a fake cloud: `accepted` is called once the cloud has taken the deploy's operation. */
+export interface ConformanceCloudHooks {
+	accepted(): void
+}
+
+/** One provider over one fresh fake cloud. */
+export interface ConformanceCloud {
+	readonly provider: ControlProvider
+	/** A deploy the fake cloud accepts and lets succeed. Each case sets `dryRun`, `signal` and `events` itself. */
+	readonly input: Omit<ProviderDeployInput, 'dryRun' | 'signal' | 'events'>
+	/** The credentials the provider holds itself (a cloud token, a signed URL); no event may carry one. */
+	readonly credentials: readonly string[]
+	/** Every request that changed the cloud: a write, a created resource, started work. A preview the cloud runs is none. */
+	mutations(): readonly string[]
+	/** Every request to stop or remove the deploy's work: a cancelled build or job, a deleted version. */
+	stops(): readonly string[]
+}
+
+export interface ControlProviderConformanceHarness {
+	/** Called once per case, and once per event in the lease-loss sweep. */
+	create(hooks: ConformanceCloudHooks): ConformanceCloud
+}
+
+/** A secret the suite adds to every deploy; no event may carry it. */
+const SECRET_NAME = 'CONFORMANCE_SECRET'
+const SECRET_VALUE = 'conformance-secret-value-7f3a9c'
+
+/** What a deploy reported through its events, as Control would have persisted it. */
+interface Recorded {
+	readonly logs: string[]
+	readonly externalIds: Array<{ readonly id: string; readonly state?: JsonValue }>
+	readonly checkpoints: JsonValue[]
+	/** Events that hold the lease: `boundary`, `externalId` and `checkpoint`, in order. */
+	events: number
+	/** A state Control could not store as given; collected, because a provider may swallow what an event throws. */
+	readonly violations: string[]
+}
+
+interface Invocation {
+	readonly input: ProviderDeployInput
+	readonly recorded: Recorded
+	/** Lose the lease as Control does: the signal aborts, and every later event rejects with the same reason. */
+	loseLease(): void
+	readonly signal: AbortSignal
+}
+
+const LEASE_LOST = new ProviderInvocationAbort('lease_lost')
+
+/** `lostAt`: the lease goes at this event (1-based), which rejects like every one after it. */
+function invocation(cloud: ConformanceCloud, dryRun: boolean, options: { readonly lostAt?: number } = {}): Invocation {
+	const controller = new AbortController()
+	const recorded: Recorded = { logs: [], externalIds: [], checkpoints: [], events: 0, violations: [] }
+	const loseLease = (): void => {
+		if (!controller.signal.aborted) controller.abort(LEASE_LOST)
+	}
+	const held = async (): Promise<void> => {
+		recorded.events += 1
+		if (recorded.events === options.lostAt) loseLease()
+		if (controller.signal.aborted) throw controller.signal.reason
+	}
+	const stored = (kind: string, state: JsonValue): JsonValue => {
+		const parsed: JsonValue = JSON.parse(JSON.stringify(state))
+		if (!Bun.deepEquals(parsed, state, true)) recorded.violations.push(`${kind} state is not JSON as given`)
+		return parsed
+	}
+	const events: ProviderRunEvents = {
+		log: (line) => {
+			recorded.logs.push(line)
+		},
+		externalId: async (id, state) => {
+			await held()
+			recorded.externalIds.push(state === undefined ? { id } : { id, state: stored('externalId', state) })
+		},
+		checkpoint: async (state) => {
+			await held()
+			recorded.checkpoints.push(stored('checkpoint', state))
+		},
+		boundary: held,
+	}
+	const input: ProviderDeployInput = {
+		...cloud.input,
+		secrets: { ...cloud.input.secrets, [SECRET_NAME]: SECRET_VALUE },
+		dryRun,
+		signal: controller.signal,
+		events,
+	}
+	return { input, recorded, loseLease, signal: controller.signal }
+}
+
+/**
+ * The deploy's outcome, or the reason it rejected with. A step a provider stops waiting for may still run, so the
+ * cloud is read only after the tasks already queued have run.
+ */
+async function settle(provider: ControlProvider, input: ProviderDeployInput): Promise<ProviderDeployOutcome | { readonly rejected: unknown }> {
+	let outcome: ProviderDeployOutcome | { readonly rejected: unknown }
+	try {
+		outcome = await provider.deploy(input)
+	} catch (error) {
+		outcome = { rejected: error }
+	}
+	await new Promise((resolve) => setTimeout(resolve, 0))
+	return outcome
+}
+
+/** No event carried a credential: the deploy's secrets, its credential managed entries, the upload bearer, the provider's own. */
+function expectCredentialFree(cloud: ConformanceCloud, run: Invocation): void {
+	const { input } = run
+	const managed = Object.values(input.managedEnvironment).flatMap((entry) => entry.credential && entry.value !== null ? [entry.value] : [])
+	const bearer = input.artifactUpload === undefined ? [] : [input.artifactUpload.bearer]
+	const reported = JSON.stringify({ logs: run.recorded.logs, externalIds: run.recorded.externalIds, checkpoints: run.recorded.checkpoints })
+	for (const credential of [...Object.values(input.secrets), ...managed, ...bearer, ...cloud.credentials]) {
+		expect(reported).not.toContain(credential)
+	}
+	expect(run.recorded.violations).toEqual([])
+}
+
+export function describeControlProviderConformance(name: string, harness: ControlProviderConformanceHarness): void {
+	const quiet = (): ConformanceCloud => harness.create({ accepted: () => {} })
+
+	describe(`${name} conforms to ControlProvider`, () => {
+		test('a deploy succeeds, and nothing it reports carries a credential', async () => {
+			const cloud = quiet()
+			const run = invocation(cloud, false)
+			expect(await settle(cloud.provider, run.input)).toMatchObject({ state: 'succeeded' })
+			expect(cloud.mutations().length).toBeGreaterThan(0)
+			expect(cloud.stops()).toEqual([])
+			expectCredentialFree(cloud, run)
+		})
+
+		test('a dry run succeeds, changes nothing in the cloud, and reports no credential', async () => {
+			const cloud = quiet()
+			const run = invocation(cloud, true)
+			expect(await settle(cloud.provider, run.input)).toMatchObject({ state: 'succeeded' })
+			expect(cloud.mutations()).toEqual([])
+			expect(cloud.stops()).toEqual([])
+			expectCredentialFree(cloud, run)
+		})
+
+		test('an invocation whose lease is gone at its first event changes nothing in the cloud', async () => {
+			const cloud = quiet()
+			const run = invocation(cloud, false, { lostAt: 1 })
+			expect(await settle(cloud.provider, run.input)).not.toMatchObject({ state: 'succeeded' })
+			expect(cloud.mutations()).toEqual([])
+			expect(cloud.stops()).toEqual([])
+		})
+
+		test('a lease lost at any event of a deploy stops nothing, and the deploy claims no success', async () => {
+			const cloud = quiet()
+			const complete = invocation(cloud, false)
+			await settle(cloud.provider, complete.input)
+			expect(complete.recorded.events).toBeGreaterThan(0)
+			for (let lostAt = 1; lostAt <= complete.recorded.events; lostAt += 1) {
+				const lost = quiet()
+				const run = invocation(lost, false, { lostAt })
+				const outcome = await settle(lost.provider, run.input)
+				// The cloud may still finish the work; this invocation may not claim it, and may not stop it.
+				expect({ lostAt, outcome }).not.toMatchObject({ outcome: { state: 'succeeded' } })
+				expect({ lostAt, stops: lost.stops() }).toEqual({ lostAt, stops: [] })
+				expectCredentialFree(lost, run)
+			}
+		})
+
+		test('a lease lost once the cloud accepted the deploy stops nothing, in the deploy, a reconcile or a cancel', async () => {
+			let run: Invocation | undefined
+			let accepted = false
+			const cloud = harness.create({
+				accepted: () => {
+					accepted = true
+					run?.loseLease()
+				},
+			})
+			run = invocation(cloud, false)
+			const outcome = await settle(cloud.provider, run.input)
+			expect(accepted).toBe(true)
+			expect(outcome).not.toMatchObject({ state: 'succeeded' })
+			expect(cloud.stops()).toEqual([])
+
+			// Control reconciles and cancels a run by what its last owner recorded.
+			const recordedId = run.recorded.externalIds[0]
+			if (recordedId === undefined) throw new Error('the deploy recorded no external id before its operation was accepted')
+			const providerState = run.recorded.checkpoints.at(-1) ?? recordedId.state
+			const reference = {
+				runId: run.input.runId,
+				externalId: recordedId.id,
+				environment: run.input.environment,
+				signal: run.signal,
+				...(providerState === undefined ? {} : { providerState }),
+			}
+			const mutations = cloud.mutations().length
+			await cloud.provider.reconcile?.(reference).catch(() => {})
+			await cloud.provider.cancel?.(reference).catch(() => {})
+			await new Promise((resolve) => setTimeout(resolve, 0))
+			expect(cloud.stops()).toEqual([])
+			expect(cloud.mutations()).toHaveLength(mutations)
+		})
+
+		test('a registration normalizes to itself, and its envelopes survive JSON', () => {
+			const cloud = quiet()
+			const normalize = cloud.provider.normalizeRegistration
+			if (normalize === undefined) return
+			const once = normalize({ app: cloud.input.app, environment: cloud.input.environment })
+			expect(normalize(once)).toEqual(once)
+			expect(JSON.parse(JSON.stringify(once.environment.target))).toEqual(once.environment.target)
+			expect(JSON.parse(JSON.stringify(once.environment.artifact))).toEqual(once.environment.artifact)
+		})
+	})
+}

package/src/control.ts

@@ -1,4 +1,5 @@
-import type { AppSchema, ContractArtifact } from '@fabrika/auth-core'
+import type { AppSchema, ContractArtifact, ManagedEnvironment } from '@fabrika/auth-core'
+import type { InstallationBrand } from '@fabrika/proxy-core/brand'
 import type { JsonValue, ProviderEnvelope } from './json'
 
 /** Events whose persistence and presentation belong to the control plane. */
@@ -15,8 +16,11 @@ export interface ProviderRunEvents {
 	boundary(): Promise<void>
 }
 
-/** Complete platform-owned runtime state. A null value removes the key from persistent targets. */
-export type ProviderManagedEnvironment = Readonly<Record<string, string | null>>
+/**
+ * Complete platform-owned runtime state, parsed by Control (`parseManagedEnvironment`). A provider writes each entry as
+ * a secret when it is a `credential`, removes one whose value is null, and removes the stale ones `staleManagedVariables` names.
+ */
+export type ProviderManagedEnvironment = ManagedEnvironment
 
 /** Provider-neutral coordinates for obtaining one app revision. */
 export interface ProviderSource {
@@ -41,8 +45,7 @@ export interface ProviderDeploymentNamespace {
 	readonly target: ProviderEnvelope
 }
 
-/** A framework release as npm publishes it; the only form one may take before it reaches a generated build command. */
-export const FRAMEWORK_RELEASE_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+export { FRAMEWORK_RELEASE_PATTERN } from '@fabrika/auth-core'
 
 /**
  * The access Control approved for one application environment (ADR-0050): the contract the proxy enforces and the
@@ -66,10 +69,18 @@ export interface ProviderApprovedAccess {
 	readonly checker: string
 }
 
+/**
+ * `dev`: the environment follows a workspace through a platform-owned launcher, which its provider starts instead of the
+ * serving entry (ADR-0043). The kind is Control's registry, never the application's.
+ */
+export type ProviderEnvironmentKind = 'standard' | 'dev'
+
 /** Persisted deploy data for one app environment. */
 export interface ProviderEnvironment {
 	readonly appId: string
 	readonly env: string
+	/** Absent means `standard`. */
+	readonly kind?: ProviderEnvironmentKind
 	readonly domain?: string
 	/** Canonical externally reachable HTTP(S) origin; independent of provider domain routing. */
 	readonly publicOrigin?: string
@@ -79,12 +90,18 @@ export interface ProviderEnvironment {
 	 * application's proxy manifest entry as `crossOrigins`.
 	 */
 	readonly crossOrigins?: readonly string[]
+	/**
+	 * The origin of the environment's active Operations ingest DSN, never the DSN: a contract application's proxy admits
+	 * it in `connect-src`. Control sets it on a deploy; absent while the environment has no active ingest.
+	 */
+	readonly operationsOrigin?: string
 	readonly namespace?: ProviderDeploymentNamespace
 	readonly target: ProviderEnvelope
 	readonly artifact: ProviderEnvelope
 	/**
 	 * The environment's approved contract, from Control's `approvedSnapshot`. Absent when nothing is approved: then a
 	 * provider publishes no endpoint table and reconciles no IAM schema, whatever the artifact claims (ADR-0050).
+	 * Control refuses a non-dry deploy without it.
 	 */
 	readonly access?: ProviderApprovedAccess
 }
@@ -137,12 +154,6 @@ export interface ProviderDeployInput {
 	readonly vars: Readonly<Record<string, string>>
 	/** Platform-owned runtime configuration, separate from operator-managed application vars. */
 	readonly managedEnvironment: ProviderManagedEnvironment
-	/**
-	 * Every origin IAM may hand this app a session at (ADR-0022). App-wide, not per-environment:
-	 * IAM's registry is keyed by app id, so the set is assembled from every environment of the app.
-	 * Absent when the app has no public origin at all, which leaves IAM's registry untouched.
-	 */
-	readonly returnOrigins?: readonly string[]
 	readonly dryRun: boolean
 	readonly sourceBinding?: ProviderSourceBinding
 	/** Optional short-lived, run-scoped Operations artifact destination. */
@@ -159,7 +170,10 @@ export interface ProviderDeployInput {
 	readonly events: ProviderRunEvents
 }
 
-/** A terminal provider operation result. */
+/**
+ * A terminal provider operation result. `succeeded` means the version is live: Control then writes the environment's
+ * approved IAM schema itself (ADR-0011), so a provider never calls IAM for an application.
+ */
 export interface ProviderTerminalOutcome {
 	readonly state: 'succeeded' | 'failed'
 	readonly exitCode?: number
@@ -222,14 +236,10 @@ export interface ProviderRunReference {
 
 export interface ProviderCancelInput extends ProviderRunReference {
 	readonly signal: AbortSignal
-	/** See `ProviderDeployInput.returnOrigins`; a cancel that settles an activated deploy projects the same set. */
-	readonly returnOrigins?: readonly string[]
 }
 
 export interface ProviderReconcileInput extends ProviderRunReference {
 	readonly signal: AbortSignal
-	/** See `ProviderDeployInput.returnOrigins`; a provider that settles a deploy here projects the same set. */
-	readonly returnOrigins?: readonly string[]
 	/** Append a line to the run's log. */
 	log?(line: string): Promise<void>
 }
@@ -330,6 +340,11 @@ export interface ProviderNamespaceMutationInput {
 	readonly namespace: ProviderDeploymentNamespace
 	/** Every app environment assigned to the namespace, read under its lease. */
 	readonly members: readonly ProviderNamespaceMember[]
+	/**
+	 * The installation's client logo for the pages the namespace's proxy answers with (ADR-0066), read from IAM for this
+	 * mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
+	 */
+	readonly brand?: InstallationBrand | null
 	readonly signal: AbortSignal
 	readonly events: ProviderNamespaceEvents
 }
@@ -462,6 +477,19 @@ export interface ProviderNamespaceOperator {
 	present(namespace: ProviderDeploymentNamespace): ProviderNamespacePresentation
 }
 
+/** The app-owned claims of one namespace whose resources Control is asked to confirm gone. */
+export interface ProviderClaimedResourcesInput {
+	readonly namespace: ProviderDeploymentNamespace
+	readonly resourceKeys: readonly string[]
+	readonly signal: AbortSignal
+}
+
+/** What the provider observed for one claimed resource. */
+export interface ProviderClaimedResource {
+	readonly resourceKey: string
+	readonly exists: boolean
+}
+
 /** Optional placement lifecycle owned by providers that use deployment namespaces. */
 export interface ProviderNamespaceCapabilities {
 	normalize(namespace: ProviderDeploymentNamespace): ProviderDeploymentNamespace
@@ -478,11 +506,36 @@ export interface ProviderNamespaceCapabilities {
 	reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>
 	/** Absent means the namespace has no entry point that follows its members. */
 	republish?(input: ProviderNamespaceRepublishInput): Promise<ProviderNamespaceRepublishResult>
+	/**
+	 * Read-only: whether each claimed resource still exists, one answer per key. Throws when it cannot tell, so Control
+	 * releases a claim only over a resource the provider confirmed gone. Absent means no claim can be released.
+	 */
+	claimedResources?(input: ProviderClaimedResourcesInput): Promise<readonly ProviderClaimedResource[]>
 	/** Absent means the provider changes no namespace in place. */
 	readonly updates?: ProviderNamespaceUpdates
 	readonly operator?: ProviderNamespaceOperator
 }
 
+export interface ProviderAuthoring {
+	/** The file NAMES (no `/`) that configure the provider's deploy; a workspace changes none of them, at any depth. */
+	readonly protectedFiles: readonly string[]
+}
+
+/** One call on the service of a `dev` environment, between its bootstrap runs. */
+export interface ProviderDevEnvironmentInput {
+	readonly environment: ProviderEnvironment
+	readonly signal: AbortSignal
+}
+
+/**
+ * The service of a `dev` environment outside a run (ADR-0049): Control stops it after an idle period and starts it on
+ * the next commit. Files the launcher wrote survive both.
+ */
+export interface ProviderDevEnvironments {
+	stop(input: ProviderDevEnvironmentInput): Promise<void>
+	start(input: ProviderDevEnvironmentInput): Promise<void>
+}
+
 /**
  * The control-plane capability bundle selected statically by one composition root.
  *
@@ -504,6 +557,22 @@ export interface ControlProvider {
 	reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>
 	readonly secrets?: ProviderManagedSecrets
 	readonly namespaces?: ProviderNamespaceCapabilities
+	/** MCP authoring (ADR-0049): an environment of this provider can be an authoring target. Absent means none can. */
+	readonly authoring?: ProviderAuthoring
+	/**
+	 * Every application environment gets `FABRIKA_PROXY_SECRET`, with or without a namespace proxy: the provider's own
+	 * hop to the application carries it (Cloudflare's Worker to its Durable Object, ADR-0065). Absent means only a
+	 * namespace proxy's environments get one.
+	 */
+	readonly applicationHopSecret?: true
+	/** Absent means the provider runs no `dev` environment, and Control refuses one. */
+	readonly devEnvironments?: ProviderDevEnvironments
+	/**
+	 * Whether an environment at this approved access is served the ops channel through which Control reaches its object
+	 * (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no
+	 * release logic. Absent means no environment of this provider is.
+	 */
+	opsChannel?(access: ProviderApprovedAccess): boolean
 	/** Absent means the provider deploys public sources only. */
 	readonly source?: ProviderSourceCapabilities
 	/**

package/src/steps.ts

@@ -59,7 +59,9 @@ export const runSteps = async <TStep extends { readonly id: string; readonly des
 		log(`→ ${step.id}`)
 		try {
 			await untilCancelled(runOne(step), signal)
-			results.push({ id: step.id, status: 'succeeded', startedAt, finishedAt: Date.now() })
+			const finishedAt = Date.now()
+			log(`✓ ${step.id} (${((finishedAt - startedAt) / 1000).toFixed(1)}s)`)
+			results.push({ id: step.id, status: 'succeeded', startedAt, finishedAt })
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error)
 			stopped = true

package/types/src/app-cli.d.ts

@@ -0,0 +1,46 @@
+import type { ProviderDeploymentNamespace, ProviderNamespacePlan } from './control';
+/** The runtime a contract application's generated entry is written for (`@fabrika/app/build`'s `EntryRuntime`). */
+export type AppEntryRuntime = 'bun' | 'cloudflare';
+/** What a namespace command asks of Control. The `fabrika` command holds the Control origin, the credential and the transport. */
+export interface NamespaceControl {
+    create(namespace: ProviderDeploymentNamespace): Promise<unknown>;
+    adopt(namespace: ProviderDeploymentNamespace): Promise<unknown>;
+    reconcile(namespaceId: string): Promise<unknown>;
+}
+/** A plan, or the namespace Control answered with; the `fabrika` command validates and prints either. */
+export type NamespaceCommandResult = {
+    readonly plan: ProviderNamespacePlan;
+} | {
+    readonly namespace: unknown;
+};
+export interface NamespaceCommandContext {
+    readonly source: Readonly<Record<string, string | undefined>>;
+    /** Reads the Control origin and credential, and throws when either is missing: call it after every other input is checked. */
+    control(): NamespaceControl;
+}
+export interface NamespaceCli {
+    readonly usage: string;
+    /** `argv` is the command's own arguments, without the router's `--provider` and `--json`. */
+    run(subcommand: string, argv: readonly string[], context: NamespaceCommandContext): Promise<NamespaceCommandResult>;
+}
+export interface AppCli {
+    readonly provider: string;
+    readonly entryRuntime: AppEntryRuntime;
+    /** `fabrika app build`, after the command wrote a contract application's entry; `contract` says whether it did. */
+    build?(argv: readonly string[], context: {
+        readonly contract: boolean;
+    }): Promise<void>;
+    deploy?(argv: readonly string[]): Promise<void>;
+    /** The text `fabrika app register` hands Control: the application's manifest for one environment. */
+    registrationManifest?(options: {
+        readonly config: string;
+        readonly env: string;
+    }): Promise<string>;
+    readonly namespaces?: NamespaceCli;
+}
+export interface AppCliModule {
+    readonly appCli: AppCli;
+}
+export declare const isAppCli: (value: unknown) => value is AppCli;
+/** `specifier` names the module in the error, so an operator knows which package to upgrade. */
+export declare const appCliFromModule: (value: unknown, expectedProvider: string, specifier: string) => AppCli;

package/types/src/authoring.d.ts

@@ -0,0 +1,27 @@
+import type { AppSchema } from '@fabrika/auth-core';
+export declare const APP_PROVIDER: unique symbol;
+export interface ProviderAuthoredApp<Provider extends string = string> {
+    readonly [APP_PROVIDER]: Provider;
+}
+export declare const authoredAppProvider: (value: unknown) => string | undefined;
+export declare const isProviderAuthoredApp: <Provider extends string>(value: unknown, provider: Provider) => value is ProviderAuthoredApp<Provider>;
+/** Provider-neutral build inputs and environment requirements declared by an app. */
+export interface AppPipeline {
+    /** Source directory relative to the app config file. Defaults to `.`. */
+    workerDir?: string;
+    /** Shell command that builds the deployable artifact. */
+    build?: string;
+    /** Secret names that must resolve before deployment. */
+    secrets?: string[];
+    /** Non-secret variable names that must resolve before deployment. */
+    vars?: string[];
+}
+/** App metadata shared by every provider-specific authoring config. */
+export interface AppConfigBase {
+    /** Stable app id, unique within one control plane. */
+    id: string;
+    /** The app-owned authorization vocabulary reconciled into IAM. */
+    schema?: AppSchema;
+    /** Provider-neutral build and environment requirements. */
+    pipeline?: AppPipeline;
+}

package/types/src/conformance.d.ts

@@ -0,0 +1,22 @@
+import { type ControlProvider, type ProviderDeployInput } from './control';
+/** What the suite hands a fake cloud: `accepted` is called once the cloud has taken the deploy's operation. */
+export interface ConformanceCloudHooks {
+    accepted(): void;
+}
+/** One provider over one fresh fake cloud. */
+export interface ConformanceCloud {
+    readonly provider: ControlProvider;
+    /** A deploy the fake cloud accepts and lets succeed. Each case sets `dryRun`, `signal` and `events` itself. */
+    readonly input: Omit<ProviderDeployInput, 'dryRun' | 'signal' | 'events'>;
+    /** The credentials the provider holds itself (a cloud token, a signed URL); no event may carry one. */
+    readonly credentials: readonly string[];
+    /** Every request that changed the cloud: a write, a created resource, started work. A preview the cloud runs is none. */
+    mutations(): readonly string[];
+    /** Every request to stop or remove the deploy's work: a cancelled build or job, a deleted version. */
+    stops(): readonly string[];
+}
+export interface ControlProviderConformanceHarness {
+    /** Called once per case, and once per event in the lease-loss sweep. */
+    create(hooks: ConformanceCloudHooks): ConformanceCloud;
+}
+export declare function describeControlProviderConformance(name: string, harness: ControlProviderConformanceHarness): void;

package/types/src/control.d.ts

@@ -0,0 +1,523 @@
+import type { AppSchema, ContractArtifact, ManagedEnvironment } from '@fabrika/auth-core';
+import type { InstallationBrand } from '@fabrika/proxy-core/brand';
+import type { JsonValue, ProviderEnvelope } from './json';
+/** Events whose persistence and presentation belong to the control plane. */
+export interface ProviderRunEvents {
+    log(line: string): void;
+    /** Atomically persist the external operation id and, when supplied, its credential-free checkpoint. */
+    externalId(id: string, state?: JsonValue): Promise<void>;
+    /** Replace the credential-free checkpoint while this run remains active. */
+    checkpoint(state: JsonValue): Promise<void>;
+    /**
+     * A step boundary: Control checks its lease and reads the run's cancellation request. Rejects with a
+     * `ProviderInvocationAbort` after aborting the run's signal. A long step calls it at its own boundaries.
+     */
+    boundary(): Promise<void>;
+}
+/**
+ * Complete platform-owned runtime state, parsed by Control (`parseManagedEnvironment`). A provider writes each entry as
+ * a secret when it is a `credential`, removes one whose value is null, and removes the stale ones `staleManagedVariables` names.
+ */
+export type ProviderManagedEnvironment = ManagedEnvironment;
+/** Provider-neutral coordinates for obtaining one app revision. */
+export interface ProviderSource {
+    readonly repoUrl: string;
+    readonly ref: string;
+    readonly workerDir?: string;
+    readonly buildCommand?: string;
+    readonly configPath?: string;
+}
+/** App data needed by a control provider. */
+export interface ProviderApp {
+    readonly id: string;
+    readonly source: ProviderSource;
+}
+/** One provider-owned placement boundary shared by zero or more app environments. */
+export interface ProviderDeploymentNamespace {
+    readonly id: string;
+    readonly env: string;
+    readonly exclusiveAppId?: string;
+    readonly target: ProviderEnvelope;
+}
+export { FRAMEWORK_RELEASE_PATTERN } from '@fabrika/auth-core';
+/**
+ * The access Control approved for one application environment (ADR-0050): the contract the proxy enforces and the
+ * IAM vocabulary compiled from it. A provider publishes a contract application's endpoint table and reconciles its
+ * IAM schema from this, never from the artifact or a runner's report.
+ */
+export interface ProviderApprovedAccess {
+    /** The contract in this platform release's model, upcast from the application's own release's artifact (ADR-0062). */
+    readonly contract: ContractArtifact;
+    /**
+     * The digest the application's own framework release computes for its contract, which it compares with
+     * `FABRIKA_CONTRACT_DIGEST` at startup. It is `contractDigest(contract)` only when the application is on this
+     * release's artifact format, so a provider never derives it from `contract`.
+     */
+    readonly contractDigest: string;
+    readonly schema: AppSchema;
+    /**
+     * The `@fabrika/check` release whose reader read the application (`FRAMEWORK_RELEASE_PATTERN`): the newest patch of
+     * the framework minor it pins (ADR-0062). Its build checks with that release.
+     */
+    readonly checker: string;
+}
+/**
+ * `dev`: the environment follows a workspace through a platform-owned launcher, which its provider starts instead of the
+ * serving entry (ADR-0043). The kind is Control's registry, never the application's.
+ */
+export type ProviderEnvironmentKind = 'standard' | 'dev';
+/** Persisted deploy data for one app environment. */
+export interface ProviderEnvironment {
+    readonly appId: string;
+    readonly env: string;
+    /** Absent means `standard`. */
+    readonly kind?: ProviderEnvironmentKind;
+    readonly domain?: string;
+    /** Canonical externally reachable HTTP(S) origin; independent of provider domain routing. */
+    readonly publicOrigin?: string;
+    /**
+     * The exact origins whose pages may call the environment's cross-origin endpoints, as the operator listed them in
+     * Control's registry (ADR-0022 "Cross-origin endpoints"). Absent when it lists none. A provider writes them into the
+     * application's proxy manifest entry as `crossOrigins`.
+     */
+    readonly crossOrigins?: readonly string[];
+    /**
+     * The origin of the environment's active Operations ingest DSN, never the DSN: a contract application's proxy admits
+     * it in `connect-src`. Control sets it on a deploy; absent while the environment has no active ingest.
+     */
+    readonly operationsOrigin?: string;
+    readonly namespace?: ProviderDeploymentNamespace;
+    readonly target: ProviderEnvelope;
+    readonly artifact: ProviderEnvelope;
+    /**
+     * The environment's approved contract, from Control's `approvedSnapshot`. Absent when nothing is approved: then a
+     * provider publishes no endpoint table and reconciles no IAM schema, whatever the artifact claims (ADR-0050).
+     * Control refuses a non-dry deploy without it.
+     */
+    readonly access?: ProviderApprovedAccess;
+}
+/** Raw registration data passed to provider-owned validation and normalization. */
+export interface ProviderRegistrationInput {
+    readonly app: ProviderApp;
+    readonly environment: ProviderEnvironment;
+}
+/** Canonical registration returned after provider-owned validation and normalization. */
+export type ProviderRegistration = ProviderRegistrationInput;
+/** Provider-neutral input for resolving one requested source ref to an immutable Git object id. */
+export interface ProviderSourceResolutionInput {
+    readonly runId: string;
+    readonly app: ProviderApp;
+    readonly environment: ProviderEnvironment;
+    /** An immutable commit already recorded by the trigger, which resolution must verify exactly. */
+    readonly expectedCommitSha?: string;
+    readonly sourceBinding?: ProviderSourceBinding;
+    readonly signal: AbortSignal;
+}
+/** The exact source revision a provider resolved before starting deploy work. */
+export interface ProviderSourceResolution {
+    readonly commitSha: string;
+}
+/**
+ * Credential-free selector of the GitHub connection and installation that read a private source
+ * (ADR-0029). Absent means a public source; an installation id alone never selects a credential.
+ */
+export interface ProviderSourceBinding {
+    readonly connectionId: string;
+    readonly installationId: number;
+}
+/** How private GitHub sources reach a provider (ADR-0029): one keyed connection's App and installation. */
+export interface ProviderSourceCapabilities {
+    readonly binding: 'connection';
+}
+/** One control-plane deploy invocation. */
+export interface ProviderDeployInput {
+    readonly runId: string;
+    readonly app: ProviderApp;
+    readonly environment: ProviderEnvironment;
+    readonly secrets: Readonly<Record<string, string>>;
+    readonly vars: Readonly<Record<string, string>>;
+    /** Platform-owned runtime configuration, separate from operator-managed application vars. */
+    readonly managedEnvironment: ProviderManagedEnvironment;
+    readonly dryRun: boolean;
+    readonly sourceBinding?: ProviderSourceBinding;
+    /** Optional short-lived, run-scoped Operations artifact destination. */
+    readonly artifactUpload?: {
+        readonly url: string;
+        readonly bearer: string;
+        readonly appId: string;
+        readonly environment: string;
+        readonly serviceKey: string;
+        readonly release: string;
+        readonly runId: string;
+    };
+    readonly signal: AbortSignal;
+    readonly events: ProviderRunEvents;
+}
+/**
+ * A terminal provider operation result. `succeeded` means the version is live: Control then writes the environment's
+ * approved IAM schema itself (ADR-0011), so a provider never calls IAM for an application.
+ */
+export interface ProviderTerminalOutcome {
+    readonly state: 'succeeded' | 'failed';
+    readonly exitCode?: number;
+    /** Whether provider-local release artifacts reached Operations. */
+    readonly artifactState?: 'complete' | 'incomplete' | 'not_applicable';
+}
+/** Running means external settlement is unresolved, including an ambiguous submission response. */
+export type ProviderDeployOutcome = ProviderTerminalOutcome | {
+    readonly state: 'running';
+};
+/** Settled does not imply rollback: when activation won before cancellation, `outcome` is `succeeded`. */
+export type ProviderCancelOutcome = {
+    readonly state: 'pending';
+} | {
+    readonly state: 'settled';
+    readonly outcome?: 'succeeded' | 'failed';
+};
+/** Losing invocation ownership must never be interpreted as permission to cancel external work. */
+export declare class ProviderInvocationAbort extends Error {
+    readonly kind: 'lease_lost' | 'cancel_requested';
+    constructor(kind: 'lease_lost' | 'cancel_requested');
+}
+export declare const isLeaseLoss: (reason: unknown) => boolean;
+/** A signal that aborts with `signal`'s reason only when the lease is lost, never on a cancel. */
+export declare const followLeaseLoss: (signal: AbortSignal) => AbortSignal;
+/** Resolve after `ms`, or reject with the signal's reason once it aborts. */
+export declare const abortableWait: (ms: number, signal: AbortSignal) => Promise<void>;
+/** A platform-owned run that can be cancelled or reconciled. */
+export interface ProviderRunReference {
+    readonly runId: string;
+    readonly externalId: string;
+    readonly environment: ProviderEnvironment;
+    /** Credential-free provider-owned checkpoint recorded by the run's last owner. */
+    readonly providerState?: JsonValue;
+    /** When the run started (`started_at`, else `created_at`), in epoch milliseconds; bounds how long a provider polls. */
+    readonly startedAtMs?: number;
+}
+export interface ProviderCancelInput extends ProviderRunReference {
+    readonly signal: AbortSignal;
+}
+export interface ProviderReconcileInput extends ProviderRunReference {
+    readonly signal: AbortSignal;
+    /** Append a line to the run's log. */
+    log?(line: string): Promise<void>;
+}
+/** The latest state reported while reconciling a platform-owned run. */
+export interface ProviderReconcileOutcome {
+    readonly state: 'running' | 'succeeded' | 'failed';
+    readonly exitCode?: number;
+    /** See `ProviderTerminalOutcome.artifactState`. */
+    readonly artifactState?: 'complete' | 'incomplete' | 'not_applicable';
+    /** The settled run was a preview: core projects it as a dry run. */
+    readonly dryRun?: boolean;
+}
+/** Write one secret value to provider-managed storage. */
+export interface ProviderSecretPutInput {
+    readonly environment: ProviderEnvironment;
+    readonly name: string;
+    readonly value: string;
+}
+/** Remove one secret value from provider-managed storage. */
+export interface ProviderSecretDeleteInput {
+    readonly environment: ProviderEnvironment;
+    readonly name: string;
+}
+/** Opaque reference persisted by core instead of the provider-managed secret value. */
+export interface ProviderSecretPutResult {
+    readonly valueRef: string;
+}
+/** Optional edit-time secret storage owned by a provider. */
+export interface ProviderManagedSecrets {
+    put(input: ProviderSecretPutInput): Promise<ProviderSecretPutResult>;
+    delete(input: ProviderSecretDeleteInput): Promise<void>;
+}
+/**
+ * A namespace lifecycle failure an operator can act on.
+ *
+ * `code` is a STABLE identifier — a platform error code, or one this provider defines for a lifecycle
+ * invariant — so core can record and a console can render the CLASS of a failure instead of matching
+ * prose. `message` is the provider's own summary; `detail` carries the upstream's words VERBATIM.
+ * Neither is safe to persist as-is: core redacts both before they reach a row or a log, because only
+ * core knows what a credential looks like in this installation.
+ */
+export declare class ProviderNamespaceError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly detail?: string | undefined;
+    constructor(message: string, code: string, retryable: boolean, detail?: string | undefined);
+}
+/**
+ * A provider-managed secret write the provider refuses on the app's own terms — a value naming a
+ * service the app does not own, say. `message` carries the secret's name and the offending host,
+ * never the value, so core may hand it to the caller as a 4xx.
+ */
+export declare class ProviderSecretError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** Persist a canonical namespace target immediately after one external mutation succeeds. */
+export interface ProviderNamespaceEvents {
+    checkpoint(namespace: ProviderDeploymentNamespace): Promise<void>;
+    /** A step boundary: Control checks the namespace lease and, for a deploy, the run's cancellation request. */
+    boundary(): Promise<void>;
+}
+/** One app environment assigned to a namespace, as its proxy routes it. */
+export interface ProviderNamespaceMember {
+    readonly appId: string;
+    readonly env: string;
+    readonly domain?: string;
+    /** See `ProviderEnvironment.crossOrigins`: the namespace proxy's entry for this member lists them. */
+    readonly crossOrigins?: readonly string[];
+    readonly artifact: ProviderEnvelope;
+    /**
+     * The secret the namespace proxy authenticates itself to this application environment with (ADR-0022 rule 5).
+     * Control generates it once and keeps it in its vault; absent when Control has no vault.
+     */
+    readonly proxySecret?: string;
+    /**
+     * The origin of this environment's active Operations ingest DSN, never the DSN itself: a contract application's
+     * proxy admits it in `connect-src`, as the framework does. Absent while the environment has no active ingest.
+     */
+    readonly operationsOrigin?: string;
+    /** See `ProviderEnvironment.access`: the proxy table of a contract application comes only from here. */
+    readonly access?: ProviderApprovedAccess;
+}
+/** One idempotent namespace lifecycle invocation. */
+export interface ProviderNamespaceMutationInput {
+    readonly namespace: ProviderDeploymentNamespace;
+    /** Every app environment assigned to the namespace, read under its lease. */
+    readonly members: readonly ProviderNamespaceMember[];
+    /**
+     * The installation's client logo for the pages the namespace's proxy answers with (ADR-0066), read from IAM for this
+     * mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
+     */
+    readonly brand?: InstallationBrand | null;
+    readonly signal: AbortSignal;
+    readonly events: ProviderNamespaceEvents;
+}
+/** `settled` is false while the rebuild is still in flight; core then hands it to a `reconcile` job. */
+export interface ProviderNamespaceRepublishResult {
+    readonly namespace: ProviderDeploymentNamespace;
+    readonly settled: boolean;
+}
+/** Rebuild a ready namespace's entry point from its current members. */
+export interface ProviderNamespaceRepublishInput extends ProviderNamespaceMutationInput {
+    /** `started`: return once the rebuild is submitted. `active`: return once it is live. */
+    readonly wait: 'started' | 'active';
+}
+/**
+ * The `code` of a `ProviderNamespaceError` an update plan throws when the requested target changes
+ * something the provider cannot move in place. Core answers it as a conflict that names the supported path.
+ */
+export declare const PROVIDER_NAMESPACE_IMMUTABLE = "namespaceImmutable";
+/**
+ * The `code` of a `ProviderNamespaceError` an update apply throws when the live change MAY have been made
+ * and is not confirmed. Any other failure means nothing changed. Applying the same plan again must converge.
+ */
+export declare const PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED = "namespaceUpdateUnconfirmed";
+/** One provider-described change, safe to audit: names and values only, never a credential. */
+export interface ProviderNamespaceChange {
+    readonly field: string;
+    readonly from: string | null;
+    readonly to: string;
+}
+/** The validated result of merging a requested target over the stored one. `change` is null for a no-op. */
+export interface ProviderNamespaceUpdatePlan {
+    readonly namespace: ProviderDeploymentNamespace;
+    readonly change: ProviderNamespaceChange | null;
+}
+/** Apply one plan. `next` is the planned namespace, with the same coordinates as `namespace`. */
+export interface ProviderNamespaceUpdateInput {
+    readonly namespace: ProviderDeploymentNamespace;
+    readonly next: ProviderDeploymentNamespace;
+    /** The namespace an earlier, unconfirmed update planned; the live resources may already match it. */
+    readonly unconfirmed?: ProviderDeploymentNamespace;
+    readonly signal: AbortSignal;
+}
+/** In-place change of a settled namespace. */
+export interface ProviderNamespaceUpdates {
+    /**
+     * Merge `requested` — whose payload may name only what changes — over the stored `namespace` and
+     * validate the result. Pure. A change that cannot be made in place throws `PROVIDER_NAMESPACE_IMMUTABLE`.
+     */
+    plan(namespace: ProviderDeploymentNamespace, requested: ProviderEnvelope): ProviderNamespaceUpdatePlan;
+    /** Move the live resources to `next` and return the target core stores. */
+    apply(input: ProviderNamespaceUpdateInput): Promise<ProviderDeploymentNamespace>;
+}
+/** One registration whose provider coordinates do not exist until namespace services are prepared. */
+export interface ProviderRegistrationPreparationInput {
+    readonly registration: ProviderRegistration;
+    readonly signal: AbortSignal;
+}
+/** One provider-defined operator choice. Core does not interpret its id or description. */
+export interface ProviderNamespacePreset {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly requiresExclusiveApp: boolean;
+}
+/** Provider-neutral coordinates plus opaque provider options for a namespace preview. */
+export interface ProviderNamespacePlanInput {
+    readonly id: string;
+    readonly env: string;
+    readonly preset: string;
+    readonly exclusiveAppId?: string;
+    readonly options?: JsonValue;
+}
+/** One safe, human-readable provider fact. Values must never contain credentials. */
+export interface ProviderNamespaceFact {
+    readonly label: string;
+    readonly value: string;
+    /**
+     * Marks a fact that NAMES A LIVE PROVIDER RESOURCE, not a policy choice. Core deletes no provider
+     * resource, so removal has to tell the operator what it stopped tracking — and only the provider
+     * knows which of its facts is a real thing with an id. Absent means "not a resource"; a fact is
+     * marked only when its value identifies something that outlives the namespace row.
+     */
+    readonly resource?: true;
+}
+/**
+ * One public host this namespace's own entry point answers on, with the listener port that publishes it.
+ *
+ * Only the provider knows how a host comes to exist — Zerops generates one per published HTTP port — and
+ * core knows which of them an application environment already claims, so the provider names them and core
+ * marks them. A namespace whose domains are bound out of band names none: the provider cannot see them.
+ */
+export interface ProviderNamespaceHost {
+    readonly host: string;
+    readonly port: number;
+}
+/** Provider-owned operator copy for a planned or persisted namespace. */
+export interface ProviderNamespacePresentation {
+    readonly preset: string;
+    readonly title: string;
+    readonly facts: readonly ProviderNamespaceFact[];
+    readonly instructions: readonly string[];
+    /** The hosts this namespace can serve, so an operator can name one as an environment's domain. */
+    readonly hosts?: readonly ProviderNamespaceHost[];
+}
+/** A mutation-free preview that can be submitted unchanged to namespace creation. */
+export interface ProviderNamespacePlan {
+    readonly namespace: ProviderDeploymentNamespace;
+    readonly presentation: ProviderNamespacePresentation;
+}
+/** Optional operator surface for providers that offer opinionated namespace presets. */
+export interface ProviderNamespaceOperator {
+    readonly presets: readonly ProviderNamespacePreset[];
+    plan(input: ProviderNamespacePlanInput): ProviderNamespacePlan;
+    present(namespace: ProviderDeploymentNamespace): ProviderNamespacePresentation;
+}
+/** The app-owned claims of one namespace whose resources Control is asked to confirm gone. */
+export interface ProviderClaimedResourcesInput {
+    readonly namespace: ProviderDeploymentNamespace;
+    readonly resourceKeys: readonly string[];
+    readonly signal: AbortSignal;
+}
+/** What the provider observed for one claimed resource. */
+export interface ProviderClaimedResource {
+    readonly resourceKey: string;
+    readonly exists: boolean;
+}
+/** Optional placement lifecycle owned by providers that use deployment namespaces. */
+export interface ProviderNamespaceCapabilities {
+    normalize(namespace: ProviderDeploymentNamespace): ProviderDeploymentNamespace;
+    /** Namespace-owned resources that must be reserved before provisioning starts. */
+    namespaceResourceClaims(namespace: ProviderDeploymentNamespace): readonly string[];
+    /** App-owned resources derived from one canonical normalized registration. */
+    registrationResourceClaims(registration: ProviderRegistration): readonly string[];
+    /**
+     * Materialize app-owned provider resources and return their canonical coordinates.
+     * Core acquires every registration resource claim before invoking this mutation.
+     */
+    prepareRegistration?(input: ProviderRegistrationPreparationInput): Promise<ProviderRegistration>;
+    provision(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>;
+    reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>;
+    /** Absent means the namespace has no entry point that follows its members. */
+    republish?(input: ProviderNamespaceRepublishInput): Promise<ProviderNamespaceRepublishResult>;
+    /**
+     * Read-only: whether each claimed resource still exists, one answer per key. Throws when it cannot tell, so Control
+     * releases a claim only over a resource the provider confirmed gone. Absent means no claim can be released.
+     */
+    claimedResources?(input: ProviderClaimedResourcesInput): Promise<readonly ProviderClaimedResource[]>;
+    /** Absent means the provider changes no namespace in place. */
+    readonly updates?: ProviderNamespaceUpdates;
+    readonly operator?: ProviderNamespaceOperator;
+}
+export interface ProviderAuthoring {
+    /** The file NAMES (no `/`) that configure the provider's deploy; a workspace changes none of them, at any depth. */
+    readonly protectedFiles: readonly string[];
+}
+/** One call on the service of a `dev` environment, between its bootstrap runs. */
+export interface ProviderDevEnvironmentInput {
+    readonly environment: ProviderEnvironment;
+    readonly signal: AbortSignal;
+}
+/**
+ * The service of a `dev` environment outside a run (ADR-0049): Control stops it after an idle period and starts it on
+ * the next commit. Files the launcher wrote survive both.
+ */
+export interface ProviderDevEnvironments {
+    stop(input: ProviderDevEnvironmentInput): Promise<void>;
+    start(input: ProviderDevEnvironmentInput): Promise<void>;
+}
+/**
+ * The control-plane capability bundle selected statically by one composition root.
+ *
+ * Core owns no provider registry. The selected provider validates registration envelopes and owns
+ * every provider-specific deploy lifecycle capability.
+ */
+export interface ControlProvider {
+    readonly id: string;
+    /** Absent means core stores the registration as submitted. */
+    normalizeRegistration?(input: ProviderRegistrationInput): ProviderRegistration;
+    resolveSource?(input: ProviderSourceResolutionInput): Promise<ProviderSourceResolution>;
+    /**
+     * Mutation-free check of a candidate's compatibility with its placement. Control calls it before publishing the
+     * snapshot, under the namespace lease, on every publication attempt. The candidate is not yet approved access.
+     */
+    validateAccess?(input: {
+        readonly environment: ProviderEnvironment;
+        readonly access: ProviderApprovedAccess;
+    }): void;
+    deploy(input: ProviderDeployInput): Promise<ProviderDeployOutcome>;
+    cancel?(input: ProviderCancelInput): Promise<ProviderCancelOutcome>;
+    reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>;
+    readonly secrets?: ProviderManagedSecrets;
+    readonly namespaces?: ProviderNamespaceCapabilities;
+    /** MCP authoring (ADR-0049): an environment of this provider can be an authoring target. Absent means none can. */
+    readonly authoring?: ProviderAuthoring;
+    /**
+     * Every application environment gets `FABRIKA_PROXY_SECRET`, with or without a namespace proxy: the provider's own
+     * hop to the application carries it (Cloudflare's Worker to its Durable Object, ADR-0065). Absent means only a
+     * namespace proxy's environments get one.
+     */
+    readonly applicationHopSecret?: true;
+    /** Absent means the provider runs no `dev` environment, and Control refuses one. */
+    readonly devEnvironments?: ProviderDevEnvironments;
+    /**
+     * Whether an environment at this approved access is served the ops channel through which Control reaches its object
+     * (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no
+     * release logic. Absent means no environment of this provider is.
+     */
+    opsChannel?(access: ProviderApprovedAccess): boolean;
+    /** Absent means the provider deploys public sources only. */
+    readonly source?: ProviderSourceCapabilities;
+    /**
+     * The variable names this artifact declares, so core can refuse one it would silently ignore
+     * ([ADR-0035](../../../docs/decisions/0035-the-platform-owns-the-application-iam-issuer.md)).
+     *
+     * OPTIONAL, and `undefined` is the honest answer rather than an empty set: a provider whose artifact
+     * names a config path in the repository cannot know what that config declares, and guessing would
+     * refuse a variable that works. A provider that CAN answer — one whose artifact is the compiled
+     * manifest — constrains what an operator may set.
+     */
+    declaredVariables?(input: {
+        readonly artifact: ProviderEnvelope;
+    }): readonly string[] | undefined;
+    /**
+     * The repository-relative directory this provider executes the application from, normalized as its execution
+     * normalizes it (`''` for the repository root), or null for a root execution refuses. Control reads the run's
+     * access snapshot there (ADR-0050). Absent means the repository root.
+     */
+    applicationRoot?(source: ProviderSource): string | null;
+}

package/types/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './authoring';
+export * from './control';
+export * from './json';
+export * from './schema';
+export * from './steps';

package/types/src/installation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The platform commands a provider MAY offer. Every one of them is optional — a provider declares the
+ * subset it implements and the CLI prints its usage for anything else.
+ *
+ * `install` is the newest and the narrowest in support: it BRINGS UP an installation that does not
+ * exist yet, generating and placing every credential it needs. Only Zerops declares it, because only
+ * there is a from-scratch bring-up a sequence of API calls; on Cloudflare the same ground is covered by
+ * `init` plus the workflow it scaffolds.
+ *
+ * `admin` admits the FIRST HUMAN to an installation that already runs. It is a verb of its own rather
+ * than a step of `install`, because it is the one command that is useful long after the bring-up: an
+ * installation whose only administrator left needs it, and a bring-up that got as far as the console
+ * does not need to be repeated to use it.
+ *
+ * `upgrade` rolls a RUNNING installation onto a newer published fabrika release. It is separate from
+ * `deploy` because the two run in different places: `deploy` runs inside the operator's own pipeline
+ * and brings an installation to the checkout it was handed, while `upgrade` runs on the operator's
+ * machine and moves the pin that pipeline reads. A provider whose operator edits no pin does not
+ * declare it.
+ *
+ * `guide` prints the operator's procedure for the whole bring-up, with the traps the per-command usage
+ * cannot show. It ships with the provider package, so an agent reads the guide of the release it runs.
+ */
+export type InstallationCommand = 'init' | 'install' | 'plan' | 'deploy' | 'admin' | 'upgrade' | 'guide';
+export declare const isInstallationCommand: (value: unknown) => value is InstallationCommand;
+export interface InstallationCli {
+    readonly provider: string;
+    readonly commands: readonly InstallationCommand[];
+    readonly usage: string;
+    run(command: InstallationCommand, argv: readonly string[]): Promise<void>;
+}
+export interface InstallationCliModule {
+    readonly installationCli: InstallationCli;
+}
+export declare const isInstallationCli: (value: unknown) => value is InstallationCli;
+export declare const supportsInstallationCommand: (installation: InstallationCli, command: InstallationCommand) => boolean;
+export declare const installationCliFromModule: (value: unknown, expectedProvider?: string) => InstallationCli;

package/types/src/json.d.ts

@@ -0,0 +1,17 @@
+/** A value that can cross the provider persistence boundary without provider-specific types. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Persisted provider data. The provider owns the payload schema and its version. */
+export interface ProviderEnvelope {
+    readonly provider: string;
+    readonly version: number;
+    readonly payload: JsonValue;
+}
+/** Converts one provider-owned value to and from its versioned JSON payload. */
+export interface ProviderCodec<T> {
+    readonly version: number;
+    encode(value: T): JsonValue;
+    decode(payload: JsonValue): T;
+}
+export declare const decodeEnvelope: <T>(kind: string, provider: string, envelope: ProviderEnvelope, codec: ProviderCodec<T>) => T;

package/types/src/schema.d.ts

@@ -0,0 +1,17 @@
+import type { AppSchema } from '@fabrika/auth-core';
+/** Inputs needed to reconcile one app's authorization vocabulary into IAM. */
+export interface SchemaReconcileInput {
+    url: string;
+    app: string;
+    schema: AppSchema;
+    /**
+     * Every origin IAM may hand this app a session at, as known by the control plane. Omitted leaves
+     * IAM's registry alone; a supplied set replaces it. It travels beside the schema and never inside
+     * it — an app declares its vocabulary, the control plane declares where the app lives.
+     */
+    returnOrigins?: readonly string[];
+    adminKey?: string;
+    signal: AbortSignal;
+}
+/** Provider-neutral port for authorization schema reconciliation. */
+export type SchemaReconciler = (input: SchemaReconcileInput) => Promise<void>;

package/types/src/steps.d.ts

@@ -0,0 +1,23 @@
+/** What happened to one provider deploy step. */
+export interface DeployStepResult {
+    readonly id: string;
+    readonly status: 'succeeded' | 'failed' | 'skipped';
+    readonly error?: string;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+}
+export interface RunStepsOptions {
+    readonly appId: string;
+    readonly env: string;
+    readonly dryRun: boolean;
+    readonly signal: AbortSignal;
+    readonly log: (line: string) => void;
+}
+/** Run a provider's steps in order. The first failure or a cancellation skips every later step. */
+export declare const runSteps: <TStep extends {
+    readonly id: string;
+    readonly description: string;
+}>(steps: readonly TStep[], options: RunStepsOptions, runOne: (step: TStep) => Promise<void>) => Promise<{
+    readonly status: "succeeded" | "failed";
+    readonly steps: readonly DeployStepResult[];
+}>;