@fabrika/provider-zerops 0.4.7 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.4.7",
+	"version": "0.5.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -43,13 +43,14 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth": "0.4.7",
-		"@fabrika/auth-core": "0.4.7",
-		"@fabrika/iam-contract": "0.4.7",
-		"@fabrika/installation-init": "0.4.7",
-		"@fabrika/operations-contract": "0.4.7",
-		"@fabrika/provider-contract": "0.4.7",
-		"@fabrika/proxy-core": "0.4.7",
+		"@fabrika/auth": "0.5.0",
+		"@fabrika/auth-core": "0.5.0",
+		"@fabrika/email": "0.5.0",
+		"@fabrika/iam-contract": "0.5.0",
+		"@fabrika/installation-init": "0.5.0",
+		"@fabrika/operations-contract": "0.5.0",
+		"@fabrika/provider-contract": "0.5.0",
+		"@fabrika/proxy-core": "0.5.0",
 		"yaml": "^2.9.1"
 	}
 }

package/src/database-budget.ts

@@ -0,0 +1,68 @@
+// The connection budget of a contract application's PostgreSQL on Zerops (ADR-0043): how many connections each of the
+// application's processes may open, and the RAM its database needs for that to be at least the minimum. PURE.
+
+/**
+ * The RAM steps of a Zerops PostgreSQL service in GB; its `max_connections` follows the step its RAM is in, and a
+ * service between two steps has the lower one's (`docs/reference/zerops-platform.md`, "Connection limits"). Above 8 GB
+ * the steps are multiples of 8 GB; 16 GB is the first with the highest limit.
+ */
+export const ZEROPS_POSTGRES_RAM_STEPS_GB: readonly number[] = [0.25, 0.5, 1, 2, 4, 8, 16]
+
+/** The lowest step, and the smallest RAM a PostgreSQL service is given (`oltp-hobby`'s floor). */
+export const ZEROPS_POSTGRES_MIN_RAM_GB = 0.25
+
+/** Of a service's `max_connections`, what no application role can take: 3 kept for superusers, up to 4 Zerops' own. */
+export const ZEROPS_POSTGRES_UNAVAILABLE_CONNECTIONS = 7
+
+/**
+ * The most connections one container's start script holds at once: `fabrika db test-isolation` peaks at 4 since the
+ * test kit opens a file's connections together, and at 5 with a `@fabrika/db` before that (measured locally,
+ * 2026-10-16, with the Notes and CRM examples). Migrating and reading the schema take fewer, one after the other.
+ */
+export const ZEROPS_START_CONNECTIONS = 5
+
+/** The fewest connections a process may have: a job's fenced write and its cancellation each need one at once. */
+export const MIN_PROCESS_CONNECTIONS = 2
+/** The most a process gets, however large the database: the pool every process had before the platform sized it. */
+export const MAX_PROCESS_CONNECTIONS = 10
+
+/** Zerops' own maximum, which a runtime whose horizontal autoscaling reads nothing may scale to. */
+export const ZEROPS_MAX_CONTAINERS = 10
+
+/** What opens connections to the application's database at once. */
+export interface ZeropsDatabaseDemand {
+	/** The deploy service's maximum container count. */
+	readonly maxContainers: number
+	/** The crontab lines that run `fabrika job run`, each its own process on one container. */
+	readonly jobs: number
+}
+
+/** `max_connections` of a Zerops PostgreSQL service with `ramGB` of RAM and this autoscaling profile. */
+export function zeropsPostgresMaxConnections(ramGB: number, profile: string | undefined): number {
+	const step = ramGB < 8
+		? Math.max(...ZEROPS_POSTGRES_RAM_STEPS_GB.filter((candidate) => candidate <= ramGB), ZEROPS_POSTGRES_MIN_RAM_GB)
+		: Math.floor(ramGB / 8) * 8
+	const [perGB, lowest, highest] = profile?.startsWith('olap-') === true ? [25, 10, 200] : [50, 20, 500]
+	return Math.min(highest, Math.max(lowest, Math.floor(perGB * step)))
+}
+
+/**
+ * The processes that may each hold a full pool at once: while a deploy replaces the containers, every old one still
+ * serves beside its replacement, and each crontab job runs in a process of its own.
+ */
+const poolHolders = (demand: ZeropsDatabaseDemand): number => 2 * demand.maxContainers + demand.jobs
+
+/**
+ * The connections each process may open so that all of them, with one container's start script, stay within what the
+ * application's roles can take; `null` when that is below `MIN_PROCESS_CONNECTIONS`.
+ */
+export function zeropsProcessConnections(maxConnections: number, demand: ZeropsDatabaseDemand): number | null {
+	const available = maxConnections - ZEROPS_POSTGRES_UNAVAILABLE_CONNECTIONS - ZEROPS_START_CONNECTIONS
+	const share = Math.floor(available / poolHolders(demand))
+	return share < MIN_PROCESS_CONNECTIONS ? null : Math.min(share, MAX_PROCESS_CONNECTIONS)
+}
+
+/** The smallest RAM step at which each process gets at least `MIN_PROCESS_CONNECTIONS`, or null when none does. */
+export function zeropsDatabaseMinRam(demand: ZeropsDatabaseDemand, profile: string | undefined): number | null {
+	return ZEROPS_POSTGRES_RAM_STEPS_GB.find((ram) => zeropsProcessConnections(zeropsPostgresMaxConnections(ram, profile), demand) !== null) ?? null
+}

package/src/execution.ts

@@ -93,6 +93,11 @@ export interface ZeropsLockedExecution {
 	readonly contract: ZeropsContractRun
 	/** A `${host_…}` reference to the application's PostgreSQL service, or null when it has none. */
 	readonly databaseUrl: string | null
+	/**
+	 * The most connections each process of the application opens (`FABRIKA_APP_DATABASE_CONNECTIONS`), as the deploy's
+	 * `size-database` step sized it from the database's limit; null until then, and without a database.
+	 */
+	readonly databaseConnections: number | null
 	/** The hostname of the application's one object-storage service, or null when it has none. */
 	readonly storageHostname: string | null
 	readonly runtimePackages: readonly ZeropsRuntimePackage[]
@@ -270,7 +275,7 @@ const migrateScript = (appId: string): readonly string[] => [
 
 // The server starts only after the migrations it expects are applied, the committed schema types match the migrated
 // schema and every generated isolation test passed on a throwaway schema, so any failure fails the readiness check,
-// whether or not a failed `initCommands` stops the activation (an unverified platform fact). The build has no
+// whether or not a failed `initCommands` stops the activation (it does, verified live). The build has no
 // database, so this is where the types and the generated tests run.
 const startScript = (appId: string, database: boolean): readonly string[] => [
 	'#!/bin/sh',
@@ -337,6 +342,18 @@ const storageVariables = (hostname: string): Record<StorageVariable, string> =>
 	FABRIKA_APP_STORAGE_SECRET_ACCESS_KEY: `\${${hostname}_secretAccessKey}`,
 })
 
+/** The crontab lines that run a job of the contract or of the framework, each on one container. */
+const jobCrontab = (contract: ZeropsContractRun): { readonly timing: string; readonly command: string; readonly allContainers: boolean }[] => [
+	...contract.jobs.map((job) => ({ timing: job.schedule, command: `${FABRIKA_BIN} job run ${job.name}`, allContainers: false })),
+	...(contract.files === true
+		? [{ timing: FILE_SWEEP_SCHEDULE, command: `${FABRIKA_BIN} job run ${ZEROPS_FILE_SWEEP_JOB}`, allContainers: false }]
+		: []),
+	...(contract.scan === true ? [{ timing: '* * * * *', command: `${FABRIKA_BIN} job run ${ZEROPS_FILE_SCAN_JOB}`, allContainers: false }] : []),
+]
+
+/** How many job processes the crontab may run at once, each opening the application's database. */
+export const zeropsJobProcesses = (contract: ZeropsContractRun): number => jobCrontab(contract).length
+
 /** The generated selected setup: the authored build kept, everything else the platform's. */
 export function renderLockedSetup(
 	setup: string,
@@ -352,23 +369,13 @@ export function renderLockedSetup(
 		[FABRIKA_CONTRACT_DIGEST]: contract.digest,
 		...(release === null ? {} : { FABRIKA_RELEASE: release }),
 		...(execution.databaseUrl === null ? {} : { FABRIKA_APP_DATABASE_URL: execution.databaseUrl }),
+		...(execution.databaseConnections === null ? {} : { FABRIKA_APP_DATABASE_CONNECTIONS: String(execution.databaseConnections) }),
 		...(execution.storageHostname === null ? {} : storageVariables(execution.storageHostname)),
 	}
 	const scan = contract.scan === true
 	const packages = sortedUnique([...execution.runtimePackages, ...(scan ? [SCANNER_PACKAGE] : [])])
-	const crontab = [
-		...contract.jobs.map((job) => ({ timing: job.schedule, command: `${FABRIKA_BIN} job run ${job.name}`, allContainers: false })),
-		...(contract.files === true
-			? [{ timing: FILE_SWEEP_SCHEDULE, command: `${FABRIKA_BIN} job run ${ZEROPS_FILE_SWEEP_JOB}`, allContainers: false }]
-			: []),
-		// Every container keeps its own signatures; one scan pass at a time holds the job's lease.
-		...(scan
-			? [
-				{ timing: '* * * * *', command: `${FABRIKA_BIN} job run ${ZEROPS_FILE_SCAN_JOB}`, allContainers: false },
-				{ timing: FRESHCLAM_SCHEDULE, command: FRESHCLAM, allContainers: true },
-			]
-			: []),
-	]
+	// Every container keeps its own signatures; one scan pass at a time holds the job's lease.
+	const crontab = [...jobCrontab(contract), ...(scan ? [{ timing: FRESHCLAM_SCHEDULE, command: FRESHCLAM, allContainers: true }] : [])]
 	// A container starts from the prepared image, whose signatures are as old as its build; a failed refresh leaves
 	// them to the daily one, and the scanner refuses signatures older than three days, so the scan fails closed.
 	const initCommands = [

package/src/installation/guide.md

@@ -126,6 +126,12 @@ fabrika platform install --provider=zerops --create-project --client-id=<clientI
 - A project that already holds generated secrets is refused. Do not try to force it: a second bring-up
   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
+  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
 https://<console host>`, and an `ADMIT YOURSELF` box that holds the step 2 command with `--iam-host` filled
@@ -139,9 +145,10 @@ in. The secrets file exists with mode `0600`. The three hosts are printed earlie
   fabrika platform admin --provider=zerops --email=<address> --iam-host=<IAM host from step 1> )
 ```
 
-It prints one enrollment URL and the time it expires. Nothing is e-mailed: the installation has no mail
-service, so do not tell the human to wait for a message. The URL is a credential: give it to the human only,
-and do not log it. The human opens it, sets a password and signs in at the console origin.
+Without a mail provider it prints one enrollment URL and the time it expires. Nothing is e-mailed then, so
+do not tell the human to wait for a message. The URL is a credential: give it to the human only, and do not
+log it. The human opens it, sets a password and signs in at the console origin. With a mail provider, IAM
+e-mails the enrollment instead, and the command reports the address and the expiry.
 
 The URL is valid for ONE HOUR. Hand it over at once. A re-run creates nothing new: while the enrollment is
 unused it only reports that one is outstanding, and it never prints the URL again. To get a new URL, after
@@ -344,6 +351,28 @@ It re-pins the namespace and queues the reconcile that rebuilds its proxy; poll
 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`.
 
+## Set or rotate the mail transport
+
+The installation's mail transport lives on the `iam` and `control` services. Zerops is its record (ADR-0004),
+and Control hands a copy to every application whose job declares `mailer: 'installation'`. To add one to an
+existing installation, change the provider, or rotate a key:
+
+No `fabrika` command does this: `platform upgrade` and `platform deploy` write no `FABRIKA_EMAIL_*` and remove
+none, and `install` cannot be re-run.
+
+1. Set the same `FABRIKA_EMAIL_*` variables on BOTH `iam` and `control`, in the Zerops GUI or with `zcli`:
+   `FABRIKA_EMAIL_PROVIDER`, `FABRIKA_EMAIL_FROM`, optionally `FABRIKA_EMAIL_FROM_NAME`, and the provider's
+   variables. Mark the credentials sensitive. Delete the variables of a provider you leave.
+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.
+
 ## When something fails
 
 - Every refusal names its flag or variable. Fix that one value and re-run. `init`, `admin`, `deploy` and

package/src/installation/index.ts

@@ -1,4 +1,5 @@
 import { reconcileSchema } from '@fabrika/auth'
+import { builtinEmailProviders } from '@fabrika/email/providers'
 import {
 	describeArgument,
 	info as consoleInfo,
@@ -44,6 +45,9 @@ export {
 	resolvePlatformProxyManifest,
 } from './proxy-manifest'
 
+const EMAIL_PROVIDERS = Object.keys(builtinEmailProviders).join(', ')
+const EMAIL_PROVIDER_VARIABLES = Object.values(builtinEmailProviders).flatMap((provider) => provider.variables.map((variable) => variable.name))
+
 const USAGE = `Zerops installation
 
 New here, or an agent? Run \`fabrika platform guide --provider=zerops\` first: the whole bring-up in order,
@@ -86,7 +90,8 @@ is not consent.
      all of them to \`--secrets-file\` (mode 0600) before the first one is placed
   4. pass 1: give the proxy an EMPTY manifest and build it, so it publishes one public hostname per
      HTTP port; the three platform hosts are then READ off those, never composed
-  5. write every remaining variable on all four runtime services
+  5. write every remaining variable on all four runtime services; the mail transport, when one is
+     given, goes to \`iam\` and \`control\` only, its credentials sensitive and not in the secrets file
   6. pass 2: hand the whole ordered sequence to \`platform deploy\`
   7. print the next commands; they read their credentials from the secrets file. Zerops holds the
      same values as SENSITIVE variables and does not hand them back, so that file is the only copy
@@ -118,11 +123,19 @@ Options (a flag beats the environment variable beside it):
   --source-dir=<checkout>           required                       clean full checkout running this CLI
   --tier=<light|standard>           FABRIKA_PLATFORM_TIER           default light
   --secrets-file=<path>             FABRIKA_PLATFORM_SECRETS_FILE   required: a NEW file outside the checkout
+  --email-provider=<name>           FABRIKA_EMAIL_PROVIDER          default none; or one of: ${EMAIL_PROVIDERS}
+  --email-from=<address>            FABRIKA_EMAIL_FROM              the sender, required with a provider
+  --email-from-name=<name>          FABRIKA_EMAIL_FROM_NAME         the sender's display name, optional
   ${UNATTENDED_FLAG}                                                             answer every confirmation yes —
                                                                     required when stdin is not a terminal
 
 	FABRIKA_ZEROPS_ACCESS_TOKEN       required   Zerops access token, environment only and no flag
 	FABRIKA_ZEROPS_API_URL            optional   region API base, when not the default
+	FABRIKA_EMAIL_<PROVIDER>_*        the selected provider's variables, environment only and no flag:
+	                                  ${EMAIL_PROVIDER_VARIABLES.join(', ')}
+
+With a mail provider, IAM sends its own mail and Control hands the same transport to every application
+whose job declares \`mailer: 'installation'\`. To set or rotate it later, see \`platform guide\`.
 
 ── platform init ─────────────────────────────────────────────────────────────────────────────────
 
@@ -266,8 +279,9 @@ Access plane refuses. A re-run creates nobody twice, grants nothing twice and is
 enrollment — a password that is already set, or an enrollment already outstanding, is REPORTED. Pass
 \`${REISSUE_FLAG}\` to replace an outstanding one, which is the way out when the first expired unopened.
 
-Nothing is e-mailed: a Zerops installation has no mail service. Hand the URL to the administrator
-yourself. It is a credential: it is printed once, on a line of its own, and stored nowhere.
+Unless \`install\` was given a mail provider, nothing is e-mailed: IAM then has no mail service. Hand the
+URL to the administrator yourself. It is a credential: it is printed once, on a line of its own, and
+stored nowhere. With a mail provider, IAM e-mails the enrollment and the URL is not printed.
 
 \`install\` reports the host this needs as \`✓ iam <host>\` and ends with this command ready to run.
 

package/src/installation/install-environment.ts

@@ -1,3 +1,4 @@
+import type { InstallationEmail } from '@fabrika/installation-init'
 import { encodeProxyManifestJson } from '@fabrika/proxy-core/manifest'
 import type { ZeropsNamespaceProxySource } from '../index'
 import type { PlatformDeployService, ResolvedService } from './deploy'
@@ -64,6 +65,8 @@ export interface InstallationEnvInput {
 	readonly secrets: InstallationSecrets
 	/** The Zerops integration token minted for the control plane. Never logged, never printed. */
 	readonly zeropsAccessToken: string
+	/** IAM sends its own mail with it, and Control hands it to applications whose job declares `mailer: 'installation'`. */
+	readonly email: InstallationEmail
 }
 
 /**
@@ -120,6 +123,8 @@ export const installationServiceEnv = (input: InstallationEnvInput): ReadonlyMap
 		// the CLI reads `FABRIKA_ZEROPS_API_URL`; they are different processes reading different sources.
 		control.set('FABRIKA_ZEROPS_API_BASE_URL', input.apiBaseUrl)
 	}
+	const email = input.email.kind === 'none' ? [] : [...input.email.variables]
+	for (const [key, value] of email) control.set(key, value)
 	return new Map<PlatformDeployService, ReadonlyMap<string, string>>([
 		[
 			'iam',
@@ -136,6 +141,7 @@ export const installationServiceEnv = (input: InstallationEnvInput): ReadonlyMap
 				['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
 				['FABRIKA_IAM_PROXY_KEY', secrets.proxyKey],
 				['FABRIKA_IAM_PROVISIONING_KEY', secrets.provisioningKey],
+				...email,
 			]),
 		],
 		[
@@ -196,19 +202,19 @@ export const GENERATED_SECRET_KEYS: ReadonlyMap<PlatformDeployService, readonly
  * Write a set of variables, reporting the KEYS — never a value, not even in a debug line.
  *
  * Write-first and unconditional: a generated secret cannot be read back to compare, and `PUT
- * /user-data/{id}` replaces in place, so a repeat costs a call and nothing else. Exactly the generated
- * secrets are written sensitive; everything else stays readable, because `platform deploy` compares
- * and merges it later.
+ * /user-data/{id}` replaces in place, so a repeat costs a call and nothing else. Exactly the `sensitive`
+ * keys are written sensitive (the generated secrets and the operator's mail credentials); everything else
+ * stays readable, because `platform deploy` compares and merges it later.
  */
 export const writeServiceEnv = async (
 	service: ResolvedService,
 	desired: ReadonlyMap<string, string>,
 	{ api, log, signal }: InstallCollaborators,
+	sensitive: ReadonlySet<string>,
 ): Promise<void> => {
-	const secrets = GENERATED_SECRET_KEYS.get(service.hostname) ?? []
 	for (const [key, value] of desired) {
 		assertRunning(signal)
-		await api.putServiceEnv({ serviceId: service.id, key, value, sensitive: secrets.includes(key), signal })
+		await api.putServiceEnv({ serviceId: service.id, key, value, sensitive: sensitive.has(key), signal })
 	}
 	log.ok(`${service.hostname}: wrote ${[...desired.keys()].join(', ')}`)
 }

package/src/installation/install-options.ts

@@ -8,7 +8,18 @@
 // operator's disk — but nothing here prompts: a missing required value is an error naming both the flag
 // and the variable that would supply it, so a mistyped install fails before it contacts anything.
 
-import { describeArgument, readEnv, readFlag, requiredSetting, setting, UNATTENDED_FLAG } from '@fabrika/installation-init'
+import { builtinEmailProviders } from '@fabrika/email/providers'
+import {
+	describeArgument,
+	EMAIL_FLAGS,
+	type InstallationEmail,
+	readEnv,
+	readFlag,
+	readInstallationEmail,
+	requiredSetting,
+	setting,
+	UNATTENDED_FLAG,
+} from '@fabrika/installation-init'
 import { checkedSecretsFilePath, SECRETS_FILE_FLAG, SECRETS_FILE_VARIABLE } from './install-secrets'
 import { parsePlatformScheme } from './placement-options'
 import { readInstallationSourceDir } from './source-options'
@@ -47,6 +58,8 @@ export interface PlatformInstallInput {
 	/** Where every credential this run creates is written, mode 0600, before the first is placed. */
 	readonly secretsFile: string
 	readonly tier: PlatformTier
+	/** The installation's mail transport, written on `iam` and `control`; `none` when the operator named no provider. */
+	readonly email: InstallationEmail
 	/** `--yes`: answer every confirmation yes, for a bring-up with nobody at the keyboard. */
 	readonly unattended: boolean
 }
@@ -54,7 +67,17 @@ export interface PlatformInstallInput {
 /** The canonical public release repository used for namespace proxy source identities. */
 export const FABRIKA_REPOSITORY_URL = 'https://github.com/contember/fabrika-platform'
 
-const FLAGS = ['--project-id', '--project-name', '--client-id', '--env', '--scheme', '--source-dir', '--tier', SECRETS_FILE_FLAG] as const
+const FLAGS = [
+	'--project-id',
+	'--project-name',
+	'--client-id',
+	'--env',
+	'--scheme',
+	'--source-dir',
+	'--tier',
+	SECRETS_FILE_FLAG,
+	...EMAIL_FLAGS,
+] as const
 
 /** `--create-project`: bring the project up too, instead of naming one the operator made. */
 export const CREATE_PROJECT_FLAG = '--create-project'
@@ -151,6 +174,8 @@ export const parsePlatformInstallArgs = (
 			sourceDir,
 		),
 		tier: readTier(setting(argv, env, '--tier', 'FABRIKA_PLATFORM_TIER')),
+		// Optional, so an existing unattended install keeps working and installs without mail.
+		email: readInstallationEmail(argv, env, { registry: builtinEmailProviders, required: false }),
 		unattended: argv.includes(UNATTENDED_FLAG),
 		...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),
 	}

package/src/installation/install.ts

@@ -27,7 +27,7 @@ import { PLATFORM_PROXY_MANIFEST_TEMPLATE } from './generated/platform-proxy-man
 import { derivePlatformHosts, type PlatformHosts, platformOrigin, ZEROPS_SUBDOMAIN_VARIABLE } from './hosts'
 import { checkedEnvironmentName } from './init-options'
 import { assertRunning, type InstallCollaborators, type InstallPrompts } from './install-collaborators'
-import { installationServiceEnv, PASS_ONE_PROXY_MANIFEST, passOneProxyEnv, writeServiceEnv } from './install-environment'
+import { GENERATED_SECRET_KEYS, installationServiceEnv, PASS_ONE_PROXY_MANIFEST, passOneProxyEnv, writeServiceEnv } from './install-environment'
 import type { PlatformInstallInput } from './install-options'
 import { resolveInstallationProject } from './install-project'
 import {
@@ -67,7 +67,7 @@ const passOne = async (
 	if (!(await prompts.confirm(`Write 3 variables on \`proxy\` and build commit ${source.commitSha}? (about 4 minutes)`, true))) {
 		throw new Error('declined: no variable was written, and re-running the install is safe')
 	}
-	await writeServiceEnv(proxy, passOneProxyEnv(secrets), collaborators)
+	await writeServiceEnv(proxy, passOneProxyEnv(secrets), collaborators, new Set(GENERATED_SECRET_KEYS.get(proxy.hostname)))
 	await deployPlatformService(proxy, { source, dryRun: false, proxyManifest: PASS_ONE_PROXY_MANIFEST }, collaborators)
 
 	const proxyEnv = await readServiceEnv(proxy.id, collaborators)
@@ -177,6 +177,7 @@ const installPreparedPlatform = async (
 		proxySource,
 		secrets,
 		zeropsAccessToken: token.token,
+		email: input.email,
 		...(input.apiBaseUrl === undefined ? {} : { apiBaseUrl: input.apiBaseUrl }),
 	})
 	const total = [...desired.values()].reduce((sum, keys) => sum + keys.size, 0)
@@ -187,8 +188,11 @@ const installPreparedPlatform = async (
 				+ `Keep ${input.secretsFile} and arrange operator-owned recovery, or start a fresh installation in a separate empty project`,
 		)
 	}
+	// The mail credentials are the operator's own, so they neither mark an installation nor go to the secrets file.
+	const emailSecrets = input.email.kind === 'none' ? [] : [...input.email.secretNames]
 	for (const hostname of PLATFORM_DEPLOY_ORDER) {
-		await writeServiceEnv(serviceOf(services, hostname), desired.get(hostname) ?? new Map<string, string>(), collaborators)
+		const sensitive = new Set([...(GENERATED_SECRET_KEYS.get(hostname) ?? []), ...emailSecrets])
+		await writeServiceEnv(serviceOf(services, hostname), desired.get(hostname) ?? new Map<string, string>(), collaborators, sensitive)
 	}
 
 	log.step('Pass 2 — deploy the installation')

package/src/installation/topology/setups.ts

@@ -167,13 +167,15 @@ const WORKSPACE_DEPLOY_FILES = ['package.json', 'bun.lock', 'node_modules', 'pac
  * `ENVIRONMENT`, `ISSUER` (this service's public origin; it is the `iss` of every minted token AND the
  * OIDC redirect base, so it must match the domain routed to the proxy in front of it),
  * `HUMAN_EMAIL_DOMAINS`, `HUMAN_EMAILS`, `IAM_BOOTSTRAP_ADMINS`,
- * `FABRIKA_IAM_OIDC_ENABLED`, `FABRIKA_IAM_PASSWORD_ENABLED`, `FABRIKA_EMAIL_PROVIDER`, and
- * `FABRIKA_EMAIL_FROM` when email delivery is enabled. OIDC-enabled installations also set
- * `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_SCOPES`, `OIDC_REQUIRE_VERIFIED_EMAIL`.
+ * `FABRIKA_IAM_OIDC_ENABLED`, `FABRIKA_IAM_PASSWORD_ENABLED`, and the mail transport when email delivery is
+ * enabled: `platform install --email-provider` writes `FABRIKA_EMAIL_PROVIDER`, `FABRIKA_EMAIL_FROM`,
+ * `FABRIKA_EMAIL_FROM_NAME` and the provider's variables on `iam` and `control`, the provider's secret ones
+ * sensitive. OIDC-enabled installations also set `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_SCOPES`,
+ * `OIDC_REQUIRE_VERIFIED_EMAIL`.
  *
  * Secrets (`envSecrets`): `FABRIKA_IAM_SIGNING_KEYS` (ES256 private JWKs — an empty value is refused at
  * boot rather than silently issuing ephemeral tokens), `OIDC_CLIENT_SECRET` when OIDC is enabled,
- * `FABRIKA_EMAIL_RESEND_API_KEY` when Resend is enabled, `FABRIKA_IAM_RPC_KEY` (authenticates
+ * `FABRIKA_IAM_RPC_KEY` (authenticates
  * the management `/rpc/*` surface; unset 404s it, which is the fail-closed default), `FABRIKA_IAM_PROXY_KEY`
  * (authenticates `/auth/mint/*`, which the proxy calls on the cold path — a SEPARATE secret by least privilege,
  * since the proxy is the only publicly routed component and must not also be able to write audit rows),

package/src/managed-env.ts

@@ -4,6 +4,7 @@ import {
 	frameworkVariableReference,
 	isConnectKeyVariable,
 	isConnectUrlVariable,
+	isEmailTransportVariable,
 	isFrameworkVariableName,
 	isWorkloadKeyVariable,
 } from '@fabrika/auth-core'
@@ -67,7 +68,7 @@ export const SENSITIVE_MANAGED_KEYS: ReadonlySet<ManagedKey> = new Set<ManagedKe
 	'FABRIKA_IAM_RPC_KEY',
 ])
 
-/** A workload or connect key is a credential; a connect URL is an origin. */
+/** A workload or connect key and every mail transport variable are written sensitive; a connect URL is an origin. */
 export const isSensitiveFamilyVariable = (name: string): boolean => !isConnectUrlVariable(name)
 
 export type ManagedValues = Record<ManagedKey, string | null>
@@ -93,16 +94,20 @@ export function parseManagedValues(value: unknown): ManagedValues {
 }
 
 /**
- * What Control hands a deploy: the ten managed keys, the key of each job and webhook of the approved contract, and the
- * key and owner origin of each connector import.
+ * What Control hands a deploy: the ten managed keys, the key of each job and webhook of the approved contract, the
+ * key and owner origin of each connector import, and the installation's mail transport when a job sends through it.
  */
 export interface ManagedEnvironment {
 	readonly values: ManagedValues
-	/** `FABRIKA_<KIND>_<NAME>_KEY` → the workload's `px_` key, and `FABRIKA_CONNECT_<IMPORT>_KEY` / `_URL`. */
+	/**
+	 * `FABRIKA_<KIND>_<NAME>_KEY` → the workload's `px_` key, `FABRIKA_CONNECT_<IMPORT>_KEY` / `_URL`, and each
+	 * `FABRIKA_EMAIL_*` of the installation's mail transport.
+	 */
 	readonly familyVariables: Readonly<Record<string, string>>
 }
 
 const keySchema = z.string().startsWith('px_').min(4)
+const mailValueSchema = z.string().min(1)
 const originSchema = z.string().refine((value) => {
 	try {
 		return new URL(value).origin === value && value.startsWith('https://')
@@ -119,6 +124,12 @@ export function parseManagedEnvironment(value: Readonly<Record<string, string |
 			managed[name] = entry
 			continue
 		}
+		if (isEmailTransportVariable(name)) {
+			const parsed = mailValueSchema.safeParse(entry)
+			if (!parsed.success) throw new Error(`zerops: ${name} must not be empty`)
+			familyVariables[name] = parsed.data
+			continue
+		}
 		const origin = isConnectUrlVariable(name)
 		if (!origin && !isWorkloadKeyVariable(name) && !isConnectKeyVariable(name)) {
 			throw new Error(`zerops: ${name} is not a variable a deploy writes`)
@@ -132,7 +143,10 @@ export function parseManagedEnvironment(value: Readonly<Record<string, string |
 	return { values: parseManagedValues(managed), familyVariables }
 }
 
-/** A service variable only the platform writes per workload or import: a stale one is removed with it. */
+/**
+ * A service variable only the platform writes per workload, import or the installation's mail transport: a stale one is
+ * removed when the deploy no longer hands it.
+ */
 export function isFrameworkFamilyVariable(name: string): boolean {
 	return FRAMEWORK_VARIABLE_PREFIXES.some((prefix) => name.startsWith(prefix))
 }

package/src/manifest.ts

@@ -410,23 +410,43 @@ const isDescriptorSetup = (value: JsonValue, setup: string): value is { readonly
 const zeropsProvisioningDatabaseUrl = (host: string): string =>
 	`postgresql://\${${host}_superUser}:\${${host}_superUserPassword}@\${${host}_hostname}:\${${host}_port}/\${${host}_dbName}?sslmode=disable`
 
+/** The PostgreSQL service a contract application uses: its own, or the namespace's shared one. */
+export interface ApplicationDatabaseService {
+	readonly hostname: string
+	/** The namespace's `postgres`, which every application of a `cheap` namespace shares and the namespace sizes. */
+	readonly shared: boolean
+}
+
 /**
  * The PostgreSQL service `FABRIKA_APP_DATABASE_URL` is generated for: the namespace's shared one, or the application's
  * one PostgreSQL service. Two candidates would make the generated migration pick one.
  */
-const applicationDatabaseUrl = (
+const applicationDatabase = (
 	services: FabrikaManifestImportDocument['services'],
 	namespaceResources: readonly ZeropsNamespaceResourceRequirement[] | undefined,
-): string | null => {
+): ApplicationDatabaseService | null => {
 	const own = services.filter((service) => service.type.startsWith('postgresql')).map((service) => service.hostname)
 	const shared = namespaceResources?.find((resource) => resource.resourceKey === 'service:postgres')
 	if (own.length + (shared === undefined ? 0 : 1) > 1) {
 		throw new Error('invalid fabrika manifest: a contract application has one PostgreSQL database; it declares more than one')
 	}
-	const host = shared?.hostname ?? own[0]
-	return host === undefined ? null : zeropsProvisioningDatabaseUrl(host)
+	if (shared !== undefined) return { hostname: shared.hostname, shared: true }
+	const [hostname] = own
+	return hostname === undefined ? null : { hostname, shared: false }
 }
 
+const applicationDatabaseUrl = (
+	services: FabrikaManifestImportDocument['services'],
+	namespaceResources: readonly ZeropsNamespaceResourceRequirement[] | undefined,
+): string | null => {
+	const database = applicationDatabase(services, namespaceResources)
+	return database === null ? null : zeropsProvisioningDatabaseUrl(database.hostname)
+}
+
+/** The PostgreSQL service of the application this manifest deploys, or null when it has none. */
+export const applicationDatabaseOf = (manifest: FabrikaManifest): ApplicationDatabaseService | null =>
+	applicationDatabase(manifest.target.importDocument.services, manifest.target.namespaceResources)
+
 /** The hostname the `FABRIKA_APP_STORAGE_*` references name: the application's one object-storage service. */
 const applicationStorageHostname = (services: FabrikaManifestImportDocument['services']): string | null => {
 	const own = services.filter((service) => OBJECT_STORAGE_TYPES.has(service.type)).map((service) => service.hostname)
@@ -444,6 +464,7 @@ export const lockedExecutionOf = (manifest: FabrikaManifest): ZeropsLockedExecut
 		appId: manifest.app.id,
 		contract,
 		databaseUrl: applicationDatabaseUrl(manifest.target.importDocument.services, manifest.target.namespaceResources),
+		databaseConnections: null,
 		storageHostname: applicationStorageHostname(manifest.target.importDocument.services),
 		runtimePackages: manifest.target.runtimePackages ?? [],
 		sourceMaps: null,
@@ -475,6 +496,7 @@ export function lockedExecutionFor(
 		appId: manifest.app.id,
 		contract,
 		databaseUrl: applicationDatabaseUrl(manifest.target.importDocument.services, manifest.target.namespaceResources),
+		databaseConnections: null,
 		storageHostname: applicationStorageHostname(manifest.target.importDocument.services),
 		runtimePackages: manifest.target.runtimePackages ?? [],
 		sourceMaps: artifactUpload === undefined ? null : sourceMapUpload(artifactUpload, access.contract),

package/src/plan.ts

@@ -6,6 +6,7 @@ export type ZeropsStepKind =
 	| 'verify-exposure'
 	| 'write-service-env'
 	| 'raise-start-memory'
+	| 'size-database'
 	| 'reserve-version'
 	| 'upload-source'
 	| 'trigger-build'
@@ -49,6 +50,11 @@ export const buildZeropsPlan = (manifest: FabrikaManifest, target: ZeropsRuntime
 		kind: 'raise-start-memory',
 		description: "Raise the deploy service's minimum RAM to what its start script needs",
 	})
+	steps.push({
+		id: 'size-database',
+		kind: 'size-database',
+		description: "Size each process's database connections to the database's limit, raising its minimum RAM where it is too low",
+	})
 	steps.push({ id: 'reserve-version', kind: 'reserve-version', description: 'Reserve a Zerops app version' })
 	steps.push({ id: 'upload-source', kind: 'upload-source', description: 'Upload the resolved repository snapshot' })
 	steps.push({ id: 'trigger-build', kind: 'trigger-build', description: 'Trigger the Zerops build+deploy pipeline' })

package/src/provider.ts

@@ -33,11 +33,28 @@ import {
 	type ZeropsAppVersion,
 	type ZeropsLogAccess,
 	type ZeropsProcess,
+	type ZeropsService,
 	type ZeropsServiceAutoscaling,
 } from './api'
 import { defaultZeropsCollaborators, type ZeropsCollaboratorFactory, type ZeropsCollaborators } from './collaborators'
 import { assertZeropsInvariants, renderYaml } from './compile'
-import { FABRIKA_CHECK_VERSION, PLATFORM_TYPESCRIPT_VERSION, renderLockedExecutionDescriptor, zeropsStartMinRam } from './execution'
+import {
+	MIN_PROCESS_CONNECTIONS,
+	ZEROPS_MAX_CONTAINERS,
+	ZEROPS_POSTGRES_MIN_RAM_GB,
+	type ZeropsDatabaseDemand,
+	zeropsDatabaseMinRam,
+	zeropsPostgresMaxConnections,
+	zeropsProcessConnections,
+} from './database-budget'
+import {
+	FABRIKA_CHECK_VERSION,
+	PLATFORM_TYPESCRIPT_VERSION,
+	renderLockedExecutionDescriptor,
+	zeropsJobProcesses,
+	type ZeropsLockedExecution,
+	zeropsStartMinRam,
+} from './execution'
 import {
 	createdServices,
 	type ExposureFinding,
@@ -61,6 +78,7 @@ import {
 	SERVICE_MANAGED_KEYS,
 } from './managed-env'
 import {
+	applicationDatabaseOf,
 	approvedSchemaOf,
 	type FabrikaImportDocument,
 	type FabrikaManifest,
@@ -288,6 +306,8 @@ interface Attempt {
 	triggered: boolean
 	/** What the build's source-map upload reported in its log, once a relayed line said so. */
 	sourceMaps?: OperationsSourceMapUploadState
+	/** The most connections each process of the application opens, as `size-database` sized them. */
+	databaseConnections?: number
 }
 
 /** Everything one step's executor needs, bundled so the per-kind handlers stay small. */
@@ -576,7 +596,7 @@ const writeServiceEnv = async (env: StepEnv): Promise<void> => {
 		log(`  [dry-run] would write service variables on ${serviceId}: ${written.join(', ') || '(none)'}`)
 		log(`  [dry-run] would remove service variables on ${serviceId} if present: ${removed.join(', ') || '(none)'}`)
 		if (Object.keys(familyVariables).length > 0) {
-			log(`  [dry-run] would remove every other job, webhook and connector variable on ${serviceId}`)
+			log(`  [dry-run] would remove every other job, webhook, connector and mail variable on ${serviceId}`)
 		}
 		return
 	}
@@ -667,27 +687,42 @@ const raiseStartMemory = async (env: StepEnv): Promise<void> => {
 		log(`  [dry-run] would raise the minimum RAM of ${hostname} to ${minRam} GB where it is lower`)
 		return
 	}
-	const serviceId = run.target.serviceId
 	assertRunning(signal)
-	const service = await zerops.api.getService({ serviceId, signal })
+	const service = await zerops.api.getService({ serviceId: run.target.serviceId, signal })
+	const before = service.currentAutoscaling?.vertical.minResource.memoryGBytes ?? null
+	if (before !== null && before >= minRam) {
+		log(`  minimum RAM of ${hostname}: ${before} GB, unchanged (its start needs ${minRam} GB)`)
+		return
+	}
+	const after = await raiseMinRam(env, service, hostname, minRam, 'its start needs')
+	log(`  minimum RAM of ${hostname}: ${before ?? 'the platform default'} → ${after} GB`)
+}
+
+/** What raising a minimum RAM calls; the deploy's collaborators, and the live platform-facts probe of the same path. */
+export interface MinRamRaise {
+	zerops: Pick<ZeropsCollaborators, 'api' | 'sleep'>
+	signal: AbortSignal
+}
+
+/**
+ * Sets `service`'s minimum RAM to `minRam` and answers the minimum it reads back. It sends the custom autoscaling it
+ * read WHOLE with only that field changed: the platform resets every field a request leaves out.
+ */
+export const raiseMinRam = async (env: MinRamRaise, service: ZeropsService, hostname: string, minRam: number, need: string): Promise<number> => {
+	const { zerops, signal } = env
 	const custom = service.customAutoscaling
 	const current = service.currentAutoscaling
 	if (custom === undefined || current === undefined) {
 		throw new Error(`zerops: ${hostname} did not report its autoscaling whole, so its minimum RAM cannot be raised to ${minRam} GB`)
 	}
-	const before = current.vertical.minResource.memoryGBytes
-	if (before !== null && before >= minRam) {
-		log(`  minimum RAM of ${hostname}: ${before} GB, unchanged (its start needs ${minRam} GB)`)
-		return
-	}
 	const maxRam = current.vertical.maxResource.memoryGBytes
 	if (maxRam !== null && maxRam < minRam) {
-		throw new Error(`zerops: ${hostname} may use at most ${maxRam} GB of RAM and its start needs ${minRam} GB; raise verticalAutoscaling.maxRam`)
+		throw new Error(`zerops: ${hostname} may use at most ${maxRam} GB of RAM and ${need} ${minRam} GB; raise verticalAutoscaling.maxRam`)
 	}
 	assertRunning(signal)
 	let process: ZeropsProcess | null
 	try {
-		process = await zerops.api.configureCustomAutoscaling({ serviceId, autoscaling: withMinRam(custom, minRam), signal })
+		process = await zerops.api.configureCustomAutoscaling({ serviceId: service.id, autoscaling: withMinRam(custom, minRam), signal })
 	} catch (error) {
 		if (error instanceof ZeropsApiError && error.status >= 400 && error.status < 500 && error.status !== 408) {
 			throw new Error(`zerops: raising the minimum RAM of ${hostname} to ${minRam} GB was refused (${error.code === '' ? error.status : error.code})`)
@@ -697,11 +732,69 @@ const raiseStartMemory = async (env: StepEnv): Promise<void> => {
 	if (process !== null) {
 		await waitForProcess({ api: zerops.api, processId: process.id, sleep: zerops.sleep, signal, label: `the autoscaling change of ${hostname}` })
 	}
-	const after = (await zerops.api.getService({ serviceId, signal })).currentAutoscaling?.vertical.minResource.memoryGBytes ?? null
+	const after = (await zerops.api.getService({ serviceId: service.id, signal })).currentAutoscaling?.vertical.minResource.memoryGBytes ?? null
 	if (after === null || after < minRam) {
 		throw new Error(`zerops: ${hostname} reads back a minimum RAM of ${after ?? 'nothing'} GB after it was raised to ${minRam} GB`)
 	}
-	log(`  minimum RAM of ${hostname}: ${before ?? 'the platform default'} → ${after} GB`)
+	return after
+}
+
+/**
+ * Sizes the connections each process of the application opens (`zeropsProcessConnections`) from its database's
+ * `max_connections`, which follows the database's minimum RAM, and the deploy service's maximum container count. When
+ * that leaves a process fewer than `MIN_PROCESS_CONNECTIONS`, it raises the minimum RAM of the application's own
+ * database to the smallest step that does not (`zeropsDatabaseMinRam`). A `cheap` namespace's shared database is the
+ * namespace's to size, so it is never raised: each process then gets the minimum, and the run log says it may not fit.
+ */
+const sizeDatabase = async (env: StepEnv): Promise<void> => {
+	const { run, zerops, log, signal, dryRun, attempt } = env
+	const locked = lockedExecutionFor(run.artifact, run, dryRun)
+	const database = locked === null ? null : applicationDatabaseOf(run.artifact)
+	if (locked === null || database === null) {
+		log('  the application has no database')
+		return
+	}
+	const deployHostname = run.artifact.target.deployService
+	if (dryRun) {
+		log(`  [dry-run] would size each process of ${deployHostname} to the connection limit of ${database.hostname}`)
+		return
+	}
+	assertRunning(signal)
+	const deploy = await zerops.api.getService({ serviceId: run.target.serviceId, signal })
+	const demand: ZeropsDatabaseDemand = {
+		maxContainers: deploy.currentAutoscaling?.horizontal.maxContainerCount ?? ZEROPS_MAX_CONTAINERS,
+		jobs: zeropsJobProcesses(locked.contract),
+	}
+	const service = await zerops.api.findService({ projectId: run.target.projectId, hostname: database.hostname, signal })
+	if (service === null) throw new Error(`zerops: the database ${database.hostname} does not exist, so its connections cannot be sized`)
+	const profile = service.autoscalingProfileId
+	// A minimum the service does not report is taken as the smallest step: its limit is then never overstated.
+	let ram = service.currentAutoscaling?.vertical.minResource.memoryGBytes ?? ZEROPS_POSTGRES_MIN_RAM_GB
+	const holders = `${demand.maxContainers} container(s) of ${deployHostname}, twice while a deploy replaces them, and ${demand.jobs} job process(es)`
+	let connections = zeropsProcessConnections(zeropsPostgresMaxConnections(ram, profile), demand)
+	if (connections === null && database.shared) {
+		connections = MIN_PROCESS_CONNECTIONS
+		log(`  [warn] ${database.hostname} at ${ram} GB has too few connections for ${holders}; the namespace shares it, so raise its profile`)
+	}
+	if (connections === null) {
+		const minRam = zeropsDatabaseMinRam(demand, profile)
+		if (minRam === null) throw new Error(`zerops: no RAM of ${database.hostname} has enough connections for ${holders}`)
+		const before = ram
+		ram = await raiseMinRam(env, service, database.hostname, minRam, `${holders} need`)
+		log(`  minimum RAM of ${database.hostname}: ${before} → ${ram} GB, for its connection limit`)
+		connections = zeropsProcessConnections(zeropsPostgresMaxConnections(ram, profile), demand) ?? MIN_PROCESS_CONNECTIONS
+	}
+	attempt.databaseConnections = connections
+	const limit = zeropsPostgresMaxConnections(ram, profile)
+	log(`  ${database.hostname}: ${limit} connections at ${ram} GB; each process opens at most ${connections}, for ${holders}`)
+}
+
+/** The locked execution with the connections `size-database` sized; an application with a database is never sent without. */
+const sizedExecution = (locked: ZeropsLockedExecution, attempt: Attempt): ZeropsLockedExecution => {
+	if (locked.databaseUrl === null) return locked
+	const connections = attempt.databaseConnections
+	if (connections === undefined) throw new Error('zerops: trigger-build has no database connection size (size-database did not run)')
+	return { ...locked, databaseConnections: connections }
 }
 
 /** Run one step's effect. Resolves on success, throws on failure (caught + recorded by `runSteps`). */
@@ -763,6 +856,11 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 			return
 		}
 
+		case 'size-database': {
+			await sizeDatabase(env)
+			return
+		}
+
 		case 'reserve-version': {
 			if (dryRun) {
 				log(`  [dry-run] would reserve an app version on service ${target.serviceId}`)
@@ -830,7 +928,7 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 			const release = env.managedValues.FABRIKA_RELEASE
 			const descriptor = locked === null
 				? overlayRelease(contents, artifact.target.zeropsSetup, release)
-				: renderLockedExecutionDescriptor(contents, artifact.target.zeropsSetup, release, locked)
+				: renderLockedExecutionDescriptor(contents, artifact.target.zeropsSetup, release, sizedExecution(locked, attempt))
 			if (locked !== null) {
 				log(`  generated run section; build checks @fabrika/check@${FABRIKA_CHECK_VERSION}, typescript@${PLATFORM_TYPESCRIPT_VERSION}`)
 				if (locked.sourceMaps !== null) log(`  the build uploads the source maps of ${locked.sourceMaps.assetRoots.length} asset root(s)`)