@fabrika/provider-zerops 0.2.0 → 0.3.2

package/src/namespace/claims.ts

@@ -0,0 +1,77 @@
+import type { ProviderDeploymentNamespace, ProviderRegistration } from '@fabrika/provider-contract'
+import { isProxyHost } from '@fabrika/proxy-core/manifest'
+import { assertFabrikaManifestCoordinates, manifestServiceHostnames, zeropsArtifactCodec } from '../manifest'
+import { zeropsSharedServicePrefix } from '../service-names'
+import { decodeEnvelope } from './codec'
+import { ZEROPS_NAMESPACE_POSTGRES_HOSTNAME, ZEROPS_NAMESPACE_PROXY_HOSTNAME } from './constants'
+
+export const namespaceResourceClaims = (namespace: ProviderDeploymentNamespace): string[] => {
+	const target = decodeEnvelope(namespace.target)
+	return [
+		`service:${ZEROPS_NAMESPACE_PROXY_HOSTNAME}`,
+		...(target.postgres === undefined ? [] : [`service:${ZEROPS_NAMESPACE_POSTGRES_HOSTNAME}`]),
+	]
+}
+
+export const registrationResourceClaims = (registration: ProviderRegistration): string[] => {
+	const namespace = registration.environment.namespace
+	if (namespace === undefined) {
+		throw new Error('Zerops registration requires a deployment namespace')
+	}
+	if (
+		namespace.exclusiveAppId !== undefined
+		&& namespace.exclusiveAppId !== registration.app.id
+	) {
+		throw new Error(`Zerops namespace is exclusive to app \`${namespace.exclusiveAppId}\``)
+	}
+	const artifactEnvelope = registration.environment.artifact
+	if (artifactEnvelope.provider !== 'zerops' || artifactEnvelope.version !== zeropsArtifactCodec.version) {
+		throw new Error('Zerops registration artifact envelope is not supported')
+	}
+	const manifest = zeropsArtifactCodec.decode(artifactEnvelope.payload)
+	assertFabrikaManifestCoordinates(manifest.app, {
+		appId: registration.app.id,
+		env: registration.environment.env,
+	})
+	// A proxy target is routed by HOST, so a registration with no domain has nothing the proxy can serve:
+	// refuse it here, where nothing has been created yet, instead of at the first deploy's manifest compile.
+	if (manifest.target.proxy !== undefined) {
+		const domain = registration.environment.domain ?? ''
+		if (domain.trim() === '') {
+			throw new Error(
+				`Zerops proxy target \`${registration.app.id}/${registration.environment.env}\` requires a public domain: `
+					+ `pass --domain with a host this namespace serves (\`namespaces get ${namespace.id}\` lists them)`,
+			)
+		}
+		// One Caddy fronts the whole namespace and its host matcher reads `*` as a wildcard label, so a
+		// pattern here would answer for every sibling app. The manifest parser refuses it either way.
+		if (!isProxyHost(domain.toLowerCase())) {
+			throw new Error(
+				`Zerops proxy target \`${registration.app.id}/${registration.environment.env}\` domain \`${domain}\` is not a literal hostname: `
+					+ 'use dot-separated labels of letters, digits and `-` (no wildcard, no port, no placeholder)',
+			)
+		}
+	}
+	const namespaceClaims = new Set(namespaceResourceClaims(namespace))
+	for (const requirement of manifest.target.namespaceResources ?? []) {
+		if (!namespaceClaims.has(requirement.resourceKey)) {
+			throw new Error(`Zerops namespace does not provide required resource \`${requirement.resourceKey}\``)
+		}
+	}
+	const hostnames = manifestServiceHostnames(manifest)
+	for (const hostname of hostnames) {
+		const key = `service:${hostname}`
+		if (namespaceClaims.has(key)) {
+			throw new Error(`Zerops service hostname \`${hostname}\` is reserved by the namespace`)
+		}
+	}
+	if (namespace.exclusiveAppId === undefined) {
+		const prefix = zeropsSharedServicePrefix(registration.app.id)
+		for (const hostname of hostnames) {
+			if (!hostname.startsWith(prefix) || hostname.length === prefix.length) {
+				throw new Error(`Zerops shared namespace service \`${hostname}\` must use app prefix \`${prefix}\``)
+			}
+		}
+	}
+	return hostnames.map((hostname) => `service:${hostname}`).sort()
+}

package/src/namespace/codec.ts

@@ -0,0 +1,179 @@
+import type {
+	JsonValue,
+	ProviderCodec,
+	ProviderDeploymentNamespace,
+	ProviderEnvelope,
+	ProviderNamespaceMutationInput,
+} from '@fabrika/provider-contract'
+import { z } from 'zod'
+import { commitShaSchema, identifierSchema, rejectExplicitUndefined, repositorySchema, sha256Schema } from '../source/validation'
+import { namespaceProxySourceSchema } from './proxy-source'
+import type { NormalizedZeropsNamespaceTarget, ZeropsNamespaceOptions, ZeropsNamespaceProxySource, ZeropsNamespaceTarget } from './types'
+
+const encodeSource = (source: ZeropsNamespaceProxySource): JsonValue => ({
+	repository: { ...source.repository },
+	commitSha: source.commitSha,
+	descriptor: { ...source.descriptor },
+})
+
+const proxyBuildSchema = z.object({
+	appVersionId: identifierSchema,
+	triggered: z.boolean(),
+	manifestSha256: sha256Schema.optional(),
+}).strict().superRefine(rejectExplicitUndefined)
+
+const proxyDeploymentSchema = z.object({
+	manifestSha256: sha256Schema.optional(),
+	appVersionId: identifierSchema,
+	repository: repositorySchema,
+	commitSha: commitShaSchema,
+	descriptorSha256: sha256Schema,
+}).strict().superRefine(rejectExplicitUndefined)
+
+export const postgresSchema = z.discriminatedUnion('type', [
+	z.object({
+		type: z.literal('postgresql:ha@18'),
+		profile: z.enum(['oltp-staging', 'oltp-production', 'oltp-enterprise', 'olap-production', 'writeheavy-production']).optional(),
+	}),
+	z.object({
+		type: z.literal('postgresql:single@18'),
+		profile: z.enum(['oltp-hobby', 'oltp-staging', 'oltp-production', 'olap-production', 'writeheavy-production']).optional(),
+	}),
+]).transform((value) => {
+	if (value.profile === undefined) delete value.profile
+	return value
+})
+
+const namespaceTargetSchema = z.object({
+	proxyDeployment: proxyDeploymentSchema.optional(),
+	proxySource: namespaceProxySourceSchema,
+	proxyBuild: proxyBuildSchema.optional(),
+	projectName: z.string().min(1).optional(),
+	corePackage: z.enum(['LIGHT', 'SERIOUS']).optional(),
+	publicAccess: z.enum(['custom-domain', 'zerops-subdomain']).optional(),
+	postgres: postgresSchema.optional(),
+	managed: z.boolean().optional(),
+	projectId: z.string().min(1).optional(),
+	proxyServiceId: z.string().min(1).optional(),
+	postgresServiceId: z.string().min(1).optional(),
+	proxyConfigured: z.boolean().optional(),
+	proxyBaselineSequence: z.number().int().min(-1).optional(),
+	proxyAppVersionId: z.string().min(1).optional(),
+	proxyHosts: z.array(z.object({ host: z.string().min(1), port: z.number().int().positive() })).optional(),
+	ready: z.boolean().optional(),
+}).transform((target) => {
+	for (const key of Object.keys(target)) {
+		if (Reflect.get(target, key) === undefined) Reflect.deleteProperty(target, key)
+	}
+	return target
+})
+
+export const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget> = {
+	version: 1,
+	encode: (target) => ({
+		...(target.proxyDeployment === undefined
+			? {}
+			: {
+				proxyDeployment: {
+					appVersionId: target.proxyDeployment.appVersionId,
+					repository: { ...target.proxyDeployment.repository },
+					commitSha: target.proxyDeployment.commitSha,
+					descriptorSha256: target.proxyDeployment.descriptorSha256,
+					...(target.proxyDeployment.manifestSha256 === undefined ? {} : { manifestSha256: target.proxyDeployment.manifestSha256 }),
+				},
+			}),
+		proxySource: encodeSource(target.proxySource),
+		...(target.proxyBuild === undefined ? {} : {
+			proxyBuild: {
+				appVersionId: target.proxyBuild.appVersionId,
+				triggered: target.proxyBuild.triggered,
+				...(target.proxyBuild.manifestSha256 === undefined ? {} : { manifestSha256: target.proxyBuild.manifestSha256 }),
+			},
+		}),
+		...(target.projectName !== undefined ? { projectName: target.projectName } : {}),
+		...(target.corePackage !== undefined ? { corePackage: target.corePackage } : {}),
+		...(target.publicAccess !== undefined ? { publicAccess: target.publicAccess } : {}),
+		...(target.postgres !== undefined
+			? { postgres: { type: target.postgres.type, ...(target.postgres.profile !== undefined ? { profile: target.postgres.profile } : {}) } }
+			: {}),
+		...(target.managed !== undefined ? { managed: target.managed } : {}),
+		...(target.projectId !== undefined ? { projectId: target.projectId } : {}),
+		...(target.proxyServiceId !== undefined ? { proxyServiceId: target.proxyServiceId } : {}),
+		...(target.postgresServiceId !== undefined ? { postgresServiceId: target.postgresServiceId } : {}),
+		...(target.proxyConfigured !== undefined ? { proxyConfigured: target.proxyConfigured } : {}),
+		...(target.proxyBaselineSequence !== undefined ? { proxyBaselineSequence: target.proxyBaselineSequence } : {}),
+		...(target.proxyAppVersionId !== undefined ? { proxyAppVersionId: target.proxyAppVersionId } : {}),
+		...(target.proxyHosts === undefined ? {} : { proxyHosts: target.proxyHosts.map((entry) => ({ host: entry.host, port: entry.port })) }),
+		...(target.ready !== undefined ? { ready: target.ready } : {}),
+	}),
+	decode: (payload) => {
+		const result = namespaceTargetSchema.safeParse(payload)
+		if (!result.success) {
+			const path = result.error.issues[0]?.path ?? []
+			if (path[0] === 'postgres') {
+				if (path[1] === 'type') throw new Error('Zerops namespace PostgreSQL type must be postgresql:ha@18 or postgresql:single@18')
+				throw new Error('Zerops namespace PostgreSQL profile is not supported')
+			}
+			if (path[0] === 'proxyHosts' && path.at(-1) === 'port') throw new Error('Zerops namespace target proxyHosts port must be a positive integer')
+			throw new Error(`Zerops namespace target ${path.join('.')} is invalid`)
+		}
+		return result.data
+	},
+}
+
+export const envelope = (target: ZeropsNamespaceTarget): ProviderEnvelope => ({
+	provider: 'zerops',
+	version: zeropsNamespaceTargetCodec.version,
+	payload: zeropsNamespaceTargetCodec.encode(target),
+})
+
+export const decodeEnvelope = (value: ProviderEnvelope): ZeropsNamespaceTarget => {
+	if (value.provider !== 'zerops') {
+		throw new Error(`namespace belongs to provider "${value.provider}", expected "zerops"`)
+	}
+	if (value.version !== zeropsNamespaceTargetCodec.version) {
+		throw new Error(`namespace schema version ${value.version} is not supported by provider "zerops"`)
+	}
+	return zeropsNamespaceTargetCodec.decode(value.payload)
+}
+
+export const normalizeTarget = (
+	namespace: ProviderDeploymentNamespace,
+	options: ZeropsNamespaceOptions,
+): NormalizedZeropsNamespaceTarget => {
+	if (namespace.id.trim() === '' || namespace.env.trim() === '') {
+		throw new Error('Zerops namespace id and env must be non-empty')
+	}
+	const decoded = decodeEnvelope(namespace.target)
+	return {
+		...decoded,
+		projectName: decoded.projectName ?? namespace.id,
+		corePackage: decoded.corePackage ?? 'LIGHT',
+		publicAccess: decoded.publicAccess ?? 'custom-domain',
+		managed: decoded.managed ?? decoded.projectId === undefined,
+		ready: decoded.ready ?? false,
+	}
+}
+
+export const normalizedNamespace = (
+	namespace: ProviderDeploymentNamespace,
+	options: ZeropsNamespaceOptions,
+): ProviderDeploymentNamespace => ({
+	...namespace,
+	target: envelope(normalizeTarget(namespace, options)),
+})
+
+const withTarget = (
+	namespace: ProviderDeploymentNamespace,
+	target: ZeropsNamespaceTarget,
+): ProviderDeploymentNamespace => ({ ...namespace, target: envelope(target) })
+
+export const checkpoint = async (
+	input: ProviderNamespaceMutationInput,
+	namespace: ProviderDeploymentNamespace,
+	target: ZeropsNamespaceTarget,
+): Promise<ProviderDeploymentNamespace> => {
+	const updated = withTarget(namespace, target)
+	await input.events.checkpoint(updated)
+	return updated
+}

package/src/namespace/constants.ts

@@ -0,0 +1,30 @@
+export const ZEROPS_NAMESPACE_PROXY_HOSTNAME = 'proxy'
+
+export const ZEROPS_NAMESPACE_POSTGRES_HOSTNAME = 'postgres'
+
+export const ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE = 'FABRIKA_IAM_ISSUER'
+
+export const ZEROPS_NAMESPACE_IAM_KEY_VARIABLE = 'FABRIKA_IAM_KEY'
+
+/** The platform-owned variable naming one URL per published HTTP port. READ_ONLY, written by Zerops. */
+export const ZEROPS_NAMESPACE_SUBDOMAIN_VARIABLE = 'zeropsSubdomain'
+
+/**
+ * How an app reaches the namespace-owned PostgreSQL service — port, database and TLS mode NAMED, not
+ * defaulted. Every part settled against a live account, none of it safe to infer:
+ *
+ *   • `${x_connectionTlsString}` is `postgresql://${user}:${password}@${hostname}:${portTls}` — no
+ *     database path. With none, the libpq/postgres.js convention falls back to the USER name.
+ *   • `dbName` and `user` are both literally `db` on EVERY PostgreSQL service, whatever its hostname
+ *     (checked on a service named `wu2db`). So the fallback lands right today — by construction rather
+ *     than by luck, but still by a rule nobody wrote down. `/${x_dbName}` says it out loud.
+ *   • THE TLS PORT, NOT THE DIRECT ONE, and this is the one that changed. `postgresql:single@18`
+ *     speaks TLS on both; `postgresql:ha@18` speaks it ONLY on `portTls` and answers `sslmode=require`
+ *     on the direct port with "Server does not support SSL". A namespace picks `ha` for `prod` and
+ *     `single` everywhere else, so a DSN naming the direct port is one preset away from failing.
+ *   • `portTls` preserves SESSION state on both — same backend pid across statements, `SET SESSION`
+ *     kept, advisory lock held and visible — so the migration runner's session-level lock is safe
+ *     there. It is a TLS endpoint, not the transaction pool the port number suggests.
+ *   • `verify-full` fails (`self signed certificate`), so `require` is the strongest mode available.
+ */
+export const ZEROPS_SHARED_POSTGRES_CONNECTION_STRING = '${postgres_connectionTlsString}/${postgres_dbName}?sslmode=require'

package/src/namespace/errors.ts

@@ -0,0 +1,60 @@
+import { ProviderNamespaceError } from '@fabrika/provider-contract'
+import { ZeropsApiError } from '../api'
+
+/**
+ * Lifecycle codes this provider defines where the platform has none of its own. They are an
+ * operator-facing vocabulary, so they are stable identifiers rather than prose (backlog 72): a
+ * platform code such as `insufficientPermissions` and one of these read the same way downstream.
+ */
+export const ZEROPS_NAMESPACE_CANCELLED = 'namespaceCancelled'
+
+export const ZEROPS_NAMESPACE_LIFECYCLE = 'namespaceLifecycle'
+
+export const ZEROPS_PROXY_DEPLOY_TIMEOUT = 'proxyDeployTimeout'
+
+export const ZEROPS_PROXY_DEPLOY_FAILED = 'proxyDeployFailed'
+
+export const ZEROPS_SUBDOMAIN_NOT_PUBLISHED = 'subdomainNotPublished'
+
+export const namespaceError = (code: string, message: string, retryable: boolean, detail?: string): ProviderNamespaceError =>
+	new ProviderNamespaceError(message, code, retryable, detail)
+
+/**
+ * `apiError` composes `zerops: <label> failed (<status>) — <code>: <server message>`. The half before the
+ * first separator is OURS (a literal label and the status); the half after is the platform's, and it
+ * REPEATS the code, which travels separately. Splitting them keeps the summary safe to show while the
+ * upstream words survive in `detail`, where the control plane redacts them before they are stored or
+ * logged — discarding them is what left three different live failures indistinguishable (backlog 72).
+ *
+ * A `redactDetail: true` call carries the code and nothing else, so it yields no detail at all.
+ */
+const splitApiMessage = (message: string, code: string): { summary: string; detail?: string } => {
+	const at = message.indexOf(' — ')
+	if (at === -1) return { summary: message }
+	const summary = message.slice(0, at)
+	const rest = message.slice(at + 3)
+	if (code === '' || rest === code) return rest === code ? { summary } : { summary, detail: rest }
+	const detail = rest.startsWith(`${code}: `) ? rest.slice(code.length + 2) : rest
+	return detail === '' ? { summary } : { summary, detail }
+}
+
+/** Every namespace lifecycle failure leaves this provider as one typed, coded error. */
+export const asNamespaceError = (cause: unknown, mode: 'provision' | 'reconcile'): ProviderNamespaceError => {
+	if (cause instanceof ProviderNamespaceError) return cause
+	if (cause instanceof ZeropsApiError) {
+		const { summary, detail } = splitApiMessage(cause.message, cause.code)
+		return namespaceError(
+			cause.code === '' ? `zeropsHttp${cause.status}` : cause.code,
+			summary,
+			cause.status === 429 || cause.status >= 500,
+			detail,
+		)
+	}
+	if (cause instanceof Error && cause.name === 'AbortError') {
+		return namespaceError(ZEROPS_NAMESPACE_CANCELLED, `Zerops namespace ${mode} was cancelled`, true)
+	}
+	if (cause instanceof Error) {
+		return namespaceError(ZEROPS_NAMESPACE_LIFECYCLE, cause.message, false)
+	}
+	return namespaceError(ZEROPS_NAMESPACE_LIFECYCLE, `Zerops namespace ${mode} failed`, false)
+}

package/src/namespace/manifest.ts

@@ -0,0 +1,28 @@
+import { decodeEnvelope, type ProviderNamespaceMember } from '@fabrika/provider-contract'
+import type { ProxyManifest } from '@fabrika/proxy-core/manifest'
+import { assertFabrikaManifestCoordinates, zeropsArtifactCodec } from '../manifest'
+
+/** Compile every public member of one deployment namespace into its strict proxy manifest. */
+export function compileNamespaceProxyManifest(namespaceId: string, members: readonly ProviderNamespaceMember[]): ProxyManifest {
+	const apps: ProxyManifest['apps'] = []
+	const ids = new Set<string>()
+	const hosts = new Set<string>()
+	for (const member of members) {
+		const manifest = decodeEnvelope('artifact', 'zerops', member.artifact, zeropsArtifactCodec)
+		assertFabrikaManifestCoordinates(manifest.app, { appId: member.appId, env: member.env })
+		const proxy = manifest.target.proxy
+		if (proxy === undefined) continue
+		if (member.domain === undefined || member.domain === '') {
+			throw new Error(`Zerops proxy target ${member.appId}/${member.env} requires a public domain`)
+		}
+		const host = member.domain.toLowerCase()
+		if (ids.has(member.appId)) throw new Error(`duplicate proxy app id \`${member.appId}\` in deployment namespace ${namespaceId}`)
+		if (hosts.has(host)) throw new Error(`duplicate proxy host \`${host}\` in deployment namespace ${namespaceId}`)
+		ids.add(member.appId)
+		hosts.add(host)
+		// A Zerops public domain is always served over the project's TLS-terminating L7 balancer, so the
+		// browser speaks https even though the proxy itself is reached over plain HTTP (ADR-0022).
+		apps.push({ id: member.appId, hosts: [host], upstream: proxy.upstream, gates: proxy.gates, scheme: 'https' })
+	}
+	return { apps }
+}

package/src/namespace/operator.ts

@@ -0,0 +1,151 @@
+import type {
+	JsonValue,
+	ProviderDeploymentNamespace,
+	ProviderNamespaceFact,
+	ProviderNamespaceOperator,
+	ProviderNamespacePlanInput,
+	ProviderNamespacePresentation,
+	ProviderNamespacePreset,
+} from '@fabrika/provider-contract'
+import { z } from 'zod'
+import { decodeEnvelope, envelope, postgresSchema } from './codec'
+import { zeropsNamespacePreset } from './topology'
+import type { ZeropsNamespaceOperatorOptions, ZeropsNamespacePlanOptions, ZeropsNamespaceTarget } from './types'
+
+const ZEROPS_NAMESPACE_PRESETS: readonly ProviderNamespacePreset[] = [
+	{
+		id: 'cheap',
+		label: 'Cheap',
+		description: 'Several apps share one project, proxy, and namespace-owned PostgreSQL service.',
+		requiresExclusiveApp: false,
+	},
+	{
+		id: 'mid',
+		label: 'Mid',
+		description: 'Several apps share one project and proxy; each app owns its prefixed database services.',
+		requiresExclusiveApp: false,
+	},
+	{
+		id: 'full',
+		label: 'Full',
+		description: 'One project and proxy are reserved for exactly one app.',
+		requiresExclusiveApp: true,
+	},
+]
+
+const planOptionsSchema = z.object({
+	projectName: z.string().min(1).optional(),
+	corePackage: z.enum(['LIGHT', 'SERIOUS']).optional(),
+	publicAccess: z.enum(['custom-domain', 'zerops-subdomain']).optional(),
+	postgres: postgresSchema.optional(),
+}).strict().transform((options) => {
+	for (const key of Object.keys(options)) {
+		if (Reflect.get(options, key) === undefined) Reflect.deleteProperty(options, key)
+	}
+	return options
+})
+const parsePlanOptions = (value: JsonValue | undefined): ZeropsNamespacePlanOptions => {
+	const result = planOptionsSchema.safeParse(value === undefined ? {} : value)
+	if (!result.success) {
+		const issue = result.error.issues[0]
+		if (issue?.code === 'unrecognized_keys') throw new Error(`Zerops namespace plan option ${issue.keys[0]} is not supported`)
+		throw new Error(`Zerops namespace plan ${issue?.path.join('.') ?? 'options'} is not supported`)
+	}
+	return result.data
+}
+
+const namespacePresentation = (
+	namespace: ProviderDeploymentNamespace,
+	target: ZeropsNamespaceTarget,
+): ProviderNamespacePresentation => {
+	const preset = target.postgres !== undefined ? 'cheap' : namespace.exclusiveAppId === undefined ? 'mid' : 'full'
+	const projectName = target.projectName ?? namespace.id
+	const corePackage = target.corePackage ?? 'LIGHT'
+	const publicAccess = target.publicAccess ?? 'custom-domain'
+	const postgres = target.postgres === undefined
+		? 'App-owned database services'
+		: `Shared ${target.postgres.type}${target.postgres.profile === undefined ? '' : ` (${target.postgres.profile})`}`
+	// Only a published subdomain namespace knows its own hosts; custom domains are bound out of band, so
+	// the provider names none and an operator reads them where they were bound.
+	const hosts = publicAccess === 'zerops-subdomain' && target.ready === true ? target.proxyHosts ?? [] : []
+	const instructions = [
+		...(publicAccess === 'custom-domain'
+			? [`Bind each application domain to the \`proxy\` service in Zerops project \`${projectName}\`; keep every app service private.`]
+			: ['Use the proxy Zerops subdomain only for non-production access; app services must remain private.']),
+		...(hosts.length === 0 ? [] : ['Register a proxy-target environment with one of the hosts below as its domain; each host serves one app.']),
+		...(target.postgres === undefined
+			? []
+			: ['Every app consuming the shared PostgreSQL binding shares its physical service and provider-issued credential.']),
+	]
+	// The project is the one fact that names a LIVE resource: it exists at the provider, it outlives the
+	// namespace row, and removal does not delete it (ADR-0034). Marked only once it actually exists.
+	const project: ProviderNamespaceFact = target.projectId === undefined
+		? { label: 'Project', value: projectName }
+		: { label: 'Project', value: `${projectName} (${target.projectId})`, resource: true }
+	return {
+		preset,
+		title: `${ZEROPS_NAMESPACE_PRESETS.find((candidate) => candidate.id === preset)?.label ?? preset} namespace`,
+		facts: [
+			{
+				label: 'Proxy source',
+				value:
+					`${target.proxySource.repository.owner}/${target.proxySource.repository.name}@${target.proxySource.commitSha} (zerops.yaml sha256:${target.proxySource.descriptor.sha256})`,
+			},
+			project,
+			{ label: 'Environment', value: namespace.env },
+			{ label: 'Core package', value: corePackage },
+			{ label: 'Placement', value: namespace.exclusiveAppId === undefined ? 'Shared' : `Exclusive to ${namespace.exclusiveAppId}` },
+			{ label: 'PostgreSQL', value: postgres },
+			{ label: 'Public access', value: publicAccess },
+		],
+		instructions,
+		...(hosts.length === 0 ? {} : { hosts }),
+	}
+}
+
+/** Build the provider-owned namespace planning surface without any network collaborators. */
+export const createZeropsNamespaceOperator = (
+	options: ZeropsNamespaceOperatorOptions,
+): ProviderNamespaceOperator => {
+	return {
+		presets: ZEROPS_NAMESPACE_PRESETS,
+		plan(input: ProviderNamespacePlanInput) {
+			if (input.id.trim() === '' || input.env.trim() === '') {
+				throw new Error('Zerops namespace plan id and env must be non-empty')
+			}
+			if (input.preset !== 'cheap' && input.preset !== 'mid' && input.preset !== 'full') {
+				throw new Error(`Zerops namespace preset ${input.preset} is not supported`)
+			}
+			const exclusiveAppId = input.exclusiveAppId?.trim()
+			if (input.preset === 'full' && (exclusiveAppId === undefined || exclusiveAppId === '')) {
+				throw new Error('Zerops full namespace plan requires exclusiveAppId')
+			}
+			if (input.preset !== 'full' && exclusiveAppId !== undefined) {
+				throw new Error(`Zerops ${input.preset} namespace plan cannot reserve an exclusive app`)
+			}
+			const planOptions = parsePlanOptions(input.options)
+			if (input.preset !== 'cheap' && planOptions.postgres !== undefined) {
+				throw new Error(`Zerops ${input.preset} namespace plan cannot own PostgreSQL`)
+			}
+			const target = zeropsNamespacePreset({
+				preset: input.preset,
+				env: input.env,
+				projectName: planOptions.projectName ?? input.id,
+				proxySource: options.proxySource,
+				...(planOptions.corePackage === undefined ? {} : { corePackage: planOptions.corePackage }),
+				...(planOptions.publicAccess === undefined ? {} : { publicAccess: planOptions.publicAccess }),
+				...(planOptions.postgres === undefined ? {} : { postgres: planOptions.postgres }),
+			})
+			const namespace: ProviderDeploymentNamespace = {
+				id: input.id,
+				env: input.env,
+				...(exclusiveAppId === undefined ? {} : { exclusiveAppId }),
+				target: envelope(target),
+			}
+			return { namespace, presentation: namespacePresentation(namespace, target) }
+		},
+		present(namespace) {
+			return namespacePresentation(namespace, decodeEnvelope(namespace.target))
+		},
+	}
+}