@fabrika/operations-contract 0.2.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/operations-contract",
-	"version": "0.2.0",
+	"version": "0.3.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -59,6 +59,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@fabrika/app": "^0.2.0"
+		"zod": "^3.25.76",
+		"@fabrika/app": "^0.3.2"
 	}
 }

package/src/catalog.ts

@@ -1,73 +1,59 @@
-/** Versioned private Control → Operations source-catalog protocol. */
+/** Private Control → Operations source-catalog protocol; both services ship together. */
 
-export const OPERATIONS_CATALOG_PROTOCOL_VERSION = 2
 export const DEFAULT_OPERATIONS_SERVICE_KEY = 'default'
 
-export interface OperationsSourceCoordinateV1 {
+export interface OperationsSourceCoordinate {
 	appId: string
 	environment: string
 	/** Omitted by Control while an app environment has only its default service. */
 	serviceKey?: string
 }
 
-export interface CanonicalOperationsSourceCoordinateV1 {
+export interface CanonicalOperationsSourceCoordinate {
 	appId: string
 	environment: string
 	serviceKey: string
 }
 
-export interface OperationsCatalogSourceV1 {
-	coordinate: OperationsSourceCoordinateV1
-	displayName: string
-	/** Canonical externally reachable origin when Control owns one; null when it does not. */
-	publicOrigin?: string | null
-}
-
-export interface CanonicalOperationsCatalogSourceV1 {
-	coordinate: CanonicalOperationsSourceCoordinateV1
-	displayName: string
-	publicOrigin: string | null
-}
-
 /** Caller-owned write credential transported only over the private catalog channel. */
-export interface OperationsCatalogIngestCredentialV2 {
+export interface OperationsCatalogIngestCredential {
 	id: string
 	publicKey: string
 }
 
-export interface OperationsCatalogSourceV2 extends OperationsCatalogSourceV1 {
-	ingestCredential: OperationsCatalogIngestCredentialV2
+export interface OperationsCatalogSource {
+	coordinate: OperationsSourceCoordinate
+	displayName: string
+	/** Canonical externally reachable origin when Control owns one; null when it does not. */
+	publicOrigin?: string | null
+	ingestCredential: OperationsCatalogIngestCredential
 }
 
-export interface CanonicalOperationsCatalogSourceV2 extends CanonicalOperationsCatalogSourceV1 {
-	ingestCredential: OperationsCatalogIngestCredentialV2
+export interface CanonicalOperationsCatalogSource {
+	coordinate: CanonicalOperationsSourceCoordinate
+	displayName: string
+	publicOrigin: string | null
+	ingestCredential: OperationsCatalogIngestCredential
 }
 
-export interface OperationsCatalogReconcileRequestV2 {
-	protocolVersion: typeof OPERATIONS_CATALOG_PROTOCOL_VERSION
+export interface OperationsCatalogReconcileRequest {
 	revision: number
 	snapshotHash: string
-	sources: OperationsCatalogSourceV2[]
+	sources: OperationsCatalogSource[]
 }
 
 export type OperationsCatalogReconcileOutcome = 'applied' | 'unchanged' | 'stale'
 
-export interface OperationsCatalogIngestResultV2 {
-	coordinate: CanonicalOperationsSourceCoordinateV1
+export interface OperationsCatalogIngestResult {
+	coordinate: CanonicalOperationsSourceCoordinate
 	credentialId: string
 	ingestProjectId: string
 }
 
-export interface OperationsCatalogReconcileResponseV2 {
-	protocolVersion: typeof OPERATIONS_CATALOG_PROTOCOL_VERSION
+export interface OperationsCatalogReconcileResponse {
 	revision: number
 	outcome: OperationsCatalogReconcileOutcome
-	created: number
-	updated: number
-	disabled: number
-	reenabled: number
-	unchanged: number
-	ingest: OperationsCatalogIngestResultV2[]
+	ingest: OperationsCatalogIngestResult[]
 }
 
 export function canonicalOperationsServiceKey(serviceKey: string | undefined): string {
@@ -75,8 +61,8 @@ export function canonicalOperationsServiceKey(serviceKey: string | undefined): s
 }
 
 export function canonicalOperationsCatalogSources(
-	sources: readonly OperationsCatalogSourceV2[],
-): CanonicalOperationsCatalogSourceV2[] {
+	sources: readonly OperationsCatalogSource[],
+): CanonicalOperationsCatalogSource[] {
 	return sources.map((source) => ({
 		coordinate: {
 			appId: source.coordinate.appId,
@@ -96,7 +82,7 @@ export function canonicalOperationsCatalogSources(
 }
 
 /** Hash the canonical source array only; revision is transport ordering, not catalog content. */
-export async function operationsCatalogSnapshotHash(sources: readonly OperationsCatalogSourceV2[]): Promise<string> {
+export async function operationsCatalogSnapshotHash(sources: readonly OperationsCatalogSource[]): Promise<string> {
 	const bytes = new TextEncoder().encode(JSON.stringify(canonicalOperationsCatalogSources(sources)))
 	const digest = await crypto.subtle.digest('SHA-256', bytes)
 	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')

package/src/index.ts

@@ -4,21 +4,18 @@ export {
 	canonicalOperationsCatalogSources,
 	canonicalOperationsServiceKey,
 	DEFAULT_OPERATIONS_SERVICE_KEY,
-	OPERATIONS_CATALOG_PROTOCOL_VERSION,
 	operationsCatalogSnapshotHash,
 } from './catalog.js'
 export type {
-	CanonicalOperationsCatalogSourceV1,
-	CanonicalOperationsCatalogSourceV2,
-	CanonicalOperationsSourceCoordinateV1,
-	OperationsCatalogIngestCredentialV2,
-	OperationsCatalogIngestResultV2,
+	CanonicalOperationsCatalogSource,
+	CanonicalOperationsSourceCoordinate,
+	OperationsCatalogIngestCredential,
+	OperationsCatalogIngestResult,
 	OperationsCatalogReconcileOutcome,
-	OperationsCatalogReconcileRequestV2,
-	OperationsCatalogReconcileResponseV2,
-	OperationsCatalogSourceV1,
-	OperationsCatalogSourceV2,
-	OperationsSourceCoordinateV1,
+	OperationsCatalogReconcileRequest,
+	OperationsCatalogReconcileResponse,
+	OperationsCatalogSource,
+	OperationsSourceCoordinate,
 } from './catalog.js'
 export {
 	buildOperationsDsn,
@@ -98,7 +95,6 @@ export {
 	FABRIKA_RELEASE,
 	normalizeOperationsCommit,
 	OPERATIONS_ARTIFACT_HEADERS,
-	OPERATIONS_RELEASE_PROTOCOL_VERSION,
 	OPERATIONS_RELEASE_RECONCILE_PATH,
 	OPERATIONS_SOURCE_MAP_UPLOAD_PATH,
 	operationsReleaseName,
@@ -107,14 +103,14 @@ export {
 export type {
 	OperationsArtifactState,
 	OperationsArtifactUploadConfiguration,
-	OperationsArtifactUploadCredentialV1,
-	OperationsReleaseAvailabilityV1,
-	OperationsReleaseCoordinateV1,
+	OperationsArtifactUploadCredential,
+	OperationsReleaseAvailability,
+	OperationsReleaseCoordinate,
 	OperationsReleaseOutcome,
 	OperationsReleasePhase,
 	OperationsReleaseReconcileOutcome,
-	OperationsReleaseReconcileRequestV1,
-	OperationsReleaseReconcileResponseV1,
+	OperationsReleaseReconcileRequest,
+	OperationsReleaseReconcileResponse,
 	OperationsReleaseUnavailableReason,
 } from './releases.js'
 export type { OperationsIssueQuery, OperationsReleaseQuery, OperationsRpcContract } from './rpc.js'

package/src/release-schemas.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod'
+
+export const operationsReleaseCoordinateSchema = z.object({
+	appId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/),
+	environment: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/),
+	serviceKey: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,62}$/).optional(),
+}).transform(({ appId, environment, serviceKey }) => ({ appId, environment, ...(serviceKey === undefined ? {} : { serviceKey }) }))
+
+export const operationsReleaseAvailabilitySchema = z.discriminatedUnion('kind', [
+	z.object({
+		kind: z.literal('available'),
+		name: z.string().max(512),
+		commitSha: z.string().toLowerCase().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/),
+	}),
+	z.object({ kind: z.literal('unavailable'), reason: z.enum(['dry_run', 'missing_commit']) }),
+])
+
+export const operationsArtifactUploadCredentialSchema = z.object({
+	verifier: z.string().regex(/^[0-9a-f]{64}$/),
+	expiresAt: z.number().int().safe(),
+})
+
+export const operationsReleasePayloadSchema = z.object({
+	runId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/),
+	coordinate: operationsReleaseCoordinateSchema,
+	phase: z.enum(['started', 'provider_accepted', 'terminal']),
+	providerRunId: z.string().max(256).nullable(),
+	outcome: z.enum(['succeeded', 'failed']).nullable(),
+	artifactState: z.enum(['pending', 'complete', 'incomplete', 'not_applicable']),
+	release: operationsReleaseAvailabilitySchema,
+	uploadCredential: operationsArtifactUploadCredentialSchema.optional(),
+	observedAt: z.number().int().safe().nonnegative(),
+}).superRefine((value, ctx) => {
+	if (value.uploadCredential !== undefined && value.uploadCredential.expiresAt <= value.observedAt) {
+		ctx.addIssue({ code: 'custom', path: ['uploadCredential'], message: 'invalid upload credential' })
+	}
+	if (value.release.kind === 'unavailable' && value.uploadCredential !== undefined) {
+		ctx.addIssue({ code: 'custom', message: 'unavailable releases cannot accept artifacts' })
+	}
+	if (value.phase === 'terminal' && value.outcome === null) {
+		ctx.addIssue({ code: 'custom', message: 'terminal release has no outcome' })
+	}
+	if (value.phase !== 'terminal' && value.outcome !== null) {
+		ctx.addIssue({ code: 'custom', message: 'non-terminal release has an outcome' })
+	}
+}).transform(({ uploadCredential, observedAt, ...payload }) => ({
+	...payload,
+	...(uploadCredential === undefined ? {} : { uploadCredential }),
+	observedAt,
+}))
+
+const releaseRequestHeaderSchema = z.object({ revision: z.number().int().safe().min(1) }).passthrough()
+
+export const operationsReleaseRequestSchema = releaseRequestHeaderSchema.transform((value, ctx) => {
+	const payload = operationsReleasePayloadSchema.safeParse(value)
+	if (!payload.success) {
+		for (const issue of payload.error.issues) ctx.addIssue(issue)
+		return z.NEVER
+	}
+	return { revision: value.revision, ...payload.data }
+})
+
+/** Preserve the public decoder's error categories and first-failure precedence. */
+export function operationsReleaseIssueMessage(issues: z.ZodIssue[]): string {
+	if (
+		issues.some((issue) => {
+			const field = issue.path[0]
+			return issue.code !== 'custom' && (field !== 'coordinate' && field !== 'release' && field !== 'uploadCredential'
+				|| ((field === 'coordinate' || field === 'release') && issue.path.length === 1 && issue.code === 'invalid_type'))
+		})
+	) return 'invalid release request'
+	if (issues.some((issue) => issue.path[0] === 'coordinate')) return 'invalid release coordinates'
+	const release = issues.find((issue) => issue.path[0] === 'release')
+	if (release !== undefined) {
+		if (release.code === 'invalid_union_discriminator') return 'invalid release availability'
+		return release.path[1] === 'reason' ? 'invalid unavailable release' : 'invalid available release'
+	}
+	if (issues.some((issue) => issue.path[0] === 'uploadCredential')) return 'invalid upload credential'
+	return issues[0]?.message ?? 'invalid release request'
+}

package/src/releases.ts

@@ -1,8 +1,16 @@
-/** Versioned private Delivery → Operations release and artifact protocol. */
+/** Private Delivery → Operations release and artifact protocol; both services ship together. */
 
 import { DEFAULT_OPERATIONS_SERVICE_KEY } from './catalog.js'
+import { operationsReleaseIssueMessage, operationsReleasePayloadSchema, operationsReleaseRequestSchema } from './release-schemas.js'
+
+export {
+	operationsArtifactUploadCredentialSchema,
+	operationsReleaseAvailabilitySchema,
+	operationsReleaseCoordinateSchema,
+	operationsReleasePayloadSchema,
+	operationsReleaseRequestSchema,
+} from './release-schemas.js'
 
-export const OPERATIONS_RELEASE_PROTOCOL_VERSION = 1
 export const FABRIKA_RELEASE = 'FABRIKA_RELEASE'
 export const OPERATIONS_RELEASE_RECONCILE_PATH = '/private/releases/reconcile'
 export const OPERATIONS_SOURCE_MAP_UPLOAD_PATH = '/api/artifacts/source-maps/'
@@ -22,13 +30,13 @@ export type OperationsReleaseOutcome = 'succeeded' | 'failed' | null
 export type OperationsArtifactState = 'pending' | 'complete' | 'incomplete' | 'not_applicable'
 export type OperationsReleaseUnavailableReason = 'dry_run' | 'missing_commit'
 
-export interface OperationsReleaseCoordinateV1 {
+export interface OperationsReleaseCoordinate {
 	appId: string
 	environment: string
 	serviceKey?: string
 }
 
-export type OperationsReleaseAvailabilityV1 =
+export type OperationsReleaseAvailability =
 	| {
 		kind: 'available'
 		name: string
@@ -39,33 +47,46 @@ export type OperationsReleaseAvailabilityV1 =
 		reason: OperationsReleaseUnavailableReason
 	}
 
-export interface OperationsArtifactUploadCredentialV1 {
+export interface OperationsArtifactUploadCredential {
 	/** SHA-256 verifier. The bearer itself never crosses the private projection boundary. */
 	verifier: string
 	expiresAt: number
 }
 
-export interface OperationsReleaseReconcileRequestV1 {
-	protocolVersion: typeof OPERATIONS_RELEASE_PROTOCOL_VERSION
+export interface OperationsReleaseReconcileRequest {
 	revision: number
 	runId: string
-	coordinate: OperationsReleaseCoordinateV1
+	coordinate: OperationsReleaseCoordinate
 	phase: OperationsReleasePhase
 	providerRunId: string | null
 	outcome: OperationsReleaseOutcome
 	artifactState: OperationsArtifactState
-	release: OperationsReleaseAvailabilityV1
-	uploadCredential?: OperationsArtifactUploadCredentialV1
+	release: OperationsReleaseAvailability
+	uploadCredential?: OperationsArtifactUploadCredential
 	observedAt: number
 }
 
+export type OperationsReleaseProjectionPayload = Omit<OperationsReleaseReconcileRequest, 'revision'>
+
+export class OperationsReleaseDecodeError extends Error {}
+
+export function parseOperationsReleaseRequest(value: unknown): OperationsReleaseReconcileRequest {
+	const result = operationsReleaseRequestSchema.safeParse(value)
+	if (!result.success) throw new OperationsReleaseDecodeError(operationsReleaseIssueMessage(result.error.issues))
+	return result.data
+}
+
+export function parseOperationsReleasePayload(value: unknown): OperationsReleaseProjectionPayload {
+	const result = operationsReleasePayloadSchema.safeParse(value)
+	if (!result.success) throw new OperationsReleaseDecodeError(operationsReleaseIssueMessage(result.error.issues))
+	return result.data
+}
+
 export type OperationsReleaseReconcileOutcome = 'applied' | 'unchanged' | 'stale'
 
-export interface OperationsReleaseReconcileResponseV1 {
-	protocolVersion: typeof OPERATIONS_RELEASE_PROTOCOL_VERSION
+export interface OperationsReleaseReconcileResponse {
 	revision: number
 	outcome: OperationsReleaseReconcileOutcome
-	releaseId: string | null
 }
 
 export interface OperationsArtifactUploadConfiguration {