@fabrika/provider-zerops 0.9.0-dev.1 → 0.9.0-dev.2

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

@@ -0,0 +1,19 @@
+export interface ZeropsCliArgs {
+    command: string | undefined;
+    subcommand: string | undefined;
+    env: string | undefined;
+    config: string;
+    output: string;
+    namespaceId: string | undefined;
+    preset: string | undefined;
+    exclusiveAppId: string | undefined;
+    projectId: string | undefined;
+    projectName: string | undefined;
+    corePackage: string | undefined;
+    publicAccess: string | undefined;
+    postgresType: string | undefined;
+    postgresProfile: string | undefined;
+    controlUrl: string | undefined;
+    help: boolean;
+}
+export declare const parseZeropsCliArgs: (argv: readonly string[]) => ZeropsCliArgs;

package/types/src/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+export declare const readZeropsSourceDescriptor: (root?: string) => Promise<import("./manifest").ZeropsArtifactSourceDescriptor>;
+export interface ZeropsManifestBuildOptions {
+    /** App config path, resolved against the working directory like `--config`. */
+    readonly config: string;
+    readonly env: string;
+}
+/** The exact text `build` writes to `fabrika.manifest.json`, produced in memory and written nowhere. */
+export declare const buildZeropsManifestText: (options: ZeropsManifestBuildOptions) => Promise<string>;
+export declare const runZeropsCli: (argv: readonly string[]) => Promise<void>;

package/types/src/collaborators.d.ts

@@ -0,0 +1,18 @@
+import type { SchemaReconciler } from '@fabrika/provider-contract';
+import { type ZeropsApi } from './api';
+import { type ExposureAlerter } from './exposure';
+import type { ZeropsSourcePort } from './source/port';
+import type { ZeropsRuntimeTarget } from './types';
+export type Sleeper = (ms: number, signal: AbortSignal) => Promise<void>;
+export declare const defaultSleep: Sleeper;
+export interface ZeropsCollaborators {
+    api: ZeropsApi;
+    /** Injected by the Zerops control composition; dry runs do not require it. */
+    source?: ZeropsSourcePort;
+    reconcileSchema: SchemaReconciler;
+    /** Raises the Operations alert for a refused activation; best-effort. */
+    alertExposure: ExposureAlerter;
+    sleep: Sleeper;
+}
+export type ZeropsCollaboratorFactory = (target: ZeropsRuntimeTarget) => ZeropsCollaborators;
+export declare const defaultZeropsCollaborators: ZeropsCollaboratorFactory;

package/types/src/compile.d.ts

@@ -0,0 +1,91 @@
+import type { JsonValue } from '@fabrika/provider-contract';
+import type { ZeropsImportProject, ZeropsImportService } from './schema.generated';
+import type { ZeropsResourceContext, ZeropsSourceTarget } from './types';
+/** The ONLY value fabrika ever writes for `envIsolation`, at either level. Not a default — an assertion. */
+export declare const ENV_ISOLATION: 'service';
+/**
+ * The ONLY value fabrika ever writes for `override`, on EVERY service class including managed ones.
+ * Live-verified: without it a re-apply is `400 serviceStackNameUnavailable` — see `compileService`.
+ */
+export declare const OVERRIDE: true;
+/** A compiled import document: exactly the two top-level keys the platform's schema defines. */
+export interface ZeropsImportDocument {
+    /** Present only when fabrika is creating/reconciling the project itself. */
+    project?: ZeropsImportProject;
+    services: ZeropsImportService[];
+}
+/**
+ * The same document once it has been through JSON — a manifest's stored `importDocument`, or one whose
+ * values were substituted. Structurally identical, leaves typed as JSON, so `assertZeropsInvariants`
+ * checks it too rather than trusting whoever produced it.
+ */
+export interface ZeropsJsonImportDocument {
+    readonly project?: {
+        readonly [key: string]: JsonValue;
+    };
+    readonly services: ReadonlyArray<{
+        readonly [key: string]: JsonValue;
+    }>;
+}
+/** What the compiler needs beyond the app's declaration. */
+export interface CompileInput {
+    target: ZeropsSourceTarget;
+    ctx: ZeropsResourceContext;
+    /**
+     * Provision every service WITHOUT code — the answer to ADR-0004's "no secret can be set before the
+     * service exists" gap. Import the services, write their secrets through the env API, deploy later.
+     * Applied on top of whatever a service declared, because it is a property of THIS import, not of the app.
+     */
+    startWithoutCode?: boolean;
+}
+/**
+ * The last gate before serialization: re-check ADR-0004's invariants on the FINISHED document. The types
+ * make a violation unauthorable and the construction makes it unemittable; this catches everything else —
+ * a config deserialized from JSON, a document assembled by hand, a future edit to this file.
+ *
+ * Deliberately checks the emitted document rather than the input: it is the document that reaches Zerops.
+ */
+export declare const assertZeropsInvariants: (document: ZeropsImportDocument | ZeropsJsonImportDocument) => void;
+/** Compile an app's Zerops declaration into the import document, invariants already checked. */
+export declare const compileImport: (input: CompileInput) => ZeropsImportDocument;
+/**
+ * Render an arbitrary Zerops document (a `zerops.yaml`, a fragment) with the SAME emitter the import
+ * document uses. Exported so nothing outside this file has to grow a second YAML writer: two emitters
+ * disagreeing about quoting or block scalars is a class of bug worth spending one export to avoid.
+ *
+ * Deliberately does NOT assert the import invariants — it does not know it is looking at an import
+ * document. `renderImportYaml` is the entry point that does, and it is the one the driver calls.
+ */
+export declare const renderYaml: (value: unknown) => string;
+/**
+ * Render a compiled document as the `zerops-import.yaml` text the API takes. Re-asserts the invariants:
+ * this is the last place the document is still inspectable, and the only place it becomes a string.
+ */
+export declare const renderImportYaml: (document: ZeropsImportDocument) => string;
+/** Compile + render in one step — what the driver's `apply-import` step actually calls. */
+export declare const compileImportYaml: (input: CompileInput) => {
+    document: ZeropsImportDocument;
+    yaml: string;
+};
+/**
+ * Compile the PROVISIONING import: the same document with every service forced `startWithoutCode: true`.
+ *
+ * This is ADR-0004's recorded gap closed. The ADR accepted a cost — "no secret can be set before the
+ * Zerops service exists, so registration must provision" — and `startWithoutCode` makes that provisioning
+ * cheap and code-free. The order becomes: register the app → import its services with no code → write
+ * their secrets through the SERVICE-level env API → deploy later. No local secret buffer, no secret in
+ * this document, and no secret held anywhere fabrika could leak it.
+ *
+ * Called by the control plane at EDIT time, not by the driver: on Zerops, pushing secrets is not a deploy
+ * step at all.
+ *
+ * **This document is the one that is NOT safe to re-apply, and `override` does not make it safe.**
+ * Verified live: re-applying it at a service that already carries code starts a `stack.deploy` and
+ * activates a new, EMPTY app version — the running code becomes a `BACKUP`. The steady-state document
+ * (no `startWithoutCode`) is a complete no-op on the same services. So this form belongs to first
+ * bring-up only; anything that reconciles an existing project applies `compileImportYaml`.
+ */
+export declare const compileProvisioningYaml: (input: Omit<CompileInput, "startWithoutCode">) => {
+    document: ZeropsImportDocument;
+    yaml: string;
+};

package/types/src/control.d.ts

@@ -0,0 +1,41 @@
+import type { ControlProvider, ProviderCodec, SchemaReconciler } from '@fabrika/provider-contract';
+import { type ZeropsApi } from './api';
+import { type Sleeper } from './collaborators';
+import { type ExposureAlerter } from './exposure';
+import { type ZeropsNamespaceProxySource } from './namespace';
+import { type OlderProxyReaders } from './namespace/proxy-reads';
+import type { ZeropsSourcePort } from './source/port';
+import type { ZeropsRunState } from './types';
+/** Provider coordinates that are safe to persist. Credentials are composed only for a live run. */
+export interface ZeropsStoredTarget {
+    serviceId: string;
+    /**
+     * The object-storage service ids the first registration's collision-refusing import created: the creation evidence
+     * the first deploy writes into the provenance marker (ADR-0043). Absent when that import created no bucket.
+     */
+    createdBuckets?: string[];
+}
+export declare const zeropsStoredTargetCodec: ProviderCodec<ZeropsStoredTarget>;
+export interface ZeropsControlProviderOptions {
+    readonly accessToken: string;
+    readonly apiBaseUrl?: string;
+    readonly propustkaUrl?: string;
+    readonly adminKey?: string;
+    readonly api?: ZeropsApi;
+    readonly source: ZeropsSourcePort;
+    readonly reconcileSchema?: SchemaReconciler;
+    readonly alertExposure?: ExposureAlerter;
+    readonly sleep?: Sleeper;
+    readonly namespaces?: {
+        readonly clientId: string;
+        readonly proxySource: ZeropsNamespaceProxySource;
+        readonly iamUrl: string;
+        readonly iamKey: string;
+        /** The manifest parsers of the older releases' proxies, which a namespace pinned to an older source may run. */
+        readonly olderProxies: OlderProxyReaders;
+    };
+}
+/** The run checkpoint (ADR-0044), or null for anything else — an older shape included. */
+export declare const parseZeropsCheckpoint: (value: unknown) => ZeropsRunState | null;
+/** Build the complete Zerops lifecycle bundle without importing control-plane persistence. */
+export declare const createZeropsControlProvider: (options: ZeropsControlProviderOptions) => ControlProvider;

package/types/src/database-budget.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare const ZEROPS_POSTGRES_RAM_STEPS_GB: readonly number[];
+/** The lowest step, and the smallest RAM a PostgreSQL service is given (`oltp-hobby`'s floor). */
+export declare 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 declare const ZEROPS_POSTGRES_UNAVAILABLE_CONNECTIONS = 7;
+/**
+ * The most connections one container's init commands hold 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 declare 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 declare 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 declare const MAX_PROCESS_CONNECTIONS = 10;
+/** Zerops' own maximum, which a runtime whose horizontal autoscaling reads nothing may scale to. */
+export declare 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 declare function zeropsPostgresMaxConnections(ramGB: number, profile: string | undefined): number;
+/**
+ * The connections each process may open so that all of them, with one container's init commands, stay within what the
+ * application's roles can take; `null` when that is below `MIN_PROCESS_CONNECTIONS`.
+ */
+export declare function zeropsProcessConnections(maxConnections: number, demand: ZeropsDatabaseDemand): number | null;
+/** The smallest RAM step at which each process gets at least `MIN_PROCESS_CONNECTIONS`, or null when none does. */
+export declare function zeropsDatabaseMinRam(demand: ZeropsDatabaseDemand, profile: string | undefined): number | null;

package/types/src/descriptor.d.ts

@@ -0,0 +1,28 @@
+import type { JsonValue } from '@fabrika/provider-contract';
+export interface ZeropsDescriptor {
+    document: {
+        readonly [key: string]: JsonValue;
+    };
+    setups: readonly string[];
+}
+export interface PreparedZeropsDescriptor {
+    contents: string;
+    setup: string;
+}
+export declare const parseZeropsDescriptor: (contents: string) => ZeropsDescriptor;
+export declare const selectZeropsDescriptorSetup: (parsed: ZeropsDescriptor, setup?: string) => string;
+/**
+ * The setup entries a deploy of `selected` applies: the selected one and, transitively, every setup it
+ * `extends`. Only these reach the running service; the other setups in the file never do.
+ */
+export declare const appliedZeropsSetups: (parsed: ZeropsDescriptor, selected: string) => JsonValue[];
+/**
+ * Refuse a selected setup that `extends` another without its own `run`: Zerops merges `extends` per
+ * whole section, and the deploy writes `FABRIKA_RELEASE` into `run`, which would replace the inherited one.
+ */
+export declare const assertOwnRunWhenExtending: (parsed: ZeropsDescriptor, selected: string) => void;
+/** The document Zerops executes: the selected setup and what it extends, which is exactly what the ownership check read. */
+export declare const executionZeropsDocument: (parsed: ZeropsDescriptor, selected: string) => {
+    readonly [key: string]: JsonValue;
+};
+export declare const prepareZeropsDescriptor: (contents: string, setup?: string) => PreparedZeropsDescriptor;

package/types/src/execution.d.ts

@@ -0,0 +1,137 @@
+import { type ContractArtifact, type DevLauncherConfig } from '@fabrika/auth-core';
+import type { OperationsAssetRoot, OperationsSourceMapBuildUpload } from '@fabrika/operations-contract/releases';
+import { type JsonValue } from '@fabrika/provider-contract';
+import { type PreparedZeropsDescriptor } from './descriptor';
+/** The port the generated entrypoint listens on (`PORT`), and the one the proxy dials. */
+export declare const ZEROPS_APPLICATION_PORT = 3000;
+/** The runtime every contract application runs on: the generated entrypoint is a Bun program. */
+export declare const ZEROPS_APPLICATION_RUNTIME = "alpine/bun@1.3";
+/**
+ * This package's own version. Control runs the git checkout of its release tag, so this reads the source version,
+ * which `release:validate` holds equal to the tag; the public packages are released together, so it is the checker
+ * release of the installation. A build checks with the application's own release instead (`checkRelease`).
+ */
+export declare const FABRIKA_CHECK_VERSION: string;
+/** The compiler the platform type-checks with. It is fetched by version, never taken from the application's lockfile. */
+export declare const PLATFORM_TYPESCRIPT_VERSION = "5.9.3";
+/** System packages an application may add to its runtime image, installed by the generated `run.prepareCommands`. */
+export declare const ZEROPS_RUNTIME_PACKAGES: readonly ["ffmpeg", "ghostscript", "imagemagick", "poppler-utils", "vips"];
+export type ZeropsRuntimePackage = (typeof ZEROPS_RUNTIME_PACKAGES)[number];
+export interface ZeropsContractJob {
+    readonly name: string;
+    readonly schedule: string;
+}
+/** The framework's file scan job (`@fabrika/app`'s `FILE_SCAN_JOB`), run every minute when a collection scans. */
+export declare const ZEROPS_FILE_SCAN_JOB = "fabrika-file-scan";
+/** The framework's file sweep job (`@fabrika/app`'s `FILE_SWEEP_JOB` and its schedule), run when the contract has files. */
+export declare const ZEROPS_FILE_SWEEP_JOB = "fabrika-file-sweep";
+/**
+ * The RAM in GB a container of a scanning application starts with: one `clamscan` over a batch peaks at about 1 GB
+ * resident while it loads its signatures (measured with ClamAV 1.4), beside the application's own process.
+ */
+export declare const ZEROPS_SCAN_MIN_RAM_GB = 2;
+/**
+ * The RAM in GB a container of an application with a database starts with. Its init commands run `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 declare 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 declare function zeropsStartMinRam(execution: ZeropsLockedExecution): number | null;
+/** What the generated run section needs from a contract; derived from the artifact by `zeropsContractRun`. */
+export interface ZeropsContractRun {
+    /** The contract digest the application compares at startup (`FABRIKA_CONTRACT_DIGEST`). */
+    readonly digest: string;
+    /** The path of the contract's health endpoint, which the readiness and health checks request. */
+    readonly readinessPath: string;
+    readonly jobs: readonly ZeropsContractJob[];
+    /** Present when the contract declares a file collection: the crontab runs the sweep of removed files. */
+    readonly files?: true;
+    /** Present when a file collection scans its uploads: the build installs ClamAV and the crontab runs the scan. */
+    readonly scan?: true;
+}
+/** Everything one locked execution descriptor is rendered from. */
+export interface ZeropsLockedExecution {
+    readonly appId: string;
+    readonly contract: ZeropsContractRun;
+    /**
+     * The release of the reader that read the application (`ProviderApprovedAccess.checker`), the newest patch of the
+     * framework minor it pins: the build runs `fabrika-check` and `fabrika-source-maps` of `@fabrika/check` at it.
+     */
+    readonly checkRelease: string;
+    /** 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[];
+    /** Where the build uploads its source maps, without the bearer; null when Control minted no upload for the run. */
+    readonly sourceMaps: OperationsSourceMapBuildUpload | null;
+    /**
+     * Present for an environment of kind `dev` (ADR-0049): `run.start` runs the dev launcher instead of the serving
+     * entry. The environment's kind selects it; an application never authors it.
+     */
+    readonly dev?: ZeropsDevExecution;
+}
+export interface ZeropsDevExecution {
+    /** The commit the bootstrap run builds: what a new container holds before the launcher's first sync. */
+    readonly head: string;
+}
+/** The application ids the generated scripts may name: the contract's own id rule, so a script needs no quoting. */
+export declare const LOCKED_APP_ID_PATTERN: RegExp;
+export declare const CONTRACT_DIGEST_PATTERN: RegExp;
+/** A literal path of unreserved characters: it is written into the generated probes unquoted by any shell. */
+export declare const READINESS_PATH_PATTERN: RegExp;
+/**
+ * The run facts of a contract, with the digest the application's own release computes for it. A contract without a
+ * health endpoint has nothing a readiness check can request.
+ */
+export declare function zeropsContractRun(artifact: ContractArtifact, digest: string): 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 the deploy's `raise-start-memory` step raises an existing service.
+ */
+export declare function assertScanMemory(services: readonly {
+    readonly [key: string]: JsonValue;
+}[], deployService: string, run: ZeropsContractRun): void;
+/** The directories a contract serves its pages from: each SPA mount's and each share link's SPA, by URL prefix. */
+export declare function zeropsAssetRoots(artifact: ContractArtifact): OperationsAssetRoot[];
+interface AuthoredBuild {
+    readonly base: string | string[] | null;
+    readonly os: string | null;
+    readonly commands: string[];
+}
+/** Refuse every key of a contract application's setup the platform owns, and return what it keeps. */
+export declare function lockedAuthoredBuild(entry: {
+    readonly [key: string]: JsonValue;
+}, setup: string): AuthoredBuild;
+/** What the dev launcher reads (`DEV_LAUNCHER_CONFIG_FILE`): the platform's, written after the checks. */
+export declare function devLauncherConfig(execution: ZeropsLockedExecution, authoredSpa: readonly string[]): DevLauncherConfig;
+/**
+ * The generated build commands, in order; the authored SPA commands run before all of them. The application's tests
+ * run first: they are authored code, so everything after them is reinstalled, regenerated or checked again. They run
+ * `--isolate`, as the application skill runs them: a test file's DOM globals otherwise leak into the next file. `tsc`
+ * runs before the checker, as in the skill's loop: the usual quick fix of a type error is a cast or an `any`, which only
+ * the checker refuses, so the checker is the last word on the code.
+ */
+export declare function generatedBuildCommands(execution: ZeropsLockedExecution, authoredSpa?: readonly string[]): readonly string[];
+/** How many job processes the crontab may run at once, each opening the application's database. */
+export declare const zeropsJobProcesses: (contract: ZeropsContractRun) => number;
+/** The commands every container runs before `run.start`, in order; any failure stops the activation. */
+export declare function generatedInitCommands(execution: ZeropsLockedExecution): string[];
+/** The generated selected setup: the authored build kept, everything else the platform's. */
+export declare function renderLockedSetup(setup: string, authored: AuthoredBuild, release: string | null, execution: ZeropsLockedExecution): {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * The execution descriptor of a contract application: only the selected setup, generated. The source descriptor's
+ * bytes and digest stay the artifact's identity; this document is what the build request carries.
+ */
+export declare function renderLockedExecutionDescriptor(contents: string, setup: string | undefined, release: string | null, execution: ZeropsLockedExecution): PreparedZeropsDescriptor;
+export {};

package/types/src/exposure.d.ts

@@ -0,0 +1,47 @@
+import type { ZeropsImportResult } from './api';
+/**
+ * The provenance marker: a service variable on the deploy service listing the object-storage service ids the platform
+ * created, each from an import that carried `objectStoragePolicy: private`. A bucket adopted by hostname has none.
+ * The import's answer is the only evidence of creation, so `apply-import` records it here before any other step runs.
+ */
+export declare const STORAGE_PROVENANCE_KEY = "FABRIKA_STORAGE_PROVENANCE";
+export declare const isObjectStorageType: (type: string) => boolean;
+export declare const parseStorageProvenance: (value: string | undefined) => ReadonlySet<string>;
+export declare const formatStorageProvenance: (ids: Iterable<string>) => string;
+/** Hostname → service id of every service this import result reports creating. */
+export declare const createdServices: (result: ZeropsImportResult) => ReadonlyMap<string, string>;
+/** How the deploy service holds the marker: a release up to v0.4.2 wrote it sensitive, which reads back without its value. */
+export type StorageProvenanceMarker = 'absent' | 'readable' | 'sensitive';
+/** The refusal of a bucket no evidence names, with the two remedies an operator has without sudo. */
+export declare const unprovenBucketReason: (input: {
+    bucketId: string;
+    deployService: string;
+    marker: StorageProvenanceMarker;
+}) => string;
+export interface ExposureFinding {
+    readonly hostname: string;
+    readonly reason: string;
+}
+export declare const formatExposureFindings: (findings: readonly ExposureFinding[]) => string;
+export interface ExposureAlert {
+    readonly appId: string;
+    readonly env: string;
+    readonly release: string | null;
+    readonly findings: readonly ExposureFinding[];
+}
+/**
+ * The Operations ingest request that raises the alert: an error event in the application's own Operations project,
+ * which its `new_issue` alert rules deliver. Null for a DSN of any other form. The public key is not a secret, but it
+ * travels only in this request.
+ */
+export declare function exposureAlertRequest(dsn: string, alert: ExposureAlert, eventId: string): {
+    url: string;
+    body: string;
+} | null;
+export type ExposureAlerter = (input: {
+    readonly dsn: string;
+    readonly alert: ExposureAlert;
+    readonly signal: AbortSignal;
+}) => Promise<void>;
+/** Send the alert. The caller treats a failure as non-fatal: the refusal stands either way. */
+export declare const sendExposureAlert: ExposureAlerter;

package/types/src/index.d.ts

@@ -0,0 +1,31 @@
+export { createZeropsApi, enableSubdomainAccessWhenHttp, readableContent, waitForProcess, ZEROPS_ACTIVE, ZEROPS_API_BASE, ZEROPS_PROCESS_FINISHED, ZEROPS_PROCESS_TERMINAL, ZEROPS_SERVICE_NOT_HTTP, ZEROPS_TERMINAL, ZeropsApiError, } from './api';
+export type { FetchLike, ZeropsApi, ZeropsApiOptions, ZeropsAppVersion, ZeropsAppVersionStatus, ZeropsAppVersionUpload, ZeropsImportedService, ZeropsImportResult, ZeropsIntegrationToken, ZeropsLogAccess, ZeropsLogLine, ZeropsProcess, ZeropsProject, ZeropsProjectMode, ZeropsProjectStatus, ZeropsRoleCode, ZeropsService, ZeropsServiceAutoscaling, ZeropsServiceEnv, ZeropsServiceEnvWrite, ZeropsServiceStatus, ZeropsTokenProjectGrant, ZeropsUserInfo, } from './api';
+export { defineApp, isZeropsAppConfig, useSharedPostgres, zeropsSharedServiceHostname, zeropsSharedServicePrefix } from './authoring';
+export type { ZeropsAuthoredAppConfig } from './authoring';
+export { parseZeropsCliArgs } from './cli-args';
+export type { ZeropsCliArgs } from './cli-args';
+export { defaultSleep, defaultZeropsCollaborators } from './collaborators';
+export type { Sleeper, ZeropsCollaboratorFactory, ZeropsCollaborators } from './collaborators';
+export { assertZeropsInvariants, compileImport, compileImportYaml, compileProvisioningYaml, ENV_ISOLATION, OVERRIDE, renderImportYaml, renderYaml, } from './compile';
+export type { CompileInput, ZeropsImportDocument, ZeropsJsonImportDocument } from './compile';
+export { createZeropsControlProvider, parseZeropsCheckpoint, zeropsStoredTargetCodec } from './control';
+export type { ZeropsControlProviderOptions, ZeropsStoredTarget } from './control';
+export { type PreparedZeropsDescriptor, prepareZeropsDescriptor } from './descriptor';
+export { assertFabrikaManifestCoordinates, compileFabrikaManifest, createZeropsArtifactSourceDescriptor, FABRIKA_MANIFEST_VERSION, manifestServiceHostnames, parseFabrikaManifest, renderFabrikaImportYaml, verifyZeropsArtifactSourceDescriptor, ZEROPS_SERVICE_HOSTNAME_PATTERN, ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES, zeropsArtifactCodec, } from './manifest';
+export type { FabrikaImportDocument, FabrikaManifest, ManifestExpectation, ZeropsArtifactSourceDescriptor } from './manifest';
+export { compileZeropsNamespaceTopology, createZeropsNamespaceCapabilities, createZeropsNamespaceOperator, decodeZeropsNamespaceProxySource, republishProxy, verifyZeropsNamespaceProxySource, ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE, ZEROPS_NAMESPACE_IAM_KEY_VARIABLE, ZEROPS_NAMESPACE_POSTGRES_HOSTNAME, ZEROPS_NAMESPACE_PROXY_HOSTNAME, ZEROPS_SHARED_POSTGRES_CONNECTION_STRING, zeropsNamespacePreset, zeropsNamespaceTargetCodec, } from './namespace';
+export type { ZeropsNamespaceOperatorOptions, ZeropsNamespaceOptions, ZeropsNamespacePlanOptions, ZeropsNamespacePostgres, ZeropsNamespacePresetInput, ZeropsNamespaceProxyBuild, ZeropsNamespaceProxyDeployment, ZeropsNamespaceProxySource, ZeropsNamespacePublicAccess, ZeropsNamespaceTarget, ZeropsNamespaceTopology, ZeropsProxyApi, ZeropsProxyRepublishInput, } from './namespace';
+export { postgresSchema as zeropsNamespacePostgresSchema } from './namespace/codec';
+export { entriesNeedingCurrentProxy } from './namespace/proxy-reads';
+export type { OlderProxyReader, OlderProxyReaders } from './namespace/proxy-reads';
+export { buildZeropsPlan, resolveDeployHostname } from './plan';
+export type { ZeropsStep, ZeropsStepKind } from './plan';
+export { CANCELLED, createZeropsDeployer, interpolateManifest } from './provider';
+export type { ZeropsDeployResult, ZeropsDeployRun } from './provider';
+export { ZEROPS_PROXY_MANIFEST_PATH, type ZeropsProxyManifestCarrier, zeropsProxyManifestCarrier } from './proxy-manifest-carrier';
+export type * from './schema.generated';
+export { isZeropsUploadDestination, normalizeZeropsSourceRepository } from './source';
+export type { ZeropsSourceRepository } from './source';
+export { ZeropsSourceRateLimitedError } from './source/port';
+export type { ZeropsSourceArchive, ZeropsSourcePort, ZeropsSourcePrivateBinding, ZeropsSourceResolution, ZeropsSourceResolveInput, ZeropsSourceUploadInput, ZeropsSourceUploadResult, } from './source/port';
+export type { ZeropsAppConfig, ZeropsCompilerOwnedProjectField, ZeropsCompilerOwnedServiceField, ZeropsDuration, ZeropsHealthCheckSpec, ZeropsNamespaceResourceRequirement, ZeropsProjectSpec, ZeropsProxySpec, ZeropsReadinessCheckSpec, ZeropsResourceContext, ZeropsRunState, ZeropsRuntimeSource, ZeropsRuntimeTarget, ZeropsServiceSpec, ZeropsSharedPostgresBinding, ZeropsSourceTarget, ZeropsYamlDeploySpec, ZeropsYamlRunSpec, ZeropsYamlSetupSpec, ZeropsYamlSpec, } from './types';

package/types/src/installation/admin-options.d.ts

@@ -0,0 +1,24 @@
+/** Every input `runPlatformAdmin` takes from the operator. */
+export interface PlatformAdminInput {
+    /** The mailbox that identifies the first administrator. */
+    readonly email: string;
+    /** IAM's public hostname — the address the proxy fronts, as `platform deploy` names it. */
+    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` wrote to its secrets file. Environment only. */
+    readonly provisioningKey: string;
+    /** Replace an outstanding enrollment instead of reporting it. */
+    readonly reissue: boolean;
+}
+/**
+ * The one way a second enrollment URL is ever issued.
+ *
+ * Printing the URL once is the property a re-run has to keep, so an outstanding enrollment is
+ * REPORTED rather than replaced. An enrollment that expired unopened would otherwise be a dead end —
+ * the only other way to issue one is a console nobody can sign in to yet — so the way out is a flag,
+ * which makes replacing the outstanding one an explicit choice.
+ */
+export declare const REISSUE_FLAG = "--reissue";
+/** Parse the command's arguments and environment into the one input `runPlatformAdmin` takes. */
+export declare const parsePlatformAdminArgs: (argv: readonly string[], env: Record<string, string | undefined>) => PlatformAdminInput;

package/types/src/installation/admin.d.ts

@@ -0,0 +1,35 @@
+import { type FirstAdministratorApi } from '@fabrika/installation-init';
+import type { PlatformAdminInput } from './admin-options';
+/**
+ * Where this command's progress goes.
+ *
+ * The same rule the rest of this package's logging states: no helper here takes a secret value. The
+ * enrollment URL is a credential in transit and never travels through the log — it goes to `print`,
+ * which is stdout and nothing else.
+ */
+export interface AdminLog {
+    step(title: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    ok(message: string): void;
+}
+/** `AdminLog` plus the boxed hand-off the closing block uses — composed in below, not asked of the caller. */
+export interface AdminReportLog extends AdminLog {
+    action(title: string, lines: readonly string[]): void;
+}
+export interface PlatformAdminCollaborators {
+    readonly client: FirstAdministratorApi;
+    readonly log: AdminReportLog;
+    /** stdout, for the command's one piece of DATA: the enrollment URL, on a line of its own. */
+    readonly print: (line: string) => void;
+}
+/** The real collaborators: the typed admin client for this installation's public IAM, and the console. */
+export declare const consoleAdminCollaborators: (input: PlatformAdminInput, log: AdminLog) => PlatformAdminCollaborators;
+/**
+ * Admit the first administrator, and report exactly what was found rather than what was assumed.
+ *
+ * Nothing is printed before the whole sequence has succeeded except its progress: a failure — an
+ * unreachable IAM, a refused key, a 4xx — throws, and the CLI exits non-zero with that one message.
+ * No partial result and, above all, no URL.
+ */
+export declare const runPlatformAdmin: (input: PlatformAdminInput, collaborators: PlatformAdminCollaborators) => Promise<void>;

package/types/src/installation/checker-release.d.ts

@@ -0,0 +1,12 @@
+/** The package every contract application build fetches by this checkout's version. */
+export declare const FABRIKA_CHECK_PACKAGE = "@fabrika/check";
+/** Whether npm has `@fabrika/check` at `version`. Throws when it cannot tell. */
+export type CheckerPublication = (version: string, signal: AbortSignal) => Promise<boolean>;
+export type RegistryFetch = (url: string, init: RequestInit) => Promise<Response>;
+export declare const npmCheckerPublication: (fetchImpl?: RegistryFetch) => CheckerPublication;
+/**
+ * Refuse a checkout whose checker npm does not have. Every contract application build of the installation fetches
+ * `@fabrika/check` at this checkout's version, so without it no application could deploy. Between a release's bump
+ * commit and its publish, `main` is such a checkout.
+ */
+export declare const assertCheckerPublished: (published: CheckerPublication, signal: AbortSignal, version?: string) => Promise<void>;

package/types/src/installation/deploy-options.d.ts

@@ -0,0 +1,37 @@
+import { type McpClient } from './mcp';
+/** How the project this installation lives in is named. */
+export type ZeropsProjectSelector = {
+    readonly kind: 'id';
+    readonly projectId: string;
+} | {
+    readonly kind: 'name';
+    readonly clientId: string;
+    readonly name: string;
+};
+/** Every input `deployPlatform` takes from the operator. */
+export interface PlatformDeployInput {
+    readonly project: ZeropsProjectSelector;
+    /** Zerops personal or integration access token. Environment only. */
+    readonly accessToken: string;
+    /** Region API base, when the installation is not on the default one. */
+    readonly apiBaseUrl?: string;
+    /** The name this installation calls itself — written to every platform service as `ENVIRONMENT`. */
+    readonly environment: string;
+    /** All three or none: none derives them from the proxy's Zerops subdomains. */
+    readonly hosts?: {
+        readonly iam: string;
+        readonly control: string;
+        readonly operations: string;
+    };
+    /** The scheme a browser speaks to this installation. `https` unless a local composition says otherwise. */
+    readonly scheme: 'http' | 'https';
+    readonly sourceDir: string;
+    /** The MCP clients this installation trusts. Absent leaves MCP authoring off (ADR-0049). */
+    readonly mcpClients?: readonly McpClient[];
+    /** IAM-issued `px_` admin key, used only to reconcile the console's schema. Environment only. */
+    readonly iamAdminKey: string;
+    /** Read everything, write nothing, trigger nothing. */
+    readonly dryRun: boolean;
+}
+/** Parse the command's arguments and environment into the one input `deployPlatform` takes. */
+export declare const parsePlatformDeployArgs: (argv: readonly string[], env: Record<string, string | undefined>) => PlatformDeployInput;