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

package/types/src/installation/topology/invariants.d.ts

@@ -0,0 +1,23 @@
+import type { ZeropsImportDocument } from '../../index';
+export declare const assertZeropsHostnames: (document: ZeropsImportDocument) => void;
+/**
+ * ADR-0022: **only the proxy is publicly routed.** App services, the IAM service, the control plane and
+ * the databases stay internal and are reached over the project's private network.
+ *
+ * Zerops makes this the default — a service is not publicly accessible until you opt in — so the failure
+ * this guards against is not "we forgot to lock something down" but "someone added
+ * `enableSubdomainAccess: true` to debug a service and it shipped". That is a one-word diff and it is
+ * exactly the kind of thing review misses.
+ *
+ * `publicService` may be absent, which asserts that NOTHING in the document is publicly routed — the
+ * right assertion for a document whose public entry point lives in another import.
+ */
+export declare const assertOnlyPublicService: (document: ZeropsImportDocument, publicService?: string) => void;
+/**
+ * `corePackage` is per-project, upgrade-only, and its upgrade is partially destructive (logs and
+ * statistics are lost) — so it is the one field in this document that a later `PUT` cannot fix
+ * (ADR-0006). Require it to be stated rather than inherited from the platform default (`LIGHT`).
+ */
+export declare const assertCorePackageIsExplicit: (document: ZeropsImportDocument) => void;
+/** All three, for a document that creates its own project. */
+export declare const assertTopologyInvariants: (document: ZeropsImportDocument, publicService?: string) => void;

package/types/src/installation/topology/setups.d.ts

@@ -0,0 +1,58 @@
+import type { ZeropsYamlSpec } from '../../index';
+/**
+ * The auth enforcement proxy — Caddy for HTTP correctness, a compiled Bun auth service for every
+ * authorization decision (ADR-0022: the endpoint table is NEVER compiled into Caddy routes).
+ *
+ * This is the only setup deployed into BOTH projects, and the only publicly routed service in either.
+ *
+ * Per-service variables (env API): `FABRIKA_IAM_ISSUER` — `http://iam:3000` in the platform project, the
+ * IAM service's PUBLIC origin in an apps project, because there is no private network between projects
+ * (ADR-0006). The manifest is not a variable; see below.
+ *
+ * Secret (`envSecrets`): `FABRIKA_IAM_KEY` — the value IAM knows as `FABRIKA_IAM_PROXY_KEY`.
+ *
+ * ── How the manifest reaches the build ───────────────────────────────────────────────────────────
+ *
+ * `proxy.manifest.json` tells the proxy which apps it fronts, at which upstream, under which endpoint table. It
+ * is baked into the artifact at BUILD time, which is what `docs/backlog/08` chose ("redeploy") over
+ * pushing to Caddy's admin API. It arrives as the one generated data file of the uploaded build archive
+ * (ADR-0045), beside the exact public commit, at a path the commit does not hold: Control streams it into a
+ * namespace proxy's archive (`republishProxy`, `packages/provider-zerops/src/namespace/proxy-attempt.ts`), and
+ * `platform install` / `platform deploy` append it to the platform proxy's (`installation/platform-archive.ts`).
+ * It never travels through the service environment, whose values Zerops caps at ~32 KB.
+ *
+ * Releases before this one lifted `FABRIKA_PROXY_MANIFEST_JSON` from the env API into the build instead.
+ * A namespace pinned to such a release keeps that descriptor, and Control keeps writing the variable for it
+ * (`zeropsProxyManifestCarrier`): never add the lift back, or a pin of this release would get the variable.
+ *
+ * What IS structural: a missing or malformed file makes `generate-config.ts` exit non-zero, so the
+ * pipeline fails and the previous version keeps serving. A valid empty app list generates only the
+ * terminal 404 route, and the auth service denies every forwarded request.
+ */
+/**
+ * The proxy's public listeners.
+ *
+ * Routing is by HOST — one app owns one hostname, and `assertUniqueHosts` refuses to let two apps share
+ * one so that Caddy's route order can never decide which app answers. A production installation gets
+ * those hostnames from custom domains bound to the project's balancer, and needs exactly ONE listener:
+ * every domain arrives on the same port and the Host header decides.
+ *
+ * A `zerops-subdomain` installation has no such source of names. Zerops mints one generated hostname per
+ * HTTP PORT, so on that path a port IS a hostname — and the number of listeners is the number of
+ * distinct public hosts the installation can ever serve. Three are the platform's own (IAM's JWKS and
+ * OIDC redirect, the control dashboard, Operations ingest); the rest are a fixed pool of APPLICATION
+ * slots, and running out of them is what caps a light-tier installation rather than any resource limit.
+ *
+ * That ceiling is the honest cost of the subdomain path and the reason it is not the production one.
+ * A custom-domain installation ignores all of this: with `enableSubdomainAccess: false` nothing here is
+ * published, the extra listeners answer the same host-matched routes, and an unknown Host still falls
+ * through to the terminal 404. One setup serves both tiers rather than a second that must be kept in
+ * step with this one.
+ *
+ * 8081 is deliberately absent: it is the health listener, which is never published.
+ */
+export declare const PROXY_PUBLIC_PORTS: number[];
+/** Liveness only, on its own unpublished listener. */
+export declare const PROXY_HEALTH_PORT = 8081;
+/** The repository-root `zerops.yaml`, in the order the setups appear in it. */
+export declare const fabrikaZeropsYaml: ZeropsYamlSpec;

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

@@ -0,0 +1,148 @@
+import { type ZeropsImportDocument, type ZeropsNamespacePostgres, type ZeropsSourceTarget } from '../../index';
+/**
+ * How a project's single public entry point is published.
+ *
+ * `enableSubdomainAccess` is documented as "not suitable for production", so production takes
+ * `custom-domain`: nothing in the import is publicly routed, and the domain is bound to the project's L7
+ * balancer out of band — the import format has NO field for a custom domain, so that step is manual by
+ * construction and not an oversight here. `zerops-subdomain` is the ONLY thing that ever writes
+ * `enableSubdomainAccess: true` — on the proxy, and on nothing else.
+ *
+ * **NEITHER VALUE IS DELIVERED BY THE IMPORT.** Live-verified: the platform accepts
+ * `enableSubdomainAccess` on a service the document CREATES and then silently drops it, so the service
+ * reads back `subdomainAccess: false` and stays there. The subdomain is established afterwards, by
+ * `PUT /service-stack/{id}/enable-subdomain-access` on a service that already publishes an HTTP port —
+ * which the namespace lifecycle does for itself (`ensureSubdomainAccess` in `src/namespace/provisioning.ts`)
+ * and which an operator applying the generated platform artifacts must do by hand; the artifact's header
+ * names the call. So `true` here records the INTENT and feeds ADR-0022's `assertOnlyPublicService`; it
+ * does not turn anything on.
+ */
+export type PublicAccess = 'custom-domain' | 'zerops-subdomain';
+/**
+ * How much platform an installation pays for.
+ *
+ * `standard` is the production shape: HA Postgres, a separate database and bucket for Operations, and
+ * enough containers that no single one is a point of failure.
+ *
+ * `light` is one project, one `postgresql:single@18` and one bucket shared by IAM, Operations, control
+ * AND the apps deployed alongside them, at one container per service. This tier exists because the standard
+ * shape costs ~13 containers before a single application is deployed, which is more platform than a
+ * small fleet — or an evaluation — can justify.
+ *
+ * Sharing is safe rather than merely cheap, and that is a property of the code, not of this comment:
+ *
+ *   • The three services' table names do not intersect (IAM 10, Operations 24, control 16), and
+ *     ADR-0017 already gives each its own migration ledger and advisory lock, so one database holds
+ *     all three without coordination.
+ *   • Their blob keys are prefix-disjoint — control writes `runs/`, Operations writes `events/`,
+ *     `dead/` and `source-maps/` — so one bucket cannot collide.
+ *
+ * What `light` genuinely gives up is FAILURE-DOMAIN isolation: Operations' high-volume error history
+ * now shares capacity with the identity path, and losing the one database loses all three services.
+ * That is the trade, and it is why `standard` remains the default rather than the special case.
+ */
+export type PlatformTier = 'standard' | 'light';
+export interface TopologyOptions {
+    /** Environment label handed to `services(ctx)`. Part of the project name, so it lands in the GUI too. */
+    env: string;
+    /** How the proxy is published. Production is `custom-domain`. */
+    publicAccess?: PublicAccess;
+    /** How much platform to provision. Defaults to `standard`. */
+    tier?: PlatformTier;
+}
+/** One project's topology plus the facts the invariant checks need. */
+export interface ProjectTopology {
+    /** Stem of the generated filenames, and how this topology is referred to in prose. */
+    id: string;
+    /** The source declaration compiled into the generated topology artifacts. */
+    target: ZeropsSourceTarget;
+    /**
+     * The SAME services with no `project` block, for the project `platform install` created or was handed.
+     *
+     * A document carrying `project:` is only valid at `POST /client/{clientId}/project/import`, which
+     * CREATES a project — and Zerops permits duplicate project names, so applying one at an existing
+     * installation risks a second project rather than failing. Present on both platform tiers.
+     */
+    servicesTarget?: ZeropsSourceTarget;
+    /** The one service allowed to be publicly routed (ADR-0022). Always the proxy. */
+    publicService: string;
+    /** Present on app namespaces so fixtures can prove the selected isolation tier. */
+    namespacePreset?: 'cheap' | 'mid' | 'full';
+    /** Present only when this namespace is reserved for one app. */
+    exclusiveAppId?: string;
+}
+/** The proxy's hostname, in every project. Also the `zerops.yaml` setup name it builds from. */
+export declare const PROXY_HOSTNAME = "proxy";
+/**
+ * The **platform** project: fabrika itself.
+ *
+ * `SERIOUS` is not a comfort choice. This project holds the thing that repairs the other one, so its
+ * availability tier is the recovery story; and because `corePackage` cannot be downgraded, starting
+ * LIGHT and "upgrading when it matters" costs a partially destructive migration at the worst moment.
+ */
+export declare const platformTopology: (options: TopologyOptions) => ProjectTopology;
+/**
+ * An application namespace: one proxy plus the namespace-owned resources selected by its preset.
+ *
+ * This is only an adapter over the provider-owned namespace compiler. The control plane uses that same
+ * compiler for live create/adopt/reconcile operations, so generated bring-up artifacts cannot drift
+ * into a second definition of what an application namespace contains.
+ *
+ * `mid` stays the default for the committed apps-prod artifact: each app imports its own prefixed
+ * database. `cheap` adds namespace-owned Postgres. `full` reserves the project for one app, while the
+ * app's own import still owns its runtime services and database.
+ */
+export interface AppsTopologyOptions extends TopologyOptions {
+    readonly corePackage: 'LIGHT' | 'SERIOUS';
+    readonly preset?: 'cheap' | 'mid' | 'full';
+    readonly projectName?: string;
+    readonly exclusiveAppId?: string;
+    readonly postgres?: ZeropsNamespacePostgres;
+}
+export declare const appsTopology: (options: AppsTopologyOptions) => ProjectTopology;
+/** The topologies this repo commits generated documents for. */
+export declare const fabrikaTopologies: () => ProjectTopology[];
+/** One compiled form: the document, and the YAML text an operator applies. */
+export interface CompiledDocument {
+    document: ZeropsImportDocument;
+    yaml: string;
+}
+/** A compiled topology in every form an operator needs. */
+export interface CompiledTopology {
+    topology: ProjectTopology;
+    /**
+     * First bring-up ONLY: every service `startWithoutCode: true`, so secrets can be written before any
+     * deploy. Applying this a second time at a project whose services already carry code activates a new
+     * EMPTY app version on each of them — verified live. It is not a reconcile document.
+     */
+    provision: CompiledDocument;
+    /**
+     * Steady state: the same document, re-appliable because every service carries `override: true`.
+     *
+     * "Re-appliable" is the whole claim, and deliberately not "reconciling". Live-verified: applying
+     * this at an existing project creates whatever is missing and leaves everything that exists exactly
+     * as it is — a changed `profile`, `minContainers` or `objectStorageSize` in here is accepted by the
+     * API and silently ignored. Changing a live service is a separate, field-specific API call.
+     */
+    steady: CompiledDocument;
+    /**
+     * The two forms above with no `project:` block, present only when the topology declares a
+     * `servicesTarget`. These are what `POST /project/{projectId}/service-stack/import` takes, so they
+     * are the ones a bootstrap applies to a project the operator created.
+     *
+     * Nothing is lost by dropping the block: `envIsolation` is settable at project CREATION only, so a
+     * `project:` here could not correct an existing project even if the endpoint tolerated it, and the
+     * per-service `envIsolation: service` the compiler writes overrides the project's value anyway
+     * (ADR-0004).
+     */
+    servicesProvision?: CompiledDocument;
+    servicesSteady?: CompiledDocument;
+}
+/**
+ * Compile one topology to both documents, asserting every invariant on each.
+ *
+ * The provisioning form exists because of the cost ADR-0004 accepted out loud: on Zerops no secret can
+ * be set before the service exists, since the env API is addressed BY SERVICE. So bring-up is
+ * import-without-code → write secrets → deploy, and `compileProvisioningYaml` is the first of those three.
+ */
+export declare const compileTopology: (topology: ProjectTopology, env: string) => CompiledTopology;

package/types/src/installation/topology/validate.d.ts

@@ -0,0 +1,11 @@
+import type { Artifact } from './artifacts';
+export type SchemaKind = 'import' | 'zerops-yaml';
+export interface SchemaViolation {
+    path: string;
+    message: string;
+}
+export declare const parseYaml: (text: string) => unknown;
+export declare const validateDocument: (kind: SchemaKind, document: unknown) => SchemaViolation[];
+export declare const validateYaml: (kind: SchemaKind, text: string) => SchemaViolation[];
+export declare const schemaKindFor: (path: string) => SchemaKind;
+export declare const assertArtifactMatchesSchema: (artifact: Artifact) => void;

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

@@ -0,0 +1,26 @@
+/** Where the sidecar repository this command edits is found. */
+export type UpgradeSidecar = 
+/** An existing local checkout — the one `platform init` left behind, or any other clone. */
+{
+    readonly kind: 'checkout';
+    readonly dir: string;
+}
+/** `<owner>/<name>`, cloned into a temporary directory for the length of the run. */
+ | {
+    readonly kind: 'repo';
+    readonly repo: string;
+};
+/** Every input `runUpgrade` takes from the operator. */
+export interface PlatformUpgradeInput {
+    /** The published fabrika tag to roll onto, already checked to be one. */
+    readonly to: string;
+    readonly sidecar: UpgradeSidecar;
+    /** The operator's name for this installation, when they gave one. Only ever used in the commit subject. */
+    readonly installation?: string;
+    /** Read everything, write nothing, push nothing. */
+    readonly dryRun: boolean;
+}
+/** The one value-less flag. */
+export declare const UPGRADE_DRY_RUN_FLAG = "--dry-run";
+/** Parse the command's arguments into the one input `runUpgrade` takes. */
+export declare const parsePlatformUpgradeArgs: (argv: readonly string[]) => PlatformUpgradeInput;

package/types/src/installation/upgrade-output.d.ts

@@ -0,0 +1,6 @@
+export declare const carriesTag: (raw: string, tag: string) => boolean;
+export declare const firstRun: (raw: string) => {
+    id: string;
+    url: string;
+    status: string;
+} | undefined;

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

@@ -0,0 +1,88 @@
+import { type Sleeper } from '../index';
+import { type DeployLog } from './log';
+import type { PlatformUpgradeInput } from './upgrade-options';
+/** The public repository whose tags an installation may be pinned to. */
+export declare const FABRIKA_REPOSITORY = "contember/fabrika-platform";
+/** The workflow `platform init` generates, and the only one a roll may be watching. */
+export declare const SIDECAR_WORKFLOW_FILE = "platform.yml";
+/** The branch the generated workflow triggers on (`push: branches: [main]`). */
+export declare const SIDECAR_BRANCH = "main";
+/**
+ * What the public repository answered about a tag.
+ *
+ * THREE answers, not two. `gh` exits non-zero for a rate limit, an expired token and an unreachable
+ * network exactly as it would for a repository that does not exist, and reporting any of those as
+ * `missing` would send an operator to check a tag that is in fact already published.
+ */
+export type TagLookup = {
+    readonly state: 'published';
+} | {
+    readonly state: 'missing';
+} | {
+    readonly state: 'unavailable';
+    readonly reason: string;
+};
+/** One workflow run, as `gh run list` describes it. */
+export interface UpgradeRun {
+    readonly id: string;
+    readonly url: string;
+    /** `queued`, `in_progress`, `completed` — reported so the operator knows why nothing moves yet. */
+    readonly status: string;
+}
+/** Where the sidecar's branch stands relative to what the pipeline actually watches. */
+export interface SidecarBranch {
+    /** The checked-out branch, or `HEAD` when detached. */
+    readonly name: string;
+    /** Commits the upstream does not have; `undefined` when the branch tracks nothing. */
+    readonly ahead: number | undefined;
+}
+/** Everything `runUpgrade` does outside its own process. Injected so the flow can be driven without git or gh. */
+export interface UpgradeEffects {
+    /** Is `gh` installed AND logged in? Every other effect here needs both, so it is asked once, first. */
+    hasGh(): Promise<boolean>;
+    /** Does the public repository carry this tag? The one thing a local check cannot answer. */
+    verifyTag(tag: string): Promise<TagLookup>;
+    /** Clone `<owner>/<name>` into a fresh directory and return it. */
+    cloneSidecar(repo: string): Promise<string>;
+    /** The `<owner>/<name>` this checkout pushes to — also the repository the run is looked for in. */
+    describeCheckout(dir: string): Promise<string>;
+    /** Does the checkout carry uncommitted changes to TRACKED files? Untracked ones are not staged here. */
+    isDirty(dir: string): Promise<boolean>;
+    /** Which branch the checkout is on, and how far ahead of its upstream. */
+    readBranch(dir: string): Promise<SidecarBranch>;
+    /** Stage `files`, commit them with `message`, and return the resulting commit SHA. */
+    commit(input: {
+        readonly dir: string;
+        readonly files: readonly string[];
+        readonly message: string;
+    }): Promise<string>;
+    push(dir: string): Promise<void>;
+    /** The run GitHub registered for `sha`, or undefined while it has not appeared yet. */
+    findRun(input: {
+        readonly repo: string;
+        readonly sha: string;
+    }): Promise<UpgradeRun | undefined>;
+    /** Follow a run to its conclusion. Throws when it ends in anything but success. */
+    watchRun(input: {
+        readonly repo: string;
+        readonly runId: string;
+    }): Promise<void>;
+}
+export interface UpgradeCollaborators {
+    readonly log: DeployLog;
+    readonly effects: UpgradeEffects;
+    readonly sleep: Sleeper;
+    readonly signal: AbortSignal;
+}
+/** The fixed commit subject. Fixed so `git log` in a sidecar reads as the installation's release history. */
+export declare const upgradeCommitMessage: (installation: string, tag: string) => string;
+/**
+ * Roll one installation's sidecar onto a published fabrika tag and follow the deploy it triggers.
+ *
+ * Nothing is written until every refusal has been passed, so a run that stops early leaves the sidecar
+ * exactly as it was — and once the push has landed the roll is under way whether or not this process
+ * survives, which is why the run URL is printed before anything is watched.
+ */
+export declare const runUpgrade: (input: PlatformUpgradeInput, collaborators: UpgradeCollaborators) => Promise<void>;
+/** The real `git` + `gh`, through the one shell-out module that keeps argv verbatim and errors short. */
+export declare const consoleUpgradeCollaborators: () => UpgradeCollaborators;

package/types/src/managed-env.d.ts

@@ -0,0 +1,57 @@
+import { type FrameworkVariableName } from '@fabrika/auth-core';
+import { type PreparedZeropsDescriptor } from './descriptor';
+/** The framework-only names Control hands every Zerops deploy; the rest of the list is the provider's own. */
+export type ManagedKey = Extract<FrameworkVariableName, 'FABRIKA_RELEASE' | 'FABRIKA_OPERATIONS_DSN' | 'FABRIKA_IAM_ISSUER' | 'FABRIKA_IAM_APP_ID' | 'FABRIKA_APP_ID' | 'FABRIKA_ENVIRONMENT' | 'FABRIKA_SERVICE_KEY' | 'FABRIKA_PROXY_SECRET' | 'FABRIKA_IAM_RPC_URL' | 'FABRIKA_IAM_RPC_KEY' | 'FABRIKA_APP_ORIGIN' | 'FABRIKA_TOKEN_KEYS'>;
+export declare const MANAGED_KEYS: readonly ManagedKey[];
+/** The managed keys written as service variables; `FABRIKA_RELEASE` travels only in the execution descriptor (ADR-0044). */
+export declare const SERVICE_MANAGED_KEYS: readonly Exclude<ManagedKey, 'FABRIKA_RELEASE'>[];
+/** The managed keys that carry a credential, written sensitive and therefore never compared. */
+export declare const SENSITIVE_MANAGED_KEYS: ReadonlySet<ManagedKey>;
+/**
+ * A workload, connect or platform transport key and every mail transport variable are written sensitive; a connect or
+ * platform transport URL is an origin.
+ */
+export declare const isSensitiveFamilyVariable: (name: string) => boolean;
+export type ManagedValues = Record<ManagedKey, string | null>;
+export declare function parseManagedValues(value: unknown): ManagedValues;
+/**
+ * What Control hands a deploy: the twelve 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, `FABRIKA_CONNECT_<IMPORT>_KEY` / `_URL`, each
+     * `FABRIKA_EMAIL_*` of the installation's mail transport, and `FABRIKA_PLATFORM_<RECEIVER>_URL` / `_KEY`.
+     */
+    readonly familyVariables: Readonly<Record<string, string>>;
+}
+export declare function parseManagedEnvironment(value: Readonly<Record<string, string | null>>): ManagedEnvironment;
+/**
+ * A service variable only the platform writes per workload, import, platform receiver or the installation's mail
+ * transport: a stale one is removed when the deploy no longer hands it.
+ */
+export declare function isFrameworkFamilyVariable(name: string): boolean;
+/** Refuse every framework-only name (ADR-0043), not only the ones a deploy writes today. */
+export declare function assertAuthoredManagedName(name: string): void;
+type AuthoredDocumentValue = string | number | boolean | null | readonly AuthoredDocumentValue[] | {
+    readonly [key: string]: AuthoredDocumentValue;
+};
+/** Refuse a value that references a framework-only variable (`${RUNTIME_FABRIKA_PROXY_SECRET}`), naming only the reference. */
+export declare function assertNoFrameworkReference(text: string): void;
+/**
+ * Refuse, in any `envVariables`/`envSecrets` mapping at any depth, a managed name as a key and a reference to one in a
+ * key or a value: Zerops resolves the reference into a variable the application controls, and lifts it into a build.
+ */
+export declare function assertAuthoredManagedDocument(value: AuthoredDocumentValue): void;
+export declare function assertAuthoredManagedInputs(input: {
+    variableNames: readonly string[];
+    secretNames: readonly string[];
+}): void;
+/**
+ * Render the execution descriptor: the source descriptor with `FABRIKA_RELEASE` written as a literal into
+ * the selected setup's `run.envVariables`, so the release travels with the version (ADR-0044). A null
+ * release omits the key. The source descriptor's bytes and digest are untouched.
+ */
+export declare function overlayRelease(contents: string, setup: string | undefined, release: string | null): PreparedZeropsDescriptor;
+export {};

package/types/src/manifest.d.ts

@@ -0,0 +1,206 @@
+import { type AppSchema } from '@fabrika/auth-core';
+import type { JsonValue, ProviderCodec, ProviderDeployInput, ProviderEnvironment } from '@fabrika/provider-contract';
+import { z } from 'zod';
+import { type ZeropsContractRun, type ZeropsDevExecution, type ZeropsLockedExecution, type ZeropsRuntimePackage } from './execution';
+import type { ZeropsAppConfig, ZeropsNamespaceResourceRequirement, ZeropsProxySpec } from './types';
+export declare const FABRIKA_MANIFEST_VERSION = 3;
+export declare const ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES: number;
+export declare const ZEROPS_SERVICE_HOSTNAME_PATTERN: RegExp;
+export interface FabrikaImportDocument {
+    readonly project?: {
+        readonly [key: string]: JsonValue;
+    };
+    readonly services: ReadonlyArray<{
+        readonly [key: string]: JsonValue;
+    }>;
+}
+export interface ZeropsArtifactSourceDescriptor {
+    readonly path: 'zerops.yaml';
+    readonly contents: string;
+    readonly sha256: string;
+}
+export interface FabrikaManifest {
+    manifestVersion: typeof FABRIKA_MANIFEST_VERSION;
+    app: {
+        id: string;
+        env: string;
+        schema?: AppSchema;
+        pipeline: {
+            secrets: string[];
+            vars: string[];
+        };
+    };
+    target: {
+        platform: 'zerops';
+        /** The exact repository-root build descriptor used for this artifact. */
+        sourceDescriptor: ZeropsArtifactSourceDescriptor;
+        /** The canonical document used both for resource claims and the Zerops API payload. */
+        importDocument: FabrikaManifestImportDocument;
+        deployService: string;
+        zeropsSetup?: string;
+        proxy?: ZeropsProxySpec;
+        namespaceResources?: ZeropsNamespaceResourceRequirement[];
+        /** Present for a contract application, whose run section and server build the platform generates. */
+        contract?: ZeropsContractRun;
+        runtimePackages?: ZeropsRuntimePackage[];
+    };
+}
+export interface ManifestExpectation {
+    appId?: string;
+    env?: string;
+}
+export declare const assertFabrikaManifestCoordinates: (app: Pick<FabrikaManifest["app"], "id" | "env">, expected: ManifestExpectation) => void;
+export declare const zeropsArtifactSourceDescriptorSchema: z.ZodObject<{
+    path: z.ZodLiteral<"zerops.yaml">;
+    contents: z.ZodEffects<z.ZodString, string, string>;
+    sha256: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    sha256: string;
+    path: "zerops.yaml";
+    contents: string;
+}, {
+    sha256: string;
+    path: "zerops.yaml";
+    contents: string;
+}>;
+declare const importDocumentSchema: z.ZodEffects<z.ZodObject<{
+    project: z.ZodOptional<z.ZodEffects<z.ZodIntersection<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, unknown>>, z.ZodObject<{
+        envIsolation: z.ZodLiteral<"service">;
+    }, "strip", z.ZodTypeAny, {
+        envIsolation: "service";
+    }, {
+        envIsolation: "service";
+    }>>, Record<string, JsonValue> & {
+        envIsolation: "service";
+    }, Record<string, unknown> & {
+        envIsolation: "service";
+    }>>;
+    services: z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodIntersection<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, unknown>>, z.ZodObject<{
+        hostname: z.ZodString;
+        type: z.ZodString;
+        envIsolation: z.ZodLiteral<"service">;
+        override: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    }, {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    }>>, Record<string, JsonValue> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    }, Record<string, unknown> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    }>, Record<string, JsonValue> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    }, Record<string, unknown> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    }>, Record<string, JsonValue> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    }, Record<string, unknown> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    services: (Record<string, JsonValue> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    })[];
+    project?: (Record<string, JsonValue> & {
+        envIsolation: "service";
+    }) | undefined;
+}, {
+    services: (Record<string, unknown> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    })[];
+    project?: (Record<string, unknown> & {
+        envIsolation: "service";
+    }) | undefined;
+}>, {
+    services: (Record<string, JsonValue> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    })[];
+    project?: (Record<string, JsonValue> & {
+        envIsolation: "service";
+    }) | undefined;
+}, {
+    services: (Record<string, unknown> & {
+        type: string;
+        envIsolation: "service";
+        override: true;
+        hostname: string;
+    })[];
+    project?: (Record<string, unknown> & {
+        envIsolation: "service";
+    }) | undefined;
+}>;
+/** The import document a manifest carries: every service already holds the ADR-0004 invariants. */
+export type FabrikaManifestImportDocument = z.infer<typeof importDocumentSchema>;
+export declare const createZeropsArtifactSourceDescriptor: (contents: string) => Promise<ZeropsArtifactSourceDescriptor>;
+export declare const verifyZeropsArtifactSourceDescriptor: (descriptor: ZeropsArtifactSourceDescriptor) => Promise<void>;
+/** 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 of the application this manifest deploys, or null when it has none. */
+export declare const applicationDatabaseOf: (manifest: FabrikaManifest) => ApplicationDatabaseService | null;
+/**
+ * What the platform renders a contract application's execution descriptor from, or null for any other application.
+ * The manifest is the one this release's `fabrika app build` wrote, so its build checks with this release.
+ */
+export declare const lockedExecutionOf: (manifest: FabrikaManifest) => ZeropsLockedExecution | null;
+/**
+ * What Control lets a provider publish for one environment (`ProviderEnvironment.access`), and, for an environment of
+ * kind `dev`, the commit its bootstrap builds.
+ */
+export type ZeropsAccess = Pick<ProviderEnvironment, 'access'> & {
+    readonly dev?: ZeropsDevExecution;
+};
+/**
+ * The execution descriptor's lock-down at deploy (ADR-0050): Control's approved contract decides it, not the artifact,
+ * so a configuration cannot drop it. Without an approved contract nothing deploys outside a dry run.
+ */
+export declare function lockedExecutionFor(manifest: FabrikaManifest, granted: ZeropsAccess, dryRun: boolean, artifactUpload?: ProviderDeployInput['artifactUpload']): ZeropsLockedExecution | null;
+/** The IAM schema a deploy, cancel or reconcile applies: the approved contract's. `undefined` reconciles nothing. */
+export declare function approvedSchemaOf(granted: ZeropsAccess): AppSchema | undefined;
+export declare const manifestServiceHostnames: (manifest: FabrikaManifest) => string[];
+export declare const renderFabrikaImportYaml: (manifest: FabrikaManifest) => string;
+/** Render the codeless import used before registration has a deploy-service id. */
+export declare const renderFabrikaProvisioningYaml: (manifest: FabrikaManifest) => string;
+export declare function parseFabrikaManifest(value: unknown, expected?: ManifestExpectation): FabrikaManifest;
+export declare function compileFabrikaManifest(config: ZeropsAppConfig, env: string, sourceDescriptor: ZeropsArtifactSourceDescriptor): FabrikaManifest;
+/** Provider artifact codec. Its envelope version and manifest payload version advance independently. */
+export declare const zeropsArtifactCodec: ProviderCodec<FabrikaManifest>;
+/** Hash the original validated artifact, never an interpolated import or execution overlay. */
+export declare function hashFabrikaManifest(manifest: FabrikaManifest): Promise<string>;
+export {};

package/types/src/namespace/claims.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderDeploymentNamespace, ProviderRegistration } from '@fabrika/provider-contract';
+export declare const namespaceResourceClaims: (namespace: ProviderDeploymentNamespace) => string[];
+export declare const registrationResourceClaims: (registration: ProviderRegistration) => string[];