@fabrika/provider-zerops 0.8.1 → 0.9.0-cloudflare.1

package/src/installation/deploy.ts

@@ -21,21 +21,35 @@
 //
 // It composes the proxy manifest and ships it in the proxy's build archive. It writes the exact namespace
 // planning source default and the per-installation configuration derived from the resolved public hosts
-// (each service's own origin, the origins it must know about, and the installation's environment name). **It writes no credential at all** — every
-// secret an installation holds is `platform init`'s to place, and a deploy that cannot write one cannot
-// leak one. The two credentials this command HOLDS are the Zerops access token and the IAM admin key,
-// both from the environment, neither ever logged.
+// (each service's own origin, the origins it must know about, and the installation's environment name),
+// and the platform database's backup schedule. **It writes one credential, and only a derived one**: the
+// secret the proxy proves its requests to IAM with, HMAC-SHA256 of a fixed label keyed by the IAM admin key,
+// written sensitive to `proxy` and `iam` and never read back. Every other secret an installation holds is
+// `platform install`'s to place. The two credentials this command HOLDS are the Zerops access token and the
+// IAM admin key, both from the environment, neither ever logged.
 //
 // ── Idempotence ───────────────────────────────────────────────────────────────────────────────────
 //
-// Every variable is READ before it is written and skipped when it already matches, so a second run
-// writes nothing; the subdomain is decided by reading `subdomainAccess` back, so a second run enables
-// nothing; and the schema reconcile is an upsert. What a re-run does do is redeploy — that is what
-// "deploy" means, and the platform keeps the previous version serving whenever the new one fails its
+// Every readable variable is READ before it is written and skipped when it already matches, so a second
+// run writes only the derived secret, which it cannot read back; the subdomain is decided by reading
+// `subdomainAccess` back, so a second run enables nothing; the database's backup period is read and set
+// only when it differs; and the schema reconcile is an upsert. What a re-run does do is redeploy — that is
+// what "deploy" means, and the platform keeps the previous version serving whenever the new one fails its
 // readiness gate.
 
-import { FABRIKA_SERVICE_TABLE_DIGEST, readEnvironmentName } from '@fabrika/auth-core'
+import { IAM_PROXY_SECRET_VARIABLE, readEnvironmentName } from '@fabrika/auth-core'
 import { IAM_APP_ID, IAM_APP_SCHEMA } from '@fabrika/iam-contract'
+import {
+	deployedServiceEnvironment,
+	IAM_OAUTH_CONFIG_VARIABLE,
+	type IamOAuthConfig,
+	platformIamOAuthConfig,
+	platformOrigin,
+	platformProxyAppFor,
+	type PlatformProxyComposition,
+	platformServiceTableDigest,
+	resolvePlatformProxyManifest,
+} from '@fabrika/installation-init'
 import type { SchemaReconciler } from '@fabrika/provider-contract'
 import { encodeProxyManifestJson, FABRIKA_PROXY_MANIFEST_JSON } from '@fabrika/proxy-core/manifest'
 import { assertServiceEnvValueFits } from '../api'
@@ -44,12 +58,14 @@ import {
 	prepareZeropsDescriptor,
 	readableContent,
 	type Sleeper,
+	waitForProcess,
 	ZEROPS_ACTIVE,
 	ZEROPS_SERVICE_NOT_HTTP,
 	ZEROPS_TERMINAL,
 	type ZeropsApi,
 	ZeropsApiError,
 	type ZeropsNamespaceProxySource,
+	type ZeropsProcess,
 	type ZeropsService,
 	type ZeropsServiceEnv,
 } from '../index'
@@ -58,7 +74,7 @@ import { assertCheckerPublished, type CheckerPublication } from './checker-relea
 import type { PlatformDeployInput } from './deploy-options'
 import { PLATFORM_CONSOLE_APP_SCHEMA } from './generated/platform-console-schema'
 import { PLATFORM_PROXY_MANIFEST_TEMPLATE } from './generated/platform-proxy-manifest'
-import { derivePlatformHosts, platformOrigin, type PlatformPlacement, ZEROPS_SUBDOMAIN_VARIABLE } from './hosts'
+import { derivePlatformHosts, type PlatformPlacement, ZEROPS_SUBDOMAIN_VARIABLE } from './hosts'
 import { PRIVATE_IAM_UPSTREAM } from './install-environment'
 import {
 	FABRIKA_ZEROPS_PROXY_SOURCE_JSON,
@@ -68,11 +84,9 @@ import {
 	validateInstallationSetups,
 } from './installation-source'
 import type { DeployLog } from './log'
-import { type IamOAuthConfig, platformIamOAuthConfig } from './mcp'
 import { archiveWithDataFile } from './platform-archive'
 import type { PreparedPlatformSource } from './platform-source'
 import { type PlatformUploadFetch, uploadPlatformArchive } from './platform-upload'
-import { platformProxyAppFor, type PlatformProxyComposition, platformServiceTableDigest, resolvePlatformProxyManifest } from './proxy-manifest'
 
 /**
  * The four services this command touches, in the order it RESOLVES and WRITES them.
@@ -112,6 +126,18 @@ export const PLATFORM_SEQUENTIAL_DEPLOY = ['proxy', 'control'] as const
 /** The proxy's hostname. The only publicly routed service, and the one that carries the manifest. */
 export const PLATFORM_PROXY_SERVICE = 'proxy'
 
+/** IAM's and control's database, on both tiers. This command deploys nothing to it; it sets its backup schedule. */
+export const PLATFORM_DATABASE_SERVICE = 'db'
+
+/** Operations' own database. A light installation created before it existed keeps Operations in `db`. */
+export const OPERATIONS_DATABASE_SERVICE = 'operationsdb'
+
+/**
+ * Hourly. Zerops has no point-in-time recovery: a single-node database loses everything since its last `pg_dump`, which
+ * by default is daily. UNVERIFIED: that `backupPeriod` takes this 5-field cron, as the GUI documentation describes.
+ */
+export const PLATFORM_DATABASE_BACKUP_PERIOD = '0 * * * *'
+
 /** How often a triggered pipeline is polled. */
 const POLL_INTERVAL_MS = 5_000
 /** Zerops caps a build pipeline at one hour; poll past that so the timeout is ours, not a coincidence. */
@@ -208,43 +234,58 @@ const resolveProject = async (
 /** The private source service of an earlier layout; Control now streams sources itself (ADR-0029). */
 const LEFTOVER_SOURCE_SERVICE = 'source'
 
+/** The services this command touches: the four it deploys, and the database whose backups it schedules. */
+interface ResolvedInstallation {
+	readonly services: ReadonlyMap<PlatformDeployService, ResolvedService>
+	readonly databaseId: string
+	readonly hasOperationsDatabase: boolean
+}
+
 /**
  * Find every platform service by hostname in one listing.
  *
- * One call rather than four `findService` lookups, so a missing service is reported as the whole set
+ * One call rather than five `findService` lookups, so a missing service is reported as the whole set
  * that is missing — an installation that was never imported fails once, naming all of it, rather than
- * four runs later. Build runtimes (`build<hostname>v<n>`) share the project and are ignored by the
+ * five runs later. Build runtimes (`build<hostname>v<n>`) share the project and are ignored by the
  * exact-name match.
  */
 const resolveServices = async (
 	projectId: string,
 	{ api, log, signal }: PlatformDeployCollaborators,
-): Promise<Map<PlatformDeployService, ResolvedService>> => {
+): Promise<ResolvedInstallation> => {
 	const services = await api.listProjectServices({ projectId, signal })
 	if (services.some((service: ZeropsService) => service.name === LEFTOVER_SOURCE_SERVICE)) {
 		log.warn('a `source` service from an earlier layout is present and unused; it may still hold GitHub App keys; delete it or reinstall')
 	}
-	const resolved = new Map<PlatformDeployService, ResolvedService>()
-	const missing: string[] = []
-	for (const hostname of PLATFORM_DEPLOY_ORDER) {
+	const idOf = (hostname: string): string | undefined => {
 		const matches = services.filter((service: ZeropsService) => service.name === hostname)
 		if (matches.length > 1) {
 			throw new Error(`Zerops project ${projectId} has ${matches.length} services named \`${hostname}\``)
 		}
 		const match = matches[0]
-		if (match === undefined || match.id === '') {
+		return match === undefined || match.id === '' ? undefined : match.id
+	}
+	const resolved = new Map<PlatformDeployService, ResolvedService>()
+	const missing: string[] = []
+	for (const hostname of PLATFORM_DEPLOY_ORDER) {
+		const id = idOf(hostname)
+		if (id === undefined) {
 			missing.push(hostname)
 			continue
 		}
-		resolved.set(hostname, { hostname, id: match.id })
+		resolved.set(hostname, { hostname, id })
 	}
-	if (missing.length > 0) {
+	const databaseId = idOf(PLATFORM_DATABASE_SERVICE)
+	if (databaseId === undefined) {
+		missing.push(PLATFORM_DATABASE_SERVICE)
+	}
+	if (missing.length > 0 || databaseId === undefined) {
 		throw new Error(
 			`Zerops project ${projectId} has no ${missing.join(', ')} service — \`platform deploy\` updates an installation, `
 				+ 'it does not create one',
 		)
 	}
-	return resolved
+	return { services: resolved, databaseId, hasOperationsDatabase: idOf(OPERATIONS_DATABASE_SERVICE) !== undefined }
 }
 
 export const serviceOf = (services: ReadonlyMap<PlatformDeployService, ResolvedService>, hostname: PlatformDeployService): ResolvedService => {
@@ -290,78 +331,56 @@ const resolvePlacement = (input: PlatformDeployInput, proxyEnv: LiveServiceEnv):
 	return { hosts: derivePlatformHosts(subdomains, listeners), scheme: input.scheme, zeropsSubdomain: true }
 }
 
-const IAM_OAUTH_CONFIG = 'FABRIKA_IAM_OAUTH_CONFIG'
+/** The credentials this command writes. Sensitive, so they cannot be compared and are rewritten on every deploy. */
+const SENSITIVE_DEPLOY_KEYS: ReadonlySet<string> = new Set([IAM_PROXY_SECRET_VARIABLE])
 
 /**
- * The per-installation configuration each service needs, derived from the resolved hosts.
+ * The per-installation configuration each service needs, derived from the resolved hosts: fabrika's
+ * (`deployedServiceEnvironment`), and control's Zerops variables after it.
  *
  * The namespace source default comes from the verified snapshot. Values are compared but never logged.
- * IAM's OAuth configuration is written only when MCP authoring is enabled; without it the variable is
- * left as it is, and the manifest — whose `/mcp` row then admits no OAuth token — is what turns MCP off.
  */
 const desiredServiceEnv = (
 	environment: string,
+	projectId: string,
 	placement: PlatformPlacement,
 	proxySource: ZeropsNamespaceProxySource,
 	oauthConfig: IamOAuthConfig | undefined,
 	controlTableDigest: string,
+	iamAdminKey: string,
 ): ReadonlyMap<PlatformDeployService, ReadonlyMap<string, string>> => {
-	const iamOrigin = platformOrigin(placement.scheme, placement.hosts.iam)
-	const operationsOrigin = platformOrigin(placement.scheme, placement.hosts.operations)
-	const iam = new Map([
-		['ENVIRONMENT', environment],
-		// The `iss` of every minted token AND the OIDC redirect base, so it must be the address
-		// routed to the proxy in front of this service.
-		['ISSUER', iamOrigin],
+	const fabrika = deployedServiceEnvironment({
+		environment,
+		scheme: placement.scheme,
+		hosts: placement.hosts,
+		iamUpstream: PRIVATE_IAM_UPSTREAM,
+		provisioningKey: iamAdminKey,
+		controlTableDigest,
+		...(oauthConfig === undefined ? {} : { oauthConfig }),
+	})
+	const control = new Map([
+		...fabrika.control,
+		[FABRIKA_ZEROPS_PROXY_SOURCE_JSON, serializeNamespaceProxySource(proxySource)],
+		// The public IAM origin an APPLICATION project's proxy reaches — there is no private
+		// network between projects (ADR-0006).
+		['FABRIKA_ZEROPS_PROXY_IAM_URL', platformOrigin(placement.scheme, placement.hosts.iam)],
+		// The installation's own project, which no deployment namespace may adopt: its proxy is the
+		// platform's enforcement point, and a namespace reconcile would rebuild it with only app members.
+		['FABRIKA_ZEROPS_PLATFORM_PROJECT_ID', projectId],
 	])
-	if (oauthConfig !== undefined) {
-		iam.set(IAM_OAUTH_CONFIG, JSON.stringify(oauthConfig))
-	}
 	return new Map<PlatformDeployService, ReadonlyMap<string, string>>([
-		['iam', iam],
-		[
-			'operations',
-			new Map([
-				['ENVIRONMENT', environment],
-				['FABRIKA_IAM_ISSUER', iamOrigin],
-				['FABRIKA_OPERATIONS_PUBLIC_HOST', placement.hosts.operations],
-			]),
-		],
-		[
-			'proxy',
-			new Map([
-				['ENVIRONMENT', environment],
-				// Compared byte-for-byte against a token's `iss`, so this is the PUBLIC issuer and not the
-				// private `iam:3000` the manifest dials — `readProxyEnv` canonicalizes it to an origin.
-				['FABRIKA_IAM_ISSUER', iamOrigin],
-				['FABRIKA_PROXY_SESSION_OWNER_JSON', JSON.stringify({ issuer: iamOrigin, upstream: PRIVATE_IAM_UPSTREAM })],
-			]),
-		],
-		[
-			'control',
-			new Map([
-				[FABRIKA_ZEROPS_PROXY_SOURCE_JSON, serializeNamespaceProxySource(proxySource)],
-				['ENVIRONMENT', environment],
-				['FABRIKA_IAM_ISSUER', iamOrigin],
-				// A bare host: `controlPublicOrigin` accepts either spelling.
-				['FABRIKA_CONTROL_DOMAIN', placement.hosts.control],
-				// The digest of the console table the proxy above publishes: Control picks its own table, MCP or not,
-				// by it, and refuses to start under another, so the two cannot disagree at runtime.
-				[FABRIKA_SERVICE_TABLE_DIGEST, controlTableDigest],
-				['OPERATIONS_ARTIFACT_ORIGIN', operationsOrigin],
-				// The public IAM origin an APPLICATION project's proxy reaches — there is no private
-				// network between projects (ADR-0006).
-				['FABRIKA_ZEROPS_PROXY_IAM_URL', iamOrigin],
-			]),
-		],
+		['iam', fabrika.iam],
+		['operations', fabrika.operations],
+		['proxy', fabrika.proxy],
+		['control', control],
 	])
 }
 
 /**
  * Write only what differs. Returns the KEYS written — never a value, not even in a debug line.
  *
- * Nothing here is a credential, so everything is written readable. A record an older release wrote
- * sensitive reads as different and is rewritten readable, which is what lets the next deploy compare it.
+ * Everything but `SENSITIVE_DEPLOY_KEYS` is written readable. A record an older release wrote sensitive
+ * reads as different and is rewritten readable, which is what lets the next deploy compare it.
  */
 const applyServiceEnv = async (
 	service: ResolvedService,
@@ -372,7 +391,8 @@ const applyServiceEnv = async (
 ): Promise<string[]> => {
 	const written: string[] = []
 	for (const [key, value] of desired) {
-		if (readableContent(live.get(key)) === value) {
+		const sensitive = SENSITIVE_DEPLOY_KEYS.has(key)
+		if (!sensitive && readableContent(live.get(key)) === value) {
 			continue
 		}
 		written.push(key)
@@ -382,7 +402,7 @@ const applyServiceEnv = async (
 			continue
 		}
 		assertRunning(collaborators.signal)
-		await collaborators.api.putServiceEnv({ serviceId: service.id, key, value, sensitive: false, signal: collaborators.signal })
+		await collaborators.api.putServiceEnv({ serviceId: service.id, key, value, sensitive, signal: collaborators.signal })
 	}
 	return written
 }
@@ -591,6 +611,111 @@ const ensureSubdomainAccess = async (
 	}
 }
 
+/** What `ensureBackupPeriod` found and did. */
+export type BackupPeriodOutcome =
+	| { readonly kind: 'unchanged' }
+	| { readonly kind: 'kept'; readonly current: string }
+	| { readonly kind: 'would-change'; readonly from: string }
+	| { readonly kind: 'changed'; readonly from: string }
+	| { readonly kind: 'unconfirmed'; readonly readBack: string }
+
+/**
+ * Whether a period is one the operator did not choose: empty, or once a day (`<minute> <hour> * * *`), which is the
+ * shape of the platform's daily default. Anything else is kept. UNVERIFIED: how the platform spells its default.
+ */
+const isDailyBackupPeriod = (period: string): boolean => period.trim() === '' || /^\d+ \d+ \* \* \*$/.test(period.trim())
+
+/**
+ * Set a managed service's backup period, read-compare-write, replacing only a daily one.
+ *
+ * A different period is sent with the retention the service reads — its own, else the default — WHOLE, because a
+ * PUT on this API resets what it leaves out. The decision is the read-back, never the PUT returning.
+ */
+export const ensureBackupPeriod = async (input: {
+	readonly api: Pick<ZeropsApi, 'getBackupConfig' | 'configureBackup' | 'getProcess'>
+	readonly sleep: Sleeper
+	readonly signal: AbortSignal
+	readonly serviceId: string
+	readonly hostname: string
+	readonly period: string
+	readonly dryRun: boolean
+}): Promise<BackupPeriodOutcome> => {
+	const { api, sleep, signal, serviceId, hostname, period } = input
+	const current = await api.getBackupConfig({ serviceId, signal })
+	if (current.backupPeriod === period) {
+		return { kind: 'unchanged' }
+	}
+	if (!isDailyBackupPeriod(current.backupPeriod)) {
+		return { kind: 'kept', current: current.backupPeriod }
+	}
+	if (input.dryRun) {
+		return { kind: 'would-change', from: current.backupPeriod }
+	}
+	assertRunning(signal)
+	let process: ZeropsProcess | null
+	try {
+		process = await api.configureBackup({
+			serviceId,
+			backupPeriod: period,
+			retentionPolicy: current.retentionPolicy ?? current.defaultRetentionPolicy,
+			signal,
+		})
+	} catch (error) {
+		if (error instanceof ZeropsApiError && error.status >= 400 && error.status < 500) {
+			throw new Error(`zerops: setting the backup schedule of ${hostname} was refused (${error.code === '' ? error.status : error.code})`)
+		}
+		throw error
+	}
+	if (process !== null) {
+		await waitForProcess({ api, processId: process.id, sleep, signal, label: `the backup schedule change of ${hostname}` })
+	}
+	const after = await api.getBackupConfig({ serviceId, signal })
+	if (after.backupPeriod !== period) {
+		return { kind: 'unconfirmed', readBack: after.backupPeriod }
+	}
+	return { kind: 'changed', from: current.backupPeriod }
+}
+
+/** `ensureBackupPeriod` on the platform database, reported as one log line; nothing it meets fails the deploy. */
+const scheduleDatabaseBackups = async (databaseId: string, dryRun: boolean, collaborators: PlatformDeployCollaborators): Promise<void> => {
+	const { log, signal } = collaborators
+	const db = PLATFORM_DATABASE_SERVICE
+	const schedule = `\`${PLATFORM_DATABASE_BACKUP_PERIOD}\``
+	let backup: BackupPeriodOutcome
+	try {
+		backup = await ensureBackupPeriod({
+			api: collaborators.api,
+			sleep: collaborators.sleep,
+			signal,
+			serviceId: databaseId,
+			hostname: db,
+			period: PLATFORM_DATABASE_BACKUP_PERIOD,
+			dryRun,
+		})
+	} catch (error) {
+		if (signal.aborted) throw error
+		log.warn(`${db}: the backup schedule was not set (${error instanceof Error ? error.message : 'unknown error'}); set it to ${schedule} by hand`)
+		return
+	}
+	switch (backup.kind) {
+		case 'unchanged':
+			log.info(`${db}: backups already run on ${schedule}`)
+			return
+		case 'kept':
+			log.info(`${db}: backups keep the schedule \`${backup.current}\` someone chose instead of the daily default`)
+			return
+		case 'would-change':
+			log.info(`${db}: backups would run on ${schedule}, were \`${backup.from}\``)
+			return
+		case 'changed':
+			log.info(`${db}: backups now run on ${schedule}, were \`${backup.from}\``)
+			return
+		case 'unconfirmed':
+			log.warn(`${db}: backups were set to ${schedule} but read back \`${backup.readBack}\`; check the schedule by hand`)
+			return
+	}
+}
+
 /**
  * The installation's environment name, refused when a public origin contradicts it.
  *
@@ -637,7 +762,7 @@ export const deployPreparedPlatform = async (
 
 	log.step('Resolve the installation')
 	const project = await resolveProject(input, collaborators)
-	const services = await resolveServices(project.id, collaborators)
+	const { services, databaseId, hasOperationsDatabase } = await resolveServices(project.id, collaborators)
 	log.info(`project ${project.name} (${project.id}) — ${PLATFORM_DEPLOY_ORDER.join(', ')}`)
 
 	const proxy = serviceOf(services, PLATFORM_PROXY_SERVICE)
@@ -670,15 +795,23 @@ export const deployPreparedPlatform = async (
 
 	log.step('Write the service environment')
 	const controlTableDigest = platformServiceTableDigest(platformManifest, platformProxyAppFor(PLATFORM_PROXY_MANIFEST_TEMPLATE, 'control').id)
-	const desired = desiredServiceEnv(environment, placement, proxySource, oauthConfig, controlTableDigest)
+	const desired = desiredServiceEnv(
+		environment,
+		project.id,
+		placement,
+		proxySource,
+		oauthConfig,
+		controlTableDigest,
+		input.iamAdminKey,
+	)
 	for (const hostname of PLATFORM_DEPLOY_ORDER) {
 		const service = serviceOf(services, hostname)
 		const live = hostname === PLATFORM_PROXY_SERVICE ? proxyEnv : await readServiceEnv(service.id, collaborators)
 		const keys = desired.get(hostname) ?? new Map<string, string>()
-		const liveOAuthConfig = live.get(IAM_OAUTH_CONFIG)
+		const liveOAuthConfig = live.get(IAM_OAUTH_CONFIG_VARIABLE)
 		const oauthStillSet = liveOAuthConfig !== undefined && (liveOAuthConfig.sensitive || liveOAuthConfig.content.trim() !== '')
 		if (hostname === 'iam' && oauthConfig === undefined && oauthStillSet) {
-			log.warn(`iam: MCP authoring is off but ${IAM_OAUTH_CONFIG} is still set; IAM keeps issuing MCP tokens until it is removed`)
+			log.warn(`iam: MCP authoring is off but ${IAM_OAUTH_CONFIG_VARIABLE} is still set; IAM keeps issuing MCP tokens until it is removed`)
 		}
 		const written = await applyServiceEnv(service, keys, live, input, collaborators)
 		log.info(
@@ -746,5 +879,17 @@ export const deployPreparedPlatform = async (
 		log.info(`\`${IAM_APP_ID}\` reconciled`)
 	}
 
+	// Last, and a warning rather than a failure: the backup API's behaviour is not yet measured on a live account
+	// (docs/reference/zerops-platform.md), and every service is already deployed, published and registered.
+	log.step('Schedule the platform database backups')
+	if (hasOperationsDatabase) {
+		await scheduleDatabaseBackups(databaseId, input.dryRun, collaborators)
+	} else {
+		log.warn(
+			`${PLATFORM_DATABASE_SERVICE}: backups keep their schedule — Operations shares this database on an installation `
+				+ `created before \`${OPERATIONS_DATABASE_SERVICE}\`, and hourly dumps would copy its whole error history`,
+		)
+	}
+
 	log.step(input.dryRun ? 'Dry run complete — nothing was written' : 'Installation deployed')
 }

package/src/installation/generated/platform-console-schema.ts

@@ -30,6 +30,9 @@ export const PLATFORM_CONSOLE_APP_SCHEMA: AppSchema = {
 		{ action: 'mail.read', description: 'List relayed mail and read its metadata' },
 		{ action: 'mail.content.read', description: 'Read the recipient, subject and bodies of relayed mail' },
 		{ action: 'mail.manage', description: 'Release or drop held mail and manage the mail rules' },
+		{ action: 'data.read', description: 'Read the sizes, counts, state and backup list of environment data' },
+		{ action: 'data.content.read', description: 'Read the row contents, exports and backups of every tenant (global grant only)' },
+		{ action: 'data.manage', description: 'Run maintenance, backups and restores, and recover an interrupted operation' },
 		{ action: 'operations.read', description: 'Read Operations errors and activity' },
 		{ action: 'operations.triage', description: 'Triage Operations errors' },
 		{ action: 'operations.manage', description: 'Manage Operations sources, alerts, and retention' },

package/src/installation/generated/platform-proxy-manifest.ts

@@ -16,7 +16,7 @@
 // `table` and registers the resource only on an installation that enables MCP authoring, and its
 // `tableWithoutOAuth` otherwise.
 
-import type { PlatformProxyManifestTemplate } from '../proxy-manifest'
+import type { PlatformProxyManifestTemplate } from '@fabrika/installation-init'
 
 export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
 	apps: [
@@ -258,6 +258,16 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
 						admission: null,
 						oauth: null,
 					},
+					{
+						id: 'dev-source',
+						kind: 'protocol',
+						method: 'POST',
+						path: '/platform/source/*',
+						callers: [],
+						requirement: null,
+						admission: null,
+						oauth: null,
+					},
 					{
 						id: 'webhooks-root',
 						kind: 'service',
@@ -453,6 +463,16 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
 						admission: null,
 						oauth: null,
 					},
+					{
+						id: 'dev-source',
+						kind: 'protocol',
+						method: 'POST',
+						path: '/platform/source/*',
+						callers: [],
+						requirement: null,
+						admission: null,
+						oauth: null,
+					},
 					{
 						id: 'webhooks-root',
 						kind: 'service',

package/src/installation/guide.md

@@ -44,16 +44,41 @@ cores and 48 GB per container, and costs more while it does.
 **1. Platform tier** (`platform install --tier`, step 1). Cannot be changed later: a project's core package
 is upgrade-only, and the data services differ.
 
-| Tier              | What runs                                                                                                                                                                           | Idle floor | Fails when                                               |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------- |
-| `light` (default) | Lightweight core. One single-node PostgreSQL (`oltp-hobby`) and one bucket shared by IAM, control and Operations; one container each.                                               | about $6   | any one container or the database is down: sign-in stops |
-| `standard`        | Serious core. HA PostgreSQL (3 nodes, `oltp-production`, dedicated CPU) for IAM and control; a second HA PostgreSQL and bucket for Operations; two containers of IAM and the proxy. | about $100 | survives the loss of one node of each                    |
+| Tier              | What runs                                                                                                                                                                           | Idle floor  | Fails when                                       |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------ |
+| `light` (default) | Lightweight core. Two single-node PostgreSQL (`oltp-hobby`): `db` for IAM and control, `operationsdb` for Operations; one shared bucket; one container each.                        | about $7.50 | any one container or `db` is down: sign-in stops |
+| `standard`        | Serious core. HA PostgreSQL (3 nodes, `oltp-production`, dedicated CPU) for IAM and control; a second HA PostgreSQL and bucket for Operations; two containers of IAM and the proxy. | about $100  | survives the loss of one node of each            |
 
 Most of `standard`'s price is the identity database's dedicated floor (about $72). `light` is right for an
 evaluation and a small fleet that tolerates an outage; `standard` for sign-in that must stay up.
 
+**What a lost node costs.** Zerops has no point-in-time recovery. Its backups are logical dumps of a whole
+database service, daily between 00:00 and 01:00 UTC unless the service sets another schedule, and a restore is
+manual (download, then `pg_restore`). A single-node PostgreSQL whose node fails loses everything written since
+its last backup and stays down until someone restores it. An HA PostgreSQL (three nodes) keeps both its data and
+its service. Zerops documents that a deploy starts the new container before it stops the old one, so a deploy
+should not take a one-container runtime down; neither that nor how fast Zerops replaces a container lost with its
+node is measured here. `platform install` and every `platform deploy` set the platform database `db` (users,
+grants, deploy records) to back up hourly, unless someone chose another schedule; a light installation created
+before `operationsdb` existed keeps its schedule. Hourly backups may shorten how far back the restore points
+reach: if Zerops tags each one `daily`, the retention's daily count counts hours. Check `db`'s retention in the GUI. Operations' own `operationsdb`
+keeps the daily default: its error history does not need that schedule.
+
+**Presets.** The choices below combine into three shapes. Prices are the idle floor for three applications in
+one production namespace; an application with a database runs at a 0.5 GB floor, about $2.10 per container.
+
+| Preset     | Platform tier | Production namespace                                                                                | Idle floor | A lost node costs                                                 |
+| ---------- | ------------- | --------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------- |
+| evaluation | `light`       | `cheap`, single-node PostgreSQL, one container each                                                 | about $16  | the data written since that database's last backup, and an outage |
+| data       | `light`       | `cheap` with `--postgres-type=postgresql:ha@18 --postgres-profile=oltp-staging`, one container each | about $26  | applications' data survives; platform data since its last backup  |
+| stable     | `standard`    | `cheap` HA as above, `--core-package=SERIOUS`, two containers of each application                   | $130+      | a short failover; the namespace proxy has one container           |
+
+A staging namespace (`cheap`, single-node) adds about $9 to any of them.
+
 **2. Namespace preset** (`control namespaces create --preset`, step 5). A namespace is the Zerops project
-applications run in. Each one adds its own proxy, about $1.08.
+applications run in. Each one adds its own proxy, about $1.08. A `cheap` namespace's shared PostgreSQL is
+single-node unless `--postgres-type=postgresql:ha@18` asks for HA (about $11 at `--postgres-profile=oltp-staging`; the two flags go together);
+the type is fixed once the namespace exists, the profile is not.
 
 | Preset          | Where an application's database lives                                   | Use with                             |
 | --------------- | ----------------------------------------------------------------------- | ------------------------------------ |
@@ -62,8 +87,8 @@ applications run in. Each one adds its own proxy, about $1.08.
 | `full`          | The namespace belongs to ONE application (`--exclusive-app=<id>`)       | an application that must be isolated |
 
 **3. The application's database** (the application's `fabrika.config.ts`, before step 5). The example
-declares `postgresql:single@18` at `oltp-hobby`, about $1.45, plus its runtime from about $1.08 per
-container. `postgresql:ha@18` survives a node failure: about $11 at `oltp-staging` (shared CPU), about $72 at
+declares `postgresql:single@18` at `oltp-hobby`, about $1.45, plus its runtime at about $2.10 per
+container (a deploy raises the floor of an application with a database to 0.5 GB). `postgresql:ha@18` survives a node failure: about $11 at `oltp-staging` (shared CPU), about $72 at
 `oltp-production` (dedicated). Single to HA later means a new service and a data migration.
 
 **4. Namespace core package** (`--core-package=LIGHT|SERIOUS`, step 5). `LIGHT` is free and the default on
@@ -127,10 +152,9 @@ fabrika platform install --provider=zerops --create-project --client-id=<clientI
   over the same project would destroy the vault key. Start over in a new empty project.
 - The account must be in the default region, or set `FABRIKA_ZEROPS_API_URL` for every command.
 - Mail is optional. Without `--email-provider` the installation sends no mail. With one, add
-  `--email-provider=<resend|smartemailing> --email-from=<address>`, optionally `--email-from-name=<name>`, and
-  export the provider's variables (`FABRIKA_EMAIL_RESEND_API_KEY`, or `FABRIKA_EMAIL_SMARTEMAILING_USERNAME`,
-  `FABRIKA_EMAIL_SMARTEMAILING_API_KEY` and optionally `FABRIKA_EMAIL_SMARTEMAILING_TAG`) from their own `0600`
-  files. They have no flag. The install writes the set on `iam` and `control`, the credentials sensitive. They
+  `--email-provider=<provider> --email-from=<address>`, optionally `--email-from-name=<name>`, and export the
+  provider's variables from their own `0600` files. `fabrika platform install --provider=zerops --help` lists the
+  providers and their variables, each named after its provider (for Resend `FABRIKA_EMAIL_RESEND_API_KEY`). They have no flag. The install writes the set on `iam` and `control`, the credentials sensitive. They
   are the human's own, so they are not copied into the secrets file.
 
 **Check.** The log ends with the `Hand off` step: where the credentials are, `The console answers at
@@ -352,7 +376,10 @@ fabrika control namespaces update --namespace=<id> --proxy-source=current
 ```
 
 It re-pins the namespace and queues the reconcile that rebuilds its proxy; poll `namespaces get` until it is
-`ready`. A namespace pinned to a release before the proxy manifest moved into the build archive carries it in a
+`ready`. Re-pin every namespace after each upgrade. Until then, Control refuses a deploy into it that uses a form
+newer than 0.6 (a public procedure, a file output, a capabilities requirement, a forwarded webhook `Authorization`),
+also when its proxy reads the form, and a proxy older than the replacement of the caller's `Authorization` keeps
+forwarding a caller's `px_` key to the application (`docs/reference/deployment-namespaces.md`). A namespace pinned to a release before the proxy manifest moved into the build archive carries it in a
 service variable, which Zerops caps at about 32 KB: when a deploy fails with `serviceEnvValueTooLarge`, this is
 the fix, and it also accepts a namespace in `failed`.
 
@@ -371,12 +398,15 @@ none, and `install` cannot be re-run.
 2. Restart `iam` and `control`. Each reads the transport at boot. IAM refuses to start on an invalid one.
    Control starts, logs a line that names the invalid variables, and refuses every deploy that needs the transport
    until you fix them and restart it.
-3. Redeploy every environment whose contract uses `installation` mail. An application gets the new transport
-   only at its next deploy. Until then it sends with the old one, and a revoked key fails its mail with
-   `provider_unauthorized`.
-
-Without a transport, a contract whose job declares `mailer: 'installation'` still deploys. Its jobs see that mail is
-not available and leave their messages queued. After step 3 the next run sends them.
+3. Redeploy every environment whose contract uses `installation` mail and whose application pins a framework release
+   older than 0.7. Such an application holds its own copy of the transport and gets the new one only at its next
+   deploy. Until then it sends with the old one, and a revoked key fails its mail with `provider_unauthorized`. An
+   application on 0.7 or newer sends through Control's relay, which uses the new transport once step 2 restarted
+   Control: it needs no redeploy.
+
+Without a transport, a contract whose job declares `mailer: 'installation'` still deploys. On a release older than 0.7
+its jobs see that mail is not available and leave their messages queued, and after step 3 the next run sends them. On
+0.7 or newer the relay accepts and holds the messages, and Control sends them once it has a transport.
 
 ## When something fails
 

package/src/installation/hosts.ts

@@ -24,10 +24,7 @@
 // never been deployed publishes none, so the variable names nothing and this refuses rather than
 // guessing at a hostname.
 
-import type { PlatformProxyService } from './proxy-manifest'
-
-/** The public hostname of each platform service, without a scheme and without a port. */
-export type PlatformHosts = Readonly<Record<PlatformProxyService, string>>
+import type { PlatformHosts, PlatformProxyService } from '@fabrika/installation-init'
 
 /** Everything the deploy needs to know about where this installation answers. */
 export interface PlatformPlacement {
@@ -112,6 +109,3 @@ export const derivePlatformHosts = (subdomains: string, listeners: readonly Plat
 	}
 	return { iam, control, operations }
 }
-
-/** `https://<host>` — the origin a browser, a token's `iss` and a return-origin registry all use. */
-export const platformOrigin = (scheme: 'http' | 'https', host: string): string => `${scheme}://${host}`