@fabrika/provider-zerops 0.0.25 → 0.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.0.25",
+	"version": "0.0.26",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -32,9 +32,9 @@
 		"gen:schema": "bun scripts/generate-zerops-types.ts"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.0.25",
-		"@fabrika/auth-core": "^0.0.25",
-		"@fabrika/provider-contract": "^0.0.25",
-		"@fabrika/proxy-contract": "^0.0.25"
+		"@fabrika/auth": "^0.0.26",
+		"@fabrika/auth-core": "^0.0.26",
+		"@fabrika/provider-contract": "^0.0.26",
+		"@fabrika/proxy-contract": "^0.0.26"
 	}
 }

package/src/api.ts

@@ -258,7 +258,7 @@ export interface ZeropsServiceEnv {
 
 /**
  * A short-lived grant for the project's LOG service. VERIFIED: `ResponseProjectLog` — the field names and
- * types are exactly these. What is NOT verified is what the URLs speak; see `readBuildLog`.
+ * types are exactly these. What the URLs speak was measured separately; see `readBuildLog`.
  */
 export interface ZeropsLogAccess {
 	url: string
@@ -271,10 +271,14 @@ export interface ZeropsLogAccess {
 	expiration: string
 }
 
+/** The RFC3339 stamp the plaintext log window puts first on every line. Anchored so a bare year cannot pass. */
+const LOG_LINE_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+
 /** One relayed build/runtime log line. Shape is fabrika's, not the platform's. */
 export interface ZeropsLogLine {
-	/** ISO timestamp when Zerops recorded the line, when it supplied one. */
+	/** RFC3339 stamp Zerops put at the head of the line, when the line carried one. */
 	timestamp?: string
+	/** The line as the log service wrote it, timestamp and tag included. */
 	message: string
 }
 
@@ -457,8 +461,9 @@ export interface ZeropsApi {
 	 * Every environment variable of ONE service, each with the record id `deleteServiceEnv` takes.
 	 * VERIFIED: `GET /service-stack/{id}/env` (`{ items }`).
 	 *
-	 * NOT `GET /service-stack/{id}/user-data`, which answers `400 serviceStackNotFound` on every
-	 * service, deployed or not — see `docs/reference/zerops-platform.md`. The `/env` reading omits
+	 * NOT `GET /service-stack/{id}/user-data`: it answers a list now (2026-08-21), but `/env` is the
+	 * endpoint whose record ids `PUT`/`DELETE /user-data/{id}` take, and the list's paging terms were
+	 * never verified — see `docs/reference/zerops-platform.md`. The `/env` reading omits
 	 * variables the service's own `zerops.yaml` declares (`type: ENV`); fabrika never writes those.
 	 * The OpenAPI publishes no lookup/pagination terms and live probes found query terms ignored, so the
 	 * implementation reads one full response under a byte bound rather than imposing an entry-count cap.
@@ -548,17 +553,42 @@ export interface ZeropsApi {
 	getLogAccess(input: { projectId: string; signal: AbortSignal }): Promise<ZeropsLogAccess>
 
 	/**
-	 * UNVERIFIED — THE ONE SHAPE NOBODY COULD CHECK. `GET /project/{id}/log` hands back URLs to a
-	 * SEPARATE log service, and that service's request/response contract appears in no published document
-	 * (it is not in the OpenAPI file, which stops at the grant). The default implementation's reading is:
-	 * GET `urlPlain` with the grant as a bearer, one plain-text line per log record, `limit`/`from` as
-	 * query params. Treat that as a guess.
+	 * One window of the project's log, narrowed to ONE app version.
+	 *
+	 * VERIFIED 2026-08-21 by measurement, not by document: the OpenAPI file stops at the grant, so the
+	 * separate log service was read against a live project. `urlPlain` answers one
+	 * `<RFC3339 timestamp> <tag> <message>` line per record and accepts `serviceStackId`, `limit`, `tags`
+	 * and `desc`; `from` and unknown terms are accepted and silently ignored, so nothing may depend on them.
+	 *
+	 * ORDERING, also measured: `limit=N` without `desc` returns the NEWEST N records in ASCENDING timestamp
+	 * order (`limit=3` against a log starting 15:50 answered 17:00:00, 17:00:00, 17:15:00), and `desc=1`
+	 * returns the same newest N, newest first. So `desc` is needed neither for the `since` cut nor for a
+	 * build longer than the limit: each poll re-reads the newest window and the caller's dedupe streams it.
 	 *
-	 * BECAUSE it is a guess, the driver treats a failure here as non-fatal: log relay degrades to "no
-	 * lines" and the deploy still succeeds or fails on `/app-version` status alone. An unverified endpoint
-	 * must never be able to fail a deploy.
+	 * A version's BUILD lines carry the tag `zbuilder@<appVersionId>` and are produced on a separate
+	 * builder stack, so they are selected by `tags` ALONE — combining that tag with the runtime
+	 * `serviceStackId` matches nothing. RUNTIME lines carry no version marker at all and the runtime
+	 * service's window mixes every version that ever ran, so they are selected by `serviceStackId` and cut
+	 * at `since` (the version's `build.pipelineStart`). Without `since` no runtime line is read: a line
+	 * from an earlier version is worse in a run log than a missing one. The cut is by TIME, not identity —
+	 * the outgoing container keeps logging until it is replaced, so its lines stamped after `since` still
+	 * pass, and only the earlier version's older history is excluded.
+	 *
+	 * The two windows are read INDEPENDENTLY: one failing must not discard what the other returned, and only
+	 * a failure of every window attempted is raised. The driver then treats that as non-fatal anyway — log
+	 * relay degrades to "no lines" and the deploy succeeds or fails on `/app-version` status alone. A log
+	 * service must never be able to fail a deploy.
 	 */
-	readBuildLog(input: { access: ZeropsLogAccess; serviceId: string; limit?: number; signal: AbortSignal }): Promise<ZeropsLogLine[]>
+	readBuildLog(input: {
+		access: ZeropsLogAccess
+		serviceId: string
+		/** Select this version's build lines by their `zbuilder@` tag; without it no build line is read. */
+		appVersionId?: string
+		/** RFC3339 lower bound for runtime lines, normally `build.pipelineStart`; without it none are read. */
+		since?: string
+		limit?: number
+		signal: AbortSignal
+	}): Promise<ZeropsLogLine[]>
 }
 
 // ── default (real) implementation ───────────────────────────────────────────────
@@ -1245,20 +1275,47 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 			}
 		},
 
-		readBuildLog: async ({ access, serviceId, limit, signal }) => {
-			// UNVERIFIED (see the interface): this is a best reading of an undocumented log service, not a
-			// contract. It is written so a wrong guess degrades to "no lines" instead of failing a deploy.
+		readBuildLog: async ({ access, serviceId, appVersionId, since, limit, signal }) => {
 			if (access.urlPlain === '') {
 				return []
 			}
 			const separator = access.urlPlain.includes('?') ? '&' : '?'
-			const url = `${access.urlPlain}${separator}serviceStackId=${encodeURIComponent(serviceId)}&limit=${limit ?? 200}`
-			const response = await doFetch(url, { headers: { authorization: `Bearer ${access.accessToken}` }, signal })
-			if (!response.ok) {
-				throw new Error(`zerops: read build log failed (${response.status})`)
+			const readWindow = async (terms: string): Promise<{ lines: ZeropsLogLine[]; error: unknown }> => {
+				try {
+					const url = `${access.urlPlain}${separator}${terms}&limit=${limit ?? 200}`
+					const response = await doFetch(url, { headers: { authorization: `Bearer ${access.accessToken}` }, signal })
+					if (!response.ok) {
+						throw new Error(`zerops: read build log failed (${response.status})`)
+					}
+					const text = await response.text()
+					const lines = text.split('\n').filter((line) => line.trim() !== '').map((line) => {
+						const head = line.slice(0, Math.max(line.indexOf(' '), 0))
+						return LOG_LINE_TIMESTAMP.test(head) ? { timestamp: head, message: line } : { message: line }
+					})
+					return { lines, error: undefined }
+				} catch (error) {
+					return { lines: [], error }
+				}
+			}
+			// Selected by tag alone: the build runs on a builder stack, so pairing the tag with the runtime
+			// service id matches nothing (see the interface).
+			const build = appVersionId === undefined ? undefined : await readWindow(`tags=${encodeURIComponent(`zbuilder@${appVersionId}`)}`)
+			const runtime = since === undefined ? undefined : await readWindow(`serviceStackId=${encodeURIComponent(serviceId)}`)
+			const attempted = [build, runtime].filter((result) => result !== undefined)
+			if (attempted.length === 0) {
+				return []
+			}
+			// Independent windows: only a failure of every one attempted is worth raising.
+			const failure = attempted.find((result) => result.error !== undefined)
+			if (failure !== undefined && attempted.every((result) => result.error !== undefined)) {
+				throw failure.error
 			}
-			const text = await response.text()
-			return text.split('\n').filter((line) => line.trim() !== '').map((line) => ({ message: line }))
+			const boundary = since === undefined ? Number.NaN : Date.parse(since)
+			// The runtime window carries every version that ever ran, so a line the driver cannot date is dropped.
+			const runtimeLines = runtime === undefined || Number.isNaN(boundary)
+				? runtime?.lines ?? []
+				: runtime.lines.filter((line) => line.timestamp !== undefined && Date.parse(line.timestamp) >= boundary)
+			return [...build?.lines ?? [], ...runtimeLines]
 		},
 	}
 }

package/src/namespace.ts

@@ -6,6 +6,7 @@ import {
 	type ProviderNamespaceCapabilities,
 	ProviderNamespaceError,
 	type ProviderNamespaceFact,
+	type ProviderNamespaceHost,
 	type ProviderNamespaceMutationInput,
 	type ProviderNamespaceOperator,
 	type ProviderNamespacePlanInput,
@@ -35,6 +36,8 @@ 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:
@@ -91,6 +94,8 @@ export interface ZeropsNamespaceTarget {
 	readonly proxyConfigured?: boolean
 	readonly proxyBaselineSequence?: number
 	readonly proxyAppVersionId?: string
+	/** The hosts the published proxy answers on, recorded once so a namespace read needs no platform call. */
+	readonly proxyHosts?: readonly ProviderNamespaceHost[]
 	readonly ready?: boolean
 }
 
@@ -221,6 +226,54 @@ const parsePostgres = (payload: JsonValue): ZeropsNamespacePostgres | undefined
 	return profile === undefined ? { type } : { type, profile }
 }
 
+const parseProxyHosts = (payload: JsonValue): readonly ProviderNamespaceHost[] | undefined => {
+	const value = property(payload, 'proxyHosts')
+	if (value === undefined) return undefined
+	if (!Array.isArray(value)) {
+		throw new Error('Zerops namespace target proxyHosts must be an array')
+	}
+	return value.map((entry) => {
+		if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+			throw new Error('Zerops namespace target proxyHosts entry must be an object')
+		}
+		const host = property(entry, 'host')
+		const port = property(entry, 'port')
+		if (typeof host !== 'string' || host === '') {
+			throw new Error('Zerops namespace target proxyHosts host must be a non-empty string')
+		}
+		if (typeof port !== 'number' || !Number.isInteger(port) || port <= 0) {
+			throw new Error('Zerops namespace target proxyHosts port must be a positive integer')
+		}
+		return { host, port }
+	})
+}
+
+/**
+ * One host per published HTTP port, out of the newline-separated URLs the platform writes.
+ *
+ * The form is `<hostname>-<hash>-<port>.<region>.zerops.app` (e.g. `proxy-2ec8-8080`). Read as URLs
+ * rather than split on `-`, so a hostname whose own first label ends in digits cannot be misread; a line
+ * that is not a URL, or whose first label carries no trailing port — the single portless line a proxy
+ * that has never deployed publishes — is skipped rather than guessed at.
+ */
+const parseZeropsProxyHosts = (value: string): ProviderNamespaceHost[] => {
+	const hosts: ProviderNamespaceHost[] = []
+	for (const line of value.split('\n')) {
+		const trimmed = line.trim()
+		if (trimmed === '') continue
+		let hostname: string
+		try {
+			hostname = new URL(trimmed).hostname
+		} catch {
+			continue
+		}
+		const port = /-(\d+)$/.exec(hostname.split('.')[0] ?? '')?.[1]
+		if (port === undefined) continue
+		hosts.push({ host: hostname, port: Number.parseInt(port, 10) })
+	}
+	return hosts.sort((left, right) => left.port - right.port)
+}
+
 export const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget> = {
 	version: 1,
 	encode: (target) => ({
@@ -238,6 +291,7 @@ export const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget> =
 		...(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) => {
@@ -272,6 +326,7 @@ export const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget> =
 			...(optionalString(payload, 'proxyAppVersionId') !== undefined
 				? { proxyAppVersionId: optionalString(payload, 'proxyAppVersionId') }
 				: {}),
+			...(parseProxyHosts(payload) !== undefined ? { proxyHosts: parseProxyHosts(payload) } : {}),
 			...(optionalBoolean(payload, 'ready') !== undefined ? { ready: optionalBoolean(payload, 'ready') } : {}),
 		}
 	},
@@ -320,6 +375,14 @@ const registrationResourceClaims = (registration: ProviderRegistration): string[
 		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 && (registration.environment.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)`,
+		)
+	}
 	const namespaceClaims = new Set(namespaceResourceClaims(namespace))
 	for (const requirement of manifest.target.namespaceResources ?? []) {
 		if (!namespaceClaims.has(requirement.resourceKey)) {
@@ -503,10 +566,14 @@ const namespacePresentation = (
 	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.']),
@@ -528,6 +595,7 @@ const namespacePresentation = (
 			{ label: 'Public access', value: publicAccess },
 		],
 		instructions,
+		...(hosts.length === 0 ? {} : { hosts }),
 	}
 }
 
@@ -832,6 +900,38 @@ const ensureProxyConfiguration = async (
 	return deployRequired
 }
 
+/**
+ * The hosts the proxy publishes, off the platform-owned `zeropsSubdomain` variable.
+ *
+ * Read through the same `/env` listing every other namespace variable uses, and read AFTER the proxy is
+ * published: the variable names a host per DEPLOYED HTTP port, so a proxy that never deployed names none.
+ * Recording the answer in the target is what keeps `namespaces get` a database read.
+ */
+const readProxyHosts = async (
+	namespace: ProviderDeploymentNamespace,
+	target: NormalizedZeropsNamespaceTarget,
+	options: ZeropsNamespaceOptions,
+	signal: AbortSignal,
+): Promise<readonly ProviderNamespaceHost[]> => {
+	const proxyServiceId = target.proxyServiceId
+	if (proxyServiceId === undefined) {
+		throw new Error('Zerops namespace has no proxy service id')
+	}
+	try {
+		const variables = await options.api.listServiceEnv({ serviceId: proxyServiceId, signal })
+		const subdomains = variables.find((variable) => variable.key === ZEROPS_NAMESPACE_SUBDOMAIN_VARIABLE)
+		return subdomains === undefined ? [] : parseZeropsProxyHosts(subdomains.content)
+	} catch {
+		// A host listing is a convenience; the proxy is already built, deployed and published. Failing the
+		// namespace over it would report a placement that WORKS as broken. Never the cause: it can carry
+		// upstream text this provider has not redacted.
+		console.warn(
+			`Zerops namespace ${namespace.id}: reading the published proxy hosts failed; the placement is ready and lists none until its next reconcile`,
+		)
+		return []
+	}
+}
+
 const latestAfterBaseline = async (
 	target: NormalizedZeropsNamespaceTarget,
 	options: ZeropsNamespaceOptions,
@@ -1125,10 +1225,14 @@ const runNamespaceMutation = async (
 	if (target.publicAccess === 'zerops-subdomain') {
 		await ensureSubdomainAccess(target, options, input.signal)
 	}
+	const proxyHosts = target.publicAccess === 'zerops-subdomain' ? await readProxyHosts(namespace, target, options, input.signal) : []
 	target = {
 		...target,
 		proxyBaselineSequence: undefined,
 		proxyAppVersionId: undefined,
+		// Cleared when the proxy publishes none and on a custom-domain namespace, so the record never
+		// outlives what it describes.
+		proxyHosts: proxyHosts.length === 0 ? undefined : proxyHosts,
 		ready: true,
 	}
 	return checkpoint(input, namespace, target)

package/src/provider.ts

@@ -170,23 +170,41 @@ const cleanupPreTriggerVersion = async (env: StepEnv, source: ZeropsRuntimeSourc
 }
 
 /**
- * Relay whatever build log Zerops will give us into the run's progress sink.
+ * Relay ONE app version's build log into the run's progress sink.
  *
- * Deliberately FAILURE-TOLERANT: the log service's protocol is the one shape in this driver nobody could
- * verify against a document (see `ZeropsApi.readBuildLog`). An unverified endpoint must never be able to
- * fail a deploy, so a broken guess degrades to "no lines relayed" and the run still succeeds or fails on
- * the platform's process and app-version statuses.
+ * Scoped to the version being deployed: the runtime service's log window mixes every version that ever ran
+ * on it, so an unscoped read stamps a run's log with lines from earlier releases. `appVersionId` selects
+ * the build lines and `since` — the version's pipeline start — cuts the runtime ones
+ * (see `ZeropsApi.readBuildLog`). Before the platform reports a pipeline start there is nothing to cut
+ * against, so no runtime line is relayed yet. The cut is by time, so the OUTGOING container's own lines
+ * still arrive until it is replaced; what it removes is every earlier version's history.
+ *
+ * Deliberately FAILURE-TOLERANT: a log service must never be able to fail a deploy, so an error degrades
+ * to "no lines relayed" and the run still succeeds or fails on the platform's process and app-version
+ * statuses.
  *
  * Relay is pull-based (ADR-0003), so each poll re-reads a window that overlaps the last one; `seen` keeps
  * the run log from repeating itself. Two genuinely identical lines with no timestamp collapse into one —
  * an acceptable trade for not printing the same window every three seconds.
  */
-const relayLog = async (env: StepEnv, access: ZeropsLogAccess | null, seen: Set<string>): Promise<void> => {
+const relayLog = async (
+	env: StepEnv,
+	access: ZeropsLogAccess | null,
+	seen: Set<string>,
+	appVersionId: string,
+	since: string | undefined,
+): Promise<void> => {
 	if (access === null) {
 		return
 	}
 	try {
-		const lines = await env.zerops.api.readBuildLog({ access, serviceId: env.run.target.serviceId, signal: env.signal })
+		const lines = await env.zerops.api.readBuildLog({
+			access,
+			serviceId: env.run.target.serviceId,
+			appVersionId,
+			...(since === undefined ? {} : { since }),
+			signal: env.signal,
+		})
 		for (const line of lines) {
 			const key = `${line.timestamp ?? ''}\u0000${line.message}`
 			if (seen.has(key)) {
@@ -248,7 +266,7 @@ const awaitVersion = async (env: StepEnv, appVersionId: string, processId: strin
 			log(`  ${appVersionId}: ${version.status ?? 'unknown'}`)
 			previous = version.status
 		}
-		await relayLog(env, access, seen)
+		await relayLog(env, access, seen, appVersionId, version.build?.pipelineStart)
 
 		if (process?.status !== undefined && ZEROPS_PROCESS_TERMINAL.has(process.status) && process.status !== ZEROPS_PROCESS_FINISHED) {
 			throw new Error(