@fabrika/provider-zerops 0.4.6 → 0.4.8

package/package.json

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

package/src/api/client.ts

@@ -354,6 +354,16 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 			return readResponse('configure autoscaling', processNilSchema, payload).process ?? null
 		},
 
+		configureCustomAutoscaling: async ({ serviceId, autoscaling, signal }) => {
+			const payload = await request('configure custom autoscaling', 'PUT', `/service-stack/${serviceId}/autoscaling`, {
+				body: {
+					customAutoscaling: { verticalAutoscaling: autoscaling.vertical, horizontalAutoscaling: autoscaling.horizontal },
+				},
+				signal,
+			})
+			return readResponse('configure custom autoscaling', processNilSchema, payload).process ?? null
+		},
+
 		getService: async ({ serviceId, signal }) =>
 			readResponse('get service', serviceSchema, await request('get service', 'GET', `/service-stack/${serviceId}`, { signal })),
 

package/src/api/readers.ts

@@ -12,6 +12,7 @@ import type {
 	ZeropsProjectStatus,
 	ZeropsRoleCode,
 	ZeropsService,
+	ZeropsServiceAutoscaling,
 	ZeropsServiceEnv,
 	ZeropsServiceStatus,
 	ZeropsUserInfo,
@@ -121,6 +122,41 @@ export const processSchema = z.object({
 	appVersion: nestedIdSchema,
 }).transform(({ appVersion, ...process }): ZeropsProcess => ({ ...process, appVersionId: appVersion?.id }))
 
+const nullableNumber = z.number().nullish().transform((value) => value ?? null)
+
+const scalingResourceSchema = z.object({ cpuCoreCount: nullableNumber, memoryGBytes: nullableNumber, diskGBytes: nullableNumber }).nullish()
+	.transform((resource) => resource ?? { cpuCoreCount: null, memoryGBytes: null, diskGBytes: null })
+
+const scalingFreeResourceSchema = z.object({
+	cpuCoreCount: nullableNumber,
+	cpuCorePercent: nullableNumber,
+	memoryGBytes: nullableNumber,
+	memoryPercent: nullableNumber,
+}).nullish().transform((resource) => resource ?? { cpuCoreCount: null, cpuCorePercent: null, memoryGBytes: null, memoryPercent: null })
+
+/**
+ * Strict where `optional` is lenient: the custom autoscaling is sent back whole, so a field read as absent would be
+ * reset. One that does not parse makes the whole object absent, and nothing is sent.
+ */
+const verticalAutoscalingSchema = z.object({
+	cpuMode: z.enum(['DEDICATED', 'SHARED']).nullish().transform((value) => value ?? null),
+	minResource: scalingResourceSchema,
+	maxResource: scalingResourceSchema,
+	minFreeResource: scalingFreeResourceSchema,
+	startCpuCoreCount: nullableNumber,
+	swapEnabled: z.boolean().nullish().transform((value) => value ?? null),
+})
+
+const serviceAutoscalingSchema = z.object({
+	// A service with no custom vertical autoscaling reads `null` here (measured 2026-10-15): every field inherits.
+	verticalAutoscaling: verticalAutoscalingSchema.nullish().transform((vertical) => vertical ?? verticalAutoscalingSchema.parse({})),
+	horizontalAutoscaling: z.object({ minContainerCount: nullableNumber, maxContainerCount: nullableNumber }).nullish()
+		.transform((horizontal) => horizontal ?? { minContainerCount: null, maxContainerCount: null }),
+}).transform(({ verticalAutoscaling, horizontalAutoscaling }): ZeropsServiceAutoscaling => ({
+	vertical: verticalAutoscaling,
+	horizontal: horizontalAutoscaling,
+}))
+
 export const serviceSchema = z.object({
 	id: idSchema,
 	name: z.string(),
@@ -130,6 +166,8 @@ export const serviceSchema = z.object({
 	activeAppVersion: nestedIdSchema,
 	subdomainAccess: optional(z.boolean()),
 	autoscalingProfileId: optional(z.string()),
+	customAutoscaling: optional(serviceAutoscalingSchema),
+	currentAutoscaling: optional(serviceAutoscalingSchema),
 }).transform(({ activeAppVersion, ...service }): ZeropsService => ({ ...service, activeAppVersionId: activeAppVersion?.id }))
 
 export const projectSchema = z.object({

package/src/api/types.ts

@@ -162,6 +162,40 @@ export type ZeropsServiceStatus =
 	| 'SCALING'
 	| 'REPAIR_FAILED'
 
+/** One bound of vertical autoscaling. `null` inherits the service type's value. */
+export interface ZeropsScalingResource {
+	cpuCoreCount: number | null
+	memoryGBytes: number | null
+	diskGBytes: number | null
+}
+
+/** The free capacity below which vertical autoscaling scales up. `null` inherits the service type's value. */
+export interface ZeropsScalingFreeResource {
+	cpuCoreCount: number | null
+	cpuCorePercent: number | null
+	memoryGBytes: number | null
+	memoryPercent: number | null
+}
+
+/**
+ * A service's autoscaling, as `ResponseServiceStack.customAutoscaling` (what was set) and `.currentAutoscaling` (what
+ * applies) carry it, every field nullable. VERIFIED live 2026-10-15 (`docs/reference/zerops-platform.md`).
+ */
+export interface ZeropsServiceAutoscaling {
+	vertical: {
+		cpuMode: 'DEDICATED' | 'SHARED' | null
+		minResource: ZeropsScalingResource
+		maxResource: ZeropsScalingResource
+		minFreeResource: ZeropsScalingFreeResource
+		startCpuCoreCount: number | null
+		swapEnabled: boolean | null
+	}
+	horizontal: {
+		minContainerCount: number | null
+		maxContainerCount: number | null
+	}
+}
+
 /** One service. VERIFIED: `ResponseServiceStack` (narrowed to the fields fabrika reads). */
 export interface ZeropsService {
 	id: string
@@ -175,6 +209,10 @@ export interface ZeropsService {
 	subdomainAccess?: boolean
 	/** Provider profile identifier, e.g. `oltp-production`. VERIFIED: `ResponseServiceStack.autoscalingProfileId`. */
 	autoscalingProfileId?: string
+	/** The autoscaling set on the service; absent when the platform sent none or one this client cannot read whole. */
+	customAutoscaling?: ZeropsServiceAutoscaling
+	/** The autoscaling that applies, the service type's values included; absent like `customAutoscaling`. */
+	currentAutoscaling?: ZeropsServiceAutoscaling
 }
 
 /** One project. VERIFIED: `ResponseProject` (narrowed). */
@@ -447,6 +485,15 @@ export interface ZeropsApi {
 	 */
 	configureAutoscaling(input: { serviceId: string; autoscalingProfileId: string; signal: AbortSignal }): Promise<ZeropsProcess | null>
 
+	/**
+	 * Replace a service's custom autoscaling: the same `PUT /service-stack/{id}/autoscaling`, body
+	 * `{ customAutoscaling: { verticalAutoscaling, horizontalAutoscaling } }`. VERIFIED live 2026-10-15: it answers
+	 * `{ process: null }` and `currentAutoscaling` reads the change at once. The platform replaces the whole object: a
+	 * field left out, or under a key it does not know, is reset to the service type's value and the call still answers
+	 * 200, so the caller sends what `getService().customAutoscaling` read, changed where it means to.
+	 */
+	configureCustomAutoscaling(input: { serviceId: string; autoscaling: ZeropsServiceAutoscaling; signal: AbortSignal }): Promise<ZeropsProcess | null>
+
 	// ── service-stack / project: reading state ────────────────────────────────────
 
 	/** One service by id. VERIFIED: `GET /service-stack/{id}`. */

package/src/api.ts

@@ -30,6 +30,7 @@ export {
 	type ZeropsProjectStatus,
 	type ZeropsRoleCode,
 	type ZeropsService,
+	type ZeropsServiceAutoscaling,
 	type ZeropsServiceEnv,
 	type ZeropsServiceEnvWrite,
 	type ZeropsServiceStatus,

package/src/control.ts

@@ -434,7 +434,9 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 			if (!checkpoint.triggered) {
 				// A throw keeps the run running; the next maintenance pass retries the deletion.
 				await deleteVersion(api, checkpoint.appVersionId, signal)
-				await log(`deleted app-version ${checkpoint.appVersionId}; its build was never requested`)
+				await log(
+					`deploy interrupted: Control stopped before it requested the build; deleted app-version ${checkpoint.appVersionId}; run the deploy again`,
+				)
 				return { state: 'failed' }
 			}
 			let version: ZeropsAppVersion | null

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

@@ -55,6 +55,20 @@ const FILE_SWEEP_SCHEDULE = '41 * * * *'
  */
 export const ZEROPS_SCAN_MIN_RAM_GB = 2
 
+/**
+ * The RAM in GB a container of an application with a database starts with. Its start script runs `fabrika db
+ * test-isolation`, whose CLI and `bun test` child together peak at 161 MiB of anonymous memory for the Notes example
+ * and 225 MiB for the CRM example (measured locally, 2026-10-15), beside Bun's own mapped binary. Zerops' 0.125 GB
+ * floor kills that within a second, faster than vertical autoscaling reacts.
+ */
+export const ZEROPS_START_MIN_RAM_GB = 0.5
+
+/** The minimum RAM in GB the deploy service's containers need to start, or null when Zerops' floor suffices. */
+export function zeropsStartMinRam(execution: ZeropsLockedExecution): number | null {
+	if (execution.contract.scan === true) return ZEROPS_SCAN_MIN_RAM_GB
+	return execution.databaseUrl === null ? null : ZEROPS_START_MIN_RAM_GB
+}
+
 /** What a scanning application adds: ClamAV in the image with its first signatures, refreshed at start and daily. */
 const SCANNER_PACKAGE = 'clamav'
 const FRESHCLAM = 'sudo freshclam --stdout --quiet'
@@ -79,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[]
@@ -113,7 +132,7 @@ export function zeropsContractRun(artifact: ContractArtifact): ZeropsContractRun
 /**
  * A scanning application's deploy service must start its containers with `ZEROPS_SCAN_MIN_RAM_GB`: below it the
  * scanner is killed for memory, and every upload stays quarantined. Zerops ignores a changed `verticalAutoscaling` of
- * an existing service on a re-import, so an existing service is raised through Zerops itself.
+ * an existing service on a re-import, so the deploy's `raise-start-memory` step raises an existing service.
  */
 export function assertScanMemory(services: readonly { readonly [key: string]: JsonValue }[], deployService: string, run: ZeropsContractRun): void {
 	if (run.scan !== true) return
@@ -323,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,
@@ -338,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/index.ts

@@ -29,6 +29,7 @@ export type {
 	ZeropsProjectStatus,
 	ZeropsRoleCode,
 	ZeropsService,
+	ZeropsServiceAutoscaling,
 	ZeropsServiceEnv,
 	ZeropsServiceEnvWrite,
 	ZeropsServiceStatus,
@@ -108,6 +109,7 @@ export { ZEROPS_PROXY_MANIFEST_PATH, type ZeropsProxyManifestCarrier, zeropsProx
 export type * from './schema.generated'
 export { isZeropsUploadDestination, normalizeZeropsSourceRepository } from './source'
 export type { ZeropsSourceRepository } from './source'
+export { ZeropsSourceRateLimitedError } from './source/port'
 export type {
 	ZeropsSourceArchive,
 	ZeropsSourcePort,

package/src/installation/admin-options.ts

@@ -19,7 +19,7 @@ export interface PlatformAdminInput {
 	readonly iamHost: string
 	/** The scheme a browser speaks to this installation. With `iamHost` it composes IAM's public origin. */
 	readonly scheme: 'http' | 'https'
-	/** The `px_` provisioning key `platform install` printed. Environment only. */
+	/** The `px_` provisioning key `platform install` wrote to its secrets file. Environment only. */
 	readonly provisioningKey: string
 	/** Replace an outstanding enrollment instead of reporting it. */
 	readonly reissue: boolean
@@ -78,7 +78,7 @@ const provisioningKey = (env: Record<string, string | undefined>): string => {
 	const value = readEnv(env, 'FABRIKA_IAM_PROVISIONING_KEY')
 	if (value === undefined) {
 		throw new Error(
-			'FABRIKA_IAM_PROVISIONING_KEY is required. It has no flag: the key platform install printed comes from the environment only.',
+			'FABRIKA_IAM_PROVISIONING_KEY is required. It has no flag: load it from the secrets file platform install wrote, into the environment only.',
 		)
 	}
 	return value

package/src/installation/guide.md

@@ -152,8 +152,10 @@ URL stops working.
 
 The sidecar is a GitHub repository the operator owns. Its workflow runs `platform deploy` at the pinned tag.
 
-Steps 4 and 5 do not depend on this step: the installation from step 1 already runs. The sidecar is what
-upgrades it later (step 6). Run this step before or after step 5. Only `platform upgrade` needs it.
+The installation from step 1 already runs, and the sidecar is what upgrades it later (step 6). But `init`
+triggers the workflow, and its run redeploys every platform service, control included. A deploy that is in
+flight when control restarts fails, and its log names no reason. So run this step BEFORE step 5, and wait for
+its run to end before the first `control deploy` (see the check below). Step 4 can run meanwhile.
 
 `init` takes the integration token step 1 minted, never the personal one. The secrets file holds it as
 `FABRIKA_ZEROPS_ACCESS_TOKEN`, beside the provisioning key. Run `init` from a directory that is NOT inside
@@ -169,9 +171,16 @@ one too. Otherwise pass `--checkout=<dir>` outside one:
 - Without `--repo` the repository is `contember/fabrika-zerops-<installation>`. Pass `--repo` for any
   other organization.
 - Keep the local checkout path. `platform upgrade` needs it later (`--sidecar=<dir>`).
+- `--tag` is written only into a NEW sidecar. An existing one keeps its `fabrika.ref`. When that pins another
+  tag, `init` writes the GitHub Environment and then refuses to trigger the run, which would deploy the other
+  tag. Its message names the fix: `fabrika platform upgrade --provider=zerops --to=<tag> --sidecar=<dir>`.
 
-**Check.** The `platform` workflow run in the sidecar repository ends green:
-`gh run list --repo <owner>/<name>`.
+**Check.** The `platform` workflow run in the sidecar repository ends green. Wait for it before step 5:
+
+```bash
+gh run list --repo <owner>/<name> --workflow=platform.yml --limit=1   # its id, status and conclusion
+gh run watch <run id> --repo <owner>/<name> --exit-status              # returns when the run ends; non-zero if it failed
+```
 
 ## Step 4. Mint a machine key for `fabrika control`
 
@@ -210,17 +219,22 @@ places it on the namespace's shared PostgreSQL (`cheap` preset). Use the config
 **Repository access decides how you register** (step 5.2). Check it first:
 `curl -s -o /dev/null -w '%{http_code}\n' https://api.github.com/repos/<owner>/<name>`.
 
-- `200`: the repository is public. Register it with `--installation-id=none`. Control reads it without a token.
+- `200`: the repository is public. Register it with `--installation-id=none`. Control reads it without a token,
+  or with the organization's GitHub App once that App is connected and installed on the repository.
 - `404`: GitHub hides it from an anonymous caller, so it is private (or the name is wrong). `register` refuses
   it with `--installation-id=none`. Ask the human to connect the GitHub App in the console first (Settings →
   Source, a browser flow), then register without `--installation-id`.
 
 **Use the installation's release in the application.** The application's `@fabrika/*` packages, the CLI
-among them, must be the version of the tag you installed: for `v0.4.3`, `^0.4.3`. Another version can build
-a manifest this installation's control refuses or reads differently. From the fabrika clone of step 0, run
-`bun scripts/release.ts example-pin <application checkout> --tag=<tag>`. It rewrites every `@fabrika/*` range
-and commits nothing. Commit and push the change in the application repository, then run `bun install` there.
-Check with `bun pm ls | grep @fabrika/cli`.
+among them, must be exactly the version of the tag you installed: for `v0.4.3`, `0.4.3`, not a range such as
+`^0.4.3`, which resolves a later patch. Another version can build a manifest this installation's control
+refuses or reads differently. The example's `main` pins the latest release; for an older installation, from
+the fabrika clone of step 0, run `bun scripts/release.ts example-pin <application checkout> --tag=<tag>`. It
+pins every `@fabrika/*` package exactly and commits nothing. Run `bun install` in the application repository,
+then commit and push `package.json` and `bun.lock`. Check that every `@fabrika/*` package, the transitive ones
+included, is the tag's version: `bun pm ls --all | grep @fabrika/`. Releases up to v0.4.6 name their own
+`@fabrika/*` dependencies by a range, so a transitive one can still resolve a later patch of that line. Then
+install the newest patch instead (step 6 upgrades an installation).
 
 1. **Create a namespace** with the preset and core package the human chose (see Decisions). Without a
    custom domain bound to its proxy, pass `--public-access=zerops-subdomain`; the default is
@@ -232,6 +246,9 @@ Check with `bun pm ls | grep @fabrika/cli`.
    fabrika control namespaces get    --namespace=<id>
    ```
 
+   The namespace's Zerops project is `fabrika-<env>-<namespace id>`, beside the installation's
+   `fabrika-<env>`. Pass `--project=<name>` for another name; it cannot change after `create`.
+
    `create` returns while the state is `pending`. Provisioning takes several minutes. Poll `get` every
    30 seconds until it is `ready`.
 
@@ -263,8 +280,12 @@ Check with `bun pm ls | grep @fabrika/cli`.
      once and refuses one that is not publicly readable, so the failure shows here and not at deploy. A
      private repository needs the GitHub App connected in the console first (Settings → Source, a browser
      flow for the human); then omit the flag.
+   - The public origin is where IAM returns a person after sign-in; without one, sign-in to the application
+     fails with "… is not a registered return origin for this app". For a host the namespace lists, `register`
+     sets `https://<free host>` itself and prints `public origin https://<host>` on stderr. For a custom domain
+     the namespace cannot list, add `--public-origin=https://<domain>`.
    - `register` CREATES and refuses a second registration. A changed manifest goes through
-     `control apps environments put` with the same placement flags.
+     `control apps environments put` with the same placement flags. `put` derives no public origin.
 
 3. **Deploy and follow it.**
 
@@ -275,7 +296,13 @@ Check with `bun pm ls | grep @fabrika/cli`.
    ```
 
    A failed run's log ends with `deploy failed: <reason>`. For example, `source resolve failed
-   (ref_not_found)` means control could not read the repository or the ref.
+   (ref_not_found)` means control could not read the repository or the ref. `GitHub rate limit for
+   anonymous reads reached; resets at <time>` means GitHub refused control's tokenless reads: every tenant
+   behind the cloud's egress address shares that limit. Deploy again after the reset, or connect the GitHub
+   App in the console so reads of that organization's repositories carry a token. A namespace that hits the
+   limit stays `provisioning` and retries on its own. A run that ends with
+   `deploy interrupted: …; run the deploy again` lost Control mid-run, typically to step 3's workflow
+   redeploying it: deploy again once Control is back.
 
    The deploy fails when the repository at the deployed commit does not match the registered manifest.
    Commit and push, rebuild the manifest, `apps environments put` it, and deploy again.
@@ -283,6 +310,13 @@ Check with `bun pm ls | grep @fabrika/cli`.
    On an environment named `prod`, a change that widens access waits for a person to approve it in the
    console before it deploys.
 
+4. **Give the administrator a role in the application.** The step 2 grant administers the installation; it
+   holds none of the application's actions, so the application answers `forbidden` to the administrator.
+   No `fabrika` command grants an application role. The human does it in the console: Access → Users → the
+   administrator → Add grant. Pick the application `<id>@<env>` (the example: `notes@<env>`), Named role / policy,
+   a role the application declares (the example's `editor` reads, writes and deletes notes), the global scope,
+   and Add grant. It takes effect at the next sign-in.
+
 **Check.** The run ends `succeeded`. `https://<host>/healthz` answers 200, and `/` redirects to the IAM
 sign-in. A green run proves only that Zerops accepted the build: have the human sign in and use the app.
 

package/src/installation/index.ts

@@ -172,13 +172,16 @@ It writes TWO secrets into that Environment and GENERATES NEITHER — both alrea
 installation, so a value invented here would not be one it accepts. Both are environment only:
 
 	FABRIKA_ZEROPS_ACCESS_TOKEN       required   the INTEGRATION token install minted (the \`control\` service's env)
-	FABRIKA_IAM_PROVISIONING_KEY      required   the px_ key install printed
+	FABRIKA_IAM_PROVISIONING_KEY      required   the px_ key install wrote to its --secrets-file
 	FABRIKA_ZEROPS_API_URL            optional   region API base, when not the default
 
 Each is sent to GitHub over \`gh\` stdin, and never printed and never written to disk.
 
 The generated pipeline pins a published TAG of contember/fabrika-platform and refuses a branch, at
 init and again in the workflow. It uploads that checkout's exact committed archive to every installation service.
+\`--tag\` is written only to a new sidecar: an existing \`fabrika.ref\` is the operator's and stays. When it pins
+another tag, init writes the Environment and then refuses to trigger the run, which would deploy that other tag;
+\`platform upgrade --to=<tag>\` moves the pin and starts the run.
 
 ── platform deploy ───────────────────────────────────────────────────────────────────────────────
 
@@ -275,7 +278,7 @@ Options (a flag beats the environment variable beside it):
   --scheme=<http|https>             FABRIKA_PLATFORM_SCHEME         default https
   ${REISSUE_FLAG}                                                         replace an outstanding enrollment
 
-  FABRIKA_IAM_PROVISIONING_KEY      required   the px_ admin key \`install\` printed, environment only
+  FABRIKA_IAM_PROVISIONING_KEY      required   the px_ admin key \`install\` wrote to its --secrets-file, environment only
 
 ── platform upgrade ──────────────────────────────────────────────────────────────────────────────
 

package/src/installation/init.ts

@@ -258,6 +258,12 @@ const readPlatform = async (input: InitInput, { log, prompts, effects }: InitCol
 	})
 }
 
+/** The local checkout and the tag its `fabrika.ref` pins, which an existing sidecar keeps whatever `--tag` says. */
+interface ScaffoldedSidecar {
+	readonly dir: string
+	readonly pinned: string
+}
+
 /**
  * Create or refresh the sidecar repository — the first step that leaves this disk.
  *
@@ -265,7 +271,7 @@ const readPlatform = async (input: InitInput, { log, prompts, effects }: InitCol
  * outward step: an Environment cannot be written to a repository that does not exist, and a workflow
  * cannot be triggered without one.
  */
-const scaffold = async (input: InitInput, { log, prompts, effects }: InitCollaborators): Promise<string | undefined> => {
+const scaffold = async (input: InitInput, { log, prompts, effects }: InitCollaborators): Promise<ScaffoldedSidecar | undefined> => {
 	log.step('Scaffold the sidecar repository')
 	const exists = await effects.repositoryExists(input.repo)
 	const question = exists
@@ -293,7 +299,22 @@ const scaffold = async (input: InitInput, { log, prompts, effects }: InitCollabo
 	if (pinned !== input.fabrikaRef) {
 		log.warn(`the existing pin ${pinned} was kept; ${input.fabrikaRef} was not written, because fabrika.ref is operator-owned`)
 	}
-	return result.dir
+	return { dir: result.dir, pinned }
+}
+
+/**
+ * Refuse to trigger a run that would deploy a tag other than `--tag`: the run deploys the kept pin, so a sidecar reused
+ * for a new installation would roll an older release over it. The Environment is already written, so the pin moves by
+ * `upgrade`, whose push triggers the run with it.
+ */
+const assertPinnedAsRequested = (input: InitInput, sidecar: ScaffoldedSidecar): void => {
+	if (sidecar.pinned === input.fabrikaRef) return
+	throw new Error(
+		`the platform workflow was NOT triggered: ${input.repo} pins ${sidecar.pinned}, not ${input.fabrikaRef}, and a run deploys the pin. `
+			+ `The ${input.installation} Environment is written. To deploy ${input.fabrikaRef}, move the pin: `
+			+ `fabrika platform upgrade --provider=zerops --to=${input.fabrikaRef} --sidecar=${sidecar.dir}. `
+			+ `To deploy ${sidecar.pinned}, run init again with --tag=${sidecar.pinned}`,
+	)
 }
 
 /** Run the whole thing for `<installation>`. */
@@ -320,8 +341,8 @@ export const runInit = async (input: InitInput, collaborators: InitCollaborators
 			: [url(settingsUrl)],
 	)
 
-	const dir = await scaffold(input, collaborators)
-	if (dir === undefined) {
+	const sidecar = await scaffold(input, collaborators)
+	if (sidecar === undefined) {
 		return
 	}
 
@@ -338,6 +359,7 @@ export const runInit = async (input: InitInput, collaborators: InitCollaborators
 	log.ok(`Environment ${input.installation} written: ${Object.keys(config.secrets).join(', ')} and ${Object.keys(config.vars).join(', ')}.`)
 
 	log.step('Trigger the deploy')
+	assertPinnedAsRequested(input, sidecar)
 	log.info("The pipeline runs the whole ordered sequence in the operator's CI; this machine deploys nothing.")
 	if (!(await prompts.confirm(`Run the platform workflow on ${input.repo} now?`, true))) {
 		log.action('OPERATOR ACTION — run it when ready', [
@@ -351,7 +373,7 @@ export const runInit = async (input: InitInput, collaborators: InitCollaborators
 	}
 
 	log.step('Done')
-	log.ok(`Sidecar repository: ${input.repo} (local checkout: ${dir})`)
+	log.ok(`Sidecar repository: ${input.repo} (local checkout: ${sidecar.dir})`)
 	log.info('Roll this installation forward by bumping fabrika.ref to a newer published tag and pushing.')
 	log.info("Who may administer the installation is IAM's to say: this repository holds no admission list to close later.")
 	// The origin comes off the live control service, never from what was typed here: an operator who

package/src/installation/install.ts

@@ -131,7 +131,7 @@ const installPreparedPlatform = async (
 	log.ok(
 		'IAM signing keys (1 × ES256), the IAM RPC key, the proxy key, the provisioning key, the Operations sync key and the vault key',
 	)
-	log.info('None of them is written to disk. Only the provisioning key is printed, once, at the end.')
+	log.info(`None of them is printed: every one goes to ${input.secretsFile} (mode 0600) before the first is placed.`)
 
 	log.step("Mint the control plane's Zerops token")
 	log.info('An INTEGRATION token, client role NO_ACCESS with ADMIN on this one project — never the personal token you authenticated with.')

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/namespace/errors.ts

@@ -1,5 +1,6 @@
 import { ProviderNamespaceError } from '@fabrika/provider-contract'
 import { ZeropsApiError, ZeropsServiceEnvValueTooLargeError } from '../api'
+import { ZeropsSourceRateLimitedError } from '../source/port'
 
 /**
  * Lifecycle codes this provider defines where the platform has none of its own. They are an
@@ -16,6 +17,8 @@ export const ZEROPS_PROXY_DEPLOY_FAILED = 'proxyDeployFailed'
 
 export const ZEROPS_SUBDOMAIN_NOT_PUBLISHED = 'subdomainNotPublished'
 
+export const ZEROPS_SOURCE_RATE_LIMITED = 'githubRateLimited'
+
 export const namespaceError = (code: string, message: string, retryable: boolean, detail?: string): ProviderNamespaceError =>
 	new ProviderNamespaceError(message, code, retryable, detail)
 
@@ -43,6 +46,8 @@ export const asNamespaceError = (cause: unknown, mode: 'provision' | 'reconcile'
 	if (cause instanceof ProviderNamespaceError) return cause
 	// The same value is refused again on every retry; only a smaller manifest or a new carrier fixes it.
 	if (cause instanceof ZeropsServiceEnvValueTooLargeError) return namespaceError(cause.code, cause.message, false)
+	// The limit resets on its own: the namespace stays `provisioning` and the cron's reconcile retries it.
+	if (cause instanceof ZeropsSourceRateLimitedError) return namespaceError(ZEROPS_SOURCE_RATE_LIMITED, cause.message, true)
 	if (cause instanceof ZeropsApiError) {
 		const { summary, detail } = splitApiMessage(cause.message, cause.code)
 		return namespaceError(

package/src/namespace/operator.ts

@@ -103,6 +103,13 @@ const namespacePresentation = (
 	}
 }
 
+/**
+ * The Zerops project a namespace creates when the plan names none: `fabrika-<env>-<id>`, beside the `fabrika-<env>` that
+ * `platform install` creates for the installation, so a namespace reads as fabrika's in the Zerops GUI.
+ */
+export const defaultZeropsNamespaceProjectName = (namespace: { readonly id: string; readonly env: string }): string =>
+	`fabrika-${namespace.env}-${namespace.id}`
+
 /** Build the provider-owned namespace planning surface without any network collaborators. */
 export const createZeropsNamespaceOperator = (
 	options: ZeropsNamespaceOperatorOptions,
@@ -130,7 +137,7 @@ export const createZeropsNamespaceOperator = (
 			const target = zeropsNamespacePreset({
 				preset: input.preset,
 				env: input.env,
-				projectName: planOptions.projectName ?? input.id,
+				projectName: planOptions.projectName ?? defaultZeropsNamespaceProjectName(input),
 				proxySource: options.proxySource,
 				...(planOptions.corePackage === undefined ? {} : { corePackage: planOptions.corePackage }),
 				...(planOptions.publicAccess === undefined ? {} : { publicAccess: planOptions.publicAccess }),

package/src/plan.ts

@@ -5,6 +5,8 @@ export type ZeropsStepKind =
 	| 'apply-import'
 	| 'verify-exposure'
 	| 'write-service-env'
+	| 'raise-start-memory'
+	| 'size-database'
 	| 'reserve-version'
 	| 'upload-source'
 	| 'trigger-build'
@@ -43,6 +45,16 @@ export const buildZeropsPlan = (manifest: FabrikaManifest, target: ZeropsRuntime
 		description: 'Read back that no service has subdomain access and every bucket is one the platform created private',
 	})
 	steps.push({ id: 'write-service-env', kind: 'write-service-env', description: 'Write the managed service variables' })
+	steps.push({
+		id: 'raise-start-memory',
+		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,10 +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 } 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,
@@ -60,6 +78,7 @@ import {
 	SERVICE_MANAGED_KEYS,
 } from './managed-env'
 import {
+	applicationDatabaseOf,
 	approvedSchemaOf,
 	type FabrikaImportDocument,
 	type FabrikaManifest,
@@ -287,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. */
@@ -642,6 +663,140 @@ const writeServiceEnv = async (env: StepEnv): Promise<void> => {
 	}
 }
 
+/** The custom autoscaling with its minimum RAM raised to `minRam`; every other field is sent back as it was read. */
+const withMinRam = (custom: ZeropsServiceAutoscaling, minRam: number): ZeropsServiceAutoscaling => ({
+	...custom,
+	vertical: { ...custom.vertical, minResource: { ...custom.vertical.minResource, memoryGBytes: minRam } },
+})
+
+/**
+ * Raises the deploy service's minimum RAM to what the generated start script needs (`zeropsStartMinRam`), before the
+ * version's containers start. An import cannot: Zerops ignores a changed `verticalAutoscaling` of an existing service,
+ * so an existing service converges here, on every deploy. It only raises, and decides by reading the service back.
+ */
+const raiseStartMemory = async (env: StepEnv): Promise<void> => {
+	const { run, zerops, log, signal, dryRun } = env
+	const locked = lockedExecutionFor(run.artifact, run, dryRun)
+	const minRam = locked === null ? null : zeropsStartMinRam(locked)
+	const hostname = run.artifact.target.deployService
+	if (minRam === null) {
+		log(`  ${hostname} needs no more than the platform's minimum RAM`)
+		return
+	}
+	if (dryRun) {
+		log(`  [dry-run] would raise the minimum RAM of ${hostname} to ${minRam} GB where it is lower`)
+		return
+	}
+	assertRunning(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 maxRam = current.vertical.maxResource.memoryGBytes
+	if (maxRam !== null && maxRam < minRam) {
+		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: 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})`)
+		}
+		throw error
+	}
+	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: 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`)
+	}
+	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`). */
 const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 	const { run, zerops, compiled, log, signal, dryRun, attempt } = env
@@ -696,6 +851,16 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 			return
 		}
 
+		case 'raise-start-memory': {
+			await raiseStartMemory(env)
+			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}`)
@@ -763,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)`)

package/src/source/port.ts

@@ -55,3 +55,14 @@ export interface ZeropsSourcePort {
 	resolve(input: ZeropsSourceResolveInput): Promise<ZeropsSourceResolution>
 	upload(input: ZeropsSourceUploadInput): Promise<ZeropsSourceUploadResult>
 }
+
+/**
+ * The source refused a read for GitHub's rate limit. The read succeeds again once the limit resets, so a namespace
+ * mutation that hits it stays retryable. The message is the user's: whose limit, when it resets, how to avoid it.
+ */
+export class ZeropsSourceRateLimitedError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'ZeropsSourceRateLimitedError'
+	}
+}