@fabrika/operations-contract 0.0.1

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@fabrika/operations-contract",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/operations-contract"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./ingest": {
+			"bun": "./src/ingest.ts",
+			"types": "./src/ingest.ts",
+			"default": "./src/ingest.ts"
+		},
+		"./operator": {
+			"bun": "./src/operator.ts",
+			"types": "./src/operator.ts",
+			"default": "./src/operator.ts"
+		},
+		"./operator-api": {
+			"bun": "./src/operator-api.ts",
+			"types": "./src/operator-api.ts",
+			"default": "./src/operator-api.ts"
+		},
+		"./access": {
+			"bun": "./src/access.ts",
+			"types": "./src/access.ts",
+			"default": "./src/access.ts"
+		},
+		"./catalog": {
+			"bun": "./src/catalog.ts",
+			"types": "./src/catalog.ts",
+			"default": "./src/catalog.ts"
+		},
+		"./releases": {
+			"bun": "./src/releases.ts",
+			"types": "./src/releases.ts",
+			"default": "./src/releases.ts"
+		},
+		"./rpc": {
+			"bun": "./src/rpc.ts",
+			"types": "./src/rpc.ts",
+			"default": "./src/rpc.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@fabrika/app": "^0.0.1"
+	}
+}

package/src/access.ts

@@ -0,0 +1,16 @@
+/** IAM vocabulary shared by the Operations runtime and Fabrika's Access schema. */
+
+/**
+ * The app id every composition names the Operations HOST by — the Cloudflare proxy Worker's manifest,
+ * the shared platform manifest, and `defineApp`. One constant because a shared manifest may not name
+ * one app twice, so the two compositions cannot disagree here and stay generalisable.
+ */
+export const OPERATIONS_APP_ID = 'operations'
+
+export const OPERATIONS_ACTIONS = {
+	READ: 'operations.read',
+	TRIAGE: 'operations.triage',
+	MANAGE: 'operations.manage',
+} as const
+
+export type OperationsAction = (typeof OPERATIONS_ACTIONS)[keyof typeof OPERATIONS_ACTIONS]

package/src/catalog.ts

@@ -0,0 +1,103 @@
+/** Versioned private Control → Operations source-catalog protocol. */
+
+export const OPERATIONS_CATALOG_PROTOCOL_VERSION = 2
+export const DEFAULT_OPERATIONS_SERVICE_KEY = 'default'
+
+export interface OperationsSourceCoordinateV1 {
+	appId: string
+	environment: string
+	/** Omitted by Control while an app environment has only its default service. */
+	serviceKey?: string
+}
+
+export interface CanonicalOperationsSourceCoordinateV1 {
+	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 {
+	id: string
+	publicKey: string
+}
+
+export interface OperationsCatalogSourceV2 extends OperationsCatalogSourceV1 {
+	ingestCredential: OperationsCatalogIngestCredentialV2
+}
+
+export interface CanonicalOperationsCatalogSourceV2 extends CanonicalOperationsCatalogSourceV1 {
+	ingestCredential: OperationsCatalogIngestCredentialV2
+}
+
+export interface OperationsCatalogReconcileRequestV2 {
+	protocolVersion: typeof OPERATIONS_CATALOG_PROTOCOL_VERSION
+	revision: number
+	snapshotHash: string
+	sources: OperationsCatalogSourceV2[]
+}
+
+export type OperationsCatalogReconcileOutcome = 'applied' | 'unchanged' | 'stale'
+
+export interface OperationsCatalogIngestResultV2 {
+	coordinate: CanonicalOperationsSourceCoordinateV1
+	credentialId: string
+	ingestProjectId: string
+}
+
+export interface OperationsCatalogReconcileResponseV2 {
+	protocolVersion: typeof OPERATIONS_CATALOG_PROTOCOL_VERSION
+	revision: number
+	outcome: OperationsCatalogReconcileOutcome
+	created: number
+	updated: number
+	disabled: number
+	reenabled: number
+	unchanged: number
+	ingest: OperationsCatalogIngestResultV2[]
+}
+
+export function canonicalOperationsServiceKey(serviceKey: string | undefined): string {
+	return serviceKey ?? DEFAULT_OPERATIONS_SERVICE_KEY
+}
+
+export function canonicalOperationsCatalogSources(
+	sources: readonly OperationsCatalogSourceV2[],
+): CanonicalOperationsCatalogSourceV2[] {
+	return sources.map((source) => ({
+		coordinate: {
+			appId: source.coordinate.appId,
+			environment: source.coordinate.environment,
+			serviceKey: canonicalOperationsServiceKey(source.coordinate.serviceKey),
+		},
+		displayName: source.displayName,
+		publicOrigin: source.publicOrigin ?? null,
+		ingestCredential: source.ingestCredential,
+	})).sort((left, right) => {
+		const app = left.coordinate.appId.localeCompare(right.coordinate.appId)
+		if (app !== 0) return app
+		const environment = left.coordinate.environment.localeCompare(right.coordinate.environment)
+		if (environment !== 0) return environment
+		return left.coordinate.serviceKey.localeCompare(right.coordinate.serviceKey)
+	})
+}
+
+/** Hash the canonical source array only; revision is transport ordering, not catalog content. */
+export async function operationsCatalogSnapshotHash(sources: readonly OperationsCatalogSourceV2[]): 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

@@ -0,0 +1,120 @@
+export { OPERATIONS_ACTIONS, OPERATIONS_APP_ID } from './access.js'
+export type { OperationsAction } from './access.js'
+export {
+	canonicalOperationsCatalogSources,
+	canonicalOperationsServiceKey,
+	DEFAULT_OPERATIONS_SERVICE_KEY,
+	OPERATIONS_CATALOG_PROTOCOL_VERSION,
+	operationsCatalogSnapshotHash,
+} from './catalog.js'
+export type {
+	CanonicalOperationsCatalogSourceV1,
+	CanonicalOperationsCatalogSourceV2,
+	CanonicalOperationsSourceCoordinateV1,
+	OperationsCatalogIngestCredentialV2,
+	OperationsCatalogIngestResultV2,
+	OperationsCatalogReconcileOutcome,
+	OperationsCatalogReconcileRequestV2,
+	OperationsCatalogReconcileResponseV2,
+	OperationsCatalogSourceV1,
+	OperationsCatalogSourceV2,
+	OperationsSourceCoordinateV1,
+} from './catalog.js'
+export {
+	buildOperationsDsn,
+	FABRIKA_APP_ID,
+	FABRIKA_ENVIRONMENT,
+	FABRIKA_OPERATIONS_DSN,
+	FABRIKA_SERVICE_KEY,
+	OPERATIONS_MANAGED_ENVIRONMENT_KEYS,
+	operationsEnvelopeUrl,
+	operationsManagedEnvironment,
+	operationsManagedEnvironmentCollisions,
+} from './ingest.js'
+export type {
+	IngestMessage,
+	IngestRejectReason,
+	OperationsIngestConfiguration,
+	OperationsManagedEnvironmentKey,
+	ParsedEvent,
+	ParsedException,
+	StackFrame,
+} from './ingest.js'
+export type {
+	OperationsAlertKind,
+	OperationsAlertRuleDto,
+	OperationsAlertRuleRequestDto,
+	OperationsAlertSettingsResponseDto,
+	OperationsAssigneeListResponseDto,
+	OperationsBulkIssueStatusRequestDto,
+	OperationsBulkIssueStatusResponseDto,
+	OperationsCurrentHttpHealthDto,
+	OperationsEventDetailResponseDto,
+	OperationsHealthCheckDto,
+	OperationsHealthCheckUpsertRequestDto,
+	OperationsHealthObservationDto,
+	OperationsHealthResponseDto,
+	OperationsHealthState,
+	OperationsIssueDetailDto,
+	OperationsIssueDetailResponseDto,
+	OperationsIssueListResponseDto,
+	OperationsIssueMutationRequestDto,
+	OperationsIssueOccurrenceDto,
+	OperationsIssueOccurrenceListResponseDto,
+	OperationsIssueSummaryDto,
+	OperationsNotificationAttemptDto,
+	OperationsNotificationChannelDto,
+	OperationsNotificationChannelRequestDto,
+	OperationsNotificationDeliveryDto,
+	OperationsReleaseDetailResponseDto,
+	OperationsReleaseListResponseDto,
+	OperationsReleaseSummaryDto,
+	OperationsSourceDetailResponseDto,
+	OperationsSourceHealthDto,
+	OperationsSourceListResponseDto,
+	OperationsSourceSummaryDto,
+	OperationsSpikeAlertRequestDto,
+} from './operator-api.js'
+export type {
+	ActivityDraft,
+	ActivityItem,
+	ActivityKind,
+	DisplayFrame,
+	EventBreadcrumb,
+	EventDetail,
+	EventException,
+	IssueAlertType,
+	IssueListItem,
+	IssueMutation,
+	IssueMutationDecision,
+	IssueStatus,
+	Occurrence,
+	OccurrenceTransition,
+	PriorIssueState,
+	RawEventFrame,
+	SourceContext,
+} from './operator.js'
+export {
+	FABRIKA_RELEASE,
+	normalizeOperationsCommit,
+	OPERATIONS_ARTIFACT_HEADERS,
+	OPERATIONS_RELEASE_PROTOCOL_VERSION,
+	OPERATIONS_RELEASE_RECONCILE_PATH,
+	OPERATIONS_SOURCE_MAP_UPLOAD_PATH,
+	operationsReleaseName,
+	operationsSourceMapUploadUrl,
+} from './releases.js'
+export type {
+	OperationsArtifactState,
+	OperationsArtifactUploadConfiguration,
+	OperationsArtifactUploadCredentialV1,
+	OperationsReleaseAvailabilityV1,
+	OperationsReleaseCoordinateV1,
+	OperationsReleaseOutcome,
+	OperationsReleasePhase,
+	OperationsReleaseReconcileOutcome,
+	OperationsReleaseReconcileRequestV1,
+	OperationsReleaseReconcileResponseV1,
+	OperationsReleaseUnavailableReason,
+} from './releases.js'
+export type { OperationsIssueQuery, OperationsReleaseQuery, OperationsRpcContract } from './rpc.js'

package/src/ingest.ts

@@ -0,0 +1,130 @@
+/** Browser- and runtime-safe shapes at the direct Sentry-compatible ingest boundary. */
+
+export const FABRIKA_OPERATIONS_DSN = 'FABRIKA_OPERATIONS_DSN'
+export const FABRIKA_APP_ID = 'FABRIKA_APP_ID'
+export const FABRIKA_ENVIRONMENT = 'FABRIKA_ENVIRONMENT'
+export const FABRIKA_SERVICE_KEY = 'FABRIKA_SERVICE_KEY'
+
+export type OperationsManagedEnvironmentKey =
+	| typeof FABRIKA_OPERATIONS_DSN
+	| typeof FABRIKA_APP_ID
+	| typeof FABRIKA_ENVIRONMENT
+	| typeof FABRIKA_SERVICE_KEY
+
+export const OPERATIONS_MANAGED_ENVIRONMENT_KEYS: readonly OperationsManagedEnvironmentKey[] = [
+	FABRIKA_OPERATIONS_DSN,
+	FABRIKA_APP_ID,
+	FABRIKA_ENVIRONMENT,
+	FABRIKA_SERVICE_KEY,
+]
+
+export interface OperationsIngestConfiguration {
+	dsn: string
+	appId: string
+	environment: string
+	serviceKey: string
+}
+
+const PUBLIC_KEY_PATTERN = /^[0-9a-f]{32}$/
+const INGEST_PROJECT_ID_PATTERN = /^[1-9][0-9]{0,18}$/
+
+export function buildOperationsDsn(origin: string, publicKey: string, ingestProjectId: string): string {
+	if (!PUBLIC_KEY_PATTERN.test(publicKey)) throw new Error('invalid Operations ingest public key')
+	if (!INGEST_PROJECT_ID_PATTERN.test(ingestProjectId)) throw new Error('invalid Operations ingest project id')
+	const url = new URL(origin)
+	if (
+		(url.protocol !== 'https:' && url.protocol !== 'http:')
+		|| url.origin !== origin
+		|| url.username !== ''
+		|| url.password !== ''
+	) {
+		throw new Error('Operations ingest origin must be an HTTP origin')
+	}
+	url.username = publicKey
+	url.pathname = `/${ingestProjectId}`
+	return url.toString()
+}
+
+export function operationsEnvelopeUrl(origin: string, ingestProjectId: string): string {
+	if (!INGEST_PROJECT_ID_PATTERN.test(ingestProjectId)) throw new Error('invalid Operations ingest project id')
+	const url = new URL(origin)
+	if (
+		(url.protocol !== 'https:' && url.protocol !== 'http:')
+		|| url.origin !== origin
+		|| url.username !== ''
+		|| url.password !== ''
+	) {
+		throw new Error('Operations ingest origin must be an HTTP origin')
+	}
+	url.pathname = `/api/${ingestProjectId}/envelope/`
+	return url.toString()
+}
+
+export function operationsManagedEnvironment(input: OperationsIngestConfiguration): Record<OperationsManagedEnvironmentKey, string> {
+	return {
+		[FABRIKA_OPERATIONS_DSN]: input.dsn,
+		[FABRIKA_APP_ID]: input.appId,
+		[FABRIKA_ENVIRONMENT]: input.environment,
+		[FABRIKA_SERVICE_KEY]: input.serviceKey,
+	}
+}
+
+export function operationsManagedEnvironmentCollisions(keys: Iterable<string>): OperationsManagedEnvironmentKey[] {
+	const occupied = new Set(keys)
+	return OPERATIONS_MANAGED_ENVIRONMENT_KEYS.filter((key) => occupied.has(key))
+}
+
+export interface StackFrame {
+	function?: string
+	filename?: string
+	module?: string
+	absPath?: string
+	line?: number
+	column?: number
+	inApp?: boolean
+	preContext?: string[]
+	contextLine?: string
+	postContext?: string[]
+}
+
+export interface ParsedException {
+	type: string
+	value: string
+	frames: StackFrame[]
+}
+
+export interface ParsedEvent {
+	eventId: string
+	projectId: string
+	exception: ParsedException
+	level: string
+	release?: string
+	environment?: string
+	platform?: string
+	tags: Record<string, string>
+	sdkFingerprint: string[] | null
+	receivedAt: number
+	raw: Record<string, unknown>
+}
+
+export interface IngestMessage {
+	projectId: string
+	fingerprint: string
+	eventId: string
+	title: string
+	culprit: string | null
+	level: string
+	release?: string
+	environment?: string
+	receivedAt: number
+	payload: Record<string, unknown>
+}
+
+export type IngestRejectReason =
+	| 'unauthorized'
+	| 'forbidden'
+	| 'too_large'
+	| 'malformed'
+	| 'unsupported'
+	| 'rate_limited'
+	| 'unavailable'

package/src/operator-api.ts

@@ -0,0 +1,250 @@
+import type { ActivityItem, EventDetail, IssueStatus } from './operator.js'
+import type { OperationsArtifactState } from './releases.js'
+
+export type OperationsAlertKind =
+	| 'new_issue'
+	| 'regression'
+	| 'spike'
+	| 'failed_check'
+	| 'recovery'
+	| 'unhealthy_telemetry'
+
+export type OperationsHealthState = 'healthy' | 'degraded' | 'failed' | 'stale' | 'unavailable'
+
+export interface OperationsSourceSummaryDto {
+	id: string
+	appId: string
+	environment: string
+	serviceKey: string
+	displayName: string
+	publicOrigin: string | null
+	enabled: boolean
+}
+
+export interface OperationsSourceListResponseDto {
+	items: OperationsSourceSummaryDto[]
+}
+
+export interface OperationsSourceDetailResponseDto {
+	source: OperationsSourceSummaryDto
+}
+
+export interface OperationsIssueSummaryDto {
+	id: string
+	source: OperationsSourceSummaryDto
+	title: string
+	culprit: string | null
+	level: string
+	status: IssueStatus
+	assignedTo: { id: string; label: string | null } | null
+	regressedAt: number | null
+	firstSeen: number
+	lastSeen: number
+	count: number
+	trend: number[]
+}
+
+export interface OperationsIssueOccurrenceDto {
+	id: string
+	eventId: string
+	receivedAt: number
+	release: string | null
+}
+
+export interface OperationsIssueListResponseDto {
+	items: OperationsIssueSummaryDto[]
+	nextCursor: string | null
+	summary: {
+		total: number
+		open: number
+		resolved: number
+		ignored: number
+	}
+}
+
+export interface OperationsIssueDetailDto extends OperationsIssueSummaryDto {
+	snoozeUntil: number | null
+	snoozeUntilCount: number | null
+	resolvedInRelease: { id: string; name: string } | null
+	mergedIntoIssueId: string | null
+	activity: ActivityItem[]
+	latestOccurrence: OperationsIssueOccurrenceDto | null
+	occurrences: OperationsIssueOccurrenceDto[]
+	occurrencesNextCursor: string | null
+}
+
+export interface OperationsIssueDetailResponseDto {
+	issue: OperationsIssueDetailDto
+}
+
+export interface OperationsEventDetailResponseDto {
+	occurrenceId: string
+	receivedAt: number
+	detail: EventDetail
+}
+
+export interface OperationsIssueOccurrenceListResponseDto {
+	items: OperationsIssueOccurrenceDto[]
+	nextCursor: string | null
+}
+
+export type OperationsIssueMutationRequestDto =
+	| { kind: 'status'; status: IssueStatus }
+	| { kind: 'comment'; text: string }
+	| { kind: 'assign'; principalId: string | null }
+	| { kind: 'snooze_until'; until: number }
+	| { kind: 'snooze_count'; additional: number }
+	| { kind: 'resolve_in_release'; releaseId: string | null }
+	| { kind: 'merge'; targetIssueId: string }
+
+export interface OperationsBulkIssueStatusRequestDto {
+	issueIds: string[]
+	status: IssueStatus
+}
+
+export interface OperationsBulkIssueStatusResponseDto {
+	items: OperationsIssueSummaryDto[]
+}
+
+export interface OperationsAssigneeListResponseDto {
+	items: {
+		id: string
+		label: string
+	}[]
+}
+
+export interface OperationsReleaseSummaryDto {
+	id: string
+	source: OperationsSourceSummaryDto
+	runId: string
+	commitSha: string
+	state: string
+	artifactState: OperationsArtifactState
+	releaseName: string
+	createdAt: number
+	finishedAt: number | null
+	newIssueCount: number
+	regressionCount: number
+}
+
+export interface OperationsReleaseListResponseDto {
+	items: OperationsReleaseSummaryDto[]
+	nextCursor: string | null
+}
+
+export interface OperationsReleaseDetailResponseDto {
+	release: OperationsReleaseSummaryDto
+	issues: OperationsIssueSummaryDto[]
+}
+
+export interface OperationsCurrentHttpHealthDto {
+	state: Exclude<OperationsHealthState, 'unavailable'>
+	observedAt: number
+	latencyMs: number | null
+	detailCode: string
+	consecutiveFailures: number
+	consecutiveSuccesses: number
+}
+
+export interface OperationsHealthObservationDto {
+	id: string
+	state: OperationsHealthState
+	observedAt: number
+	latencyMs: number | null
+	detailCode: string | null
+	successful: boolean
+	statusCode: number | null
+}
+
+export interface OperationsHealthCheckDto {
+	id: string
+	sourceId: string
+	path: string
+	enabled: boolean
+	intervalMs: number
+	timeoutMs: number
+	expectedStatus: number
+	failureThreshold: number
+	recoveryThreshold: number
+	staleAfterMs: number
+	current: OperationsCurrentHttpHealthDto | null
+	history: OperationsHealthObservationDto[]
+}
+
+export interface OperationsSourceHealthDto {
+	source: OperationsSourceSummaryDto
+	httpChecks: OperationsHealthCheckDto[]
+	telemetryState: OperationsHealthState
+}
+
+export interface OperationsHealthResponseDto {
+	sources: OperationsSourceHealthDto[]
+}
+
+export interface OperationsHealthCheckUpsertRequestDto {
+	path: string
+	enabled: boolean
+	intervalMs: number
+	timeoutMs: number
+	expectedStatus: number
+	failureThreshold: number
+	recoveryThreshold: number
+	staleAfterMs: number
+}
+
+export interface OperationsAlertRuleDto {
+	kind: OperationsAlertKind
+	enabled: boolean
+}
+
+export interface OperationsNotificationChannelDto {
+	id: string
+	scope: OperationsAlertKind
+	type: 'webhook'
+	targetDisplay: string
+	hasTarget: boolean
+	enabled: boolean
+}
+
+export interface OperationsNotificationAttemptDto {
+	id: string
+	attemptedAt: number
+	delivered: boolean
+	errorCode: string | null
+}
+
+export interface OperationsNotificationDeliveryDto {
+	id: string
+	channelId: string
+	kind: OperationsAlertKind
+	createdAt: number
+	attemptCount: number
+	maxAttempts: number
+	status: 'pending' | 'delivered' | 'abandoned'
+	deliveredAt: number | null
+	abandonedAt: number | null
+	attempts: OperationsNotificationAttemptDto[]
+}
+
+export interface OperationsAlertSettingsResponseDto {
+	spike: { threshold: number; enabled: boolean } | null
+	rules: OperationsAlertRuleDto[]
+	channels: OperationsNotificationChannelDto[]
+	deliveries: OperationsNotificationDeliveryDto[]
+}
+
+export interface OperationsSpikeAlertRequestDto {
+	threshold: number
+	enabled: boolean
+}
+
+export interface OperationsAlertRuleRequestDto {
+	enabled: boolean
+}
+
+export interface OperationsNotificationChannelRequestDto {
+	scope: OperationsAlertKind
+	type: 'webhook'
+	target?: string
+	enabled: boolean
+}

package/src/operator.ts

@@ -0,0 +1,123 @@
+import type { StackFrame } from './ingest.js'
+
+export type IssueStatus = 'open' | 'resolved' | 'ignored'
+export type ActivityKind = 'comment' | 'status' | 'assigned' | 'regressed' | 'snoozed' | 'unsnoozed' | 'merged'
+export type IssueAlertType = 'new_issue' | 'regression'
+
+export interface IssueListItem {
+	fingerprint: string
+	projectId: string
+	title: string
+	culprit: string | null
+	level: string
+	status: IssueStatus
+	assignedTo: string | null
+	regressedAt: number | null
+	firstSeen: number
+	lastSeen: number
+	count: number
+	trend: number[]
+}
+
+export interface ActivityItem {
+	id: string
+	kind: ActivityKind
+	actorLabel: string | null
+	data: Record<string, unknown> | null
+	at: number
+}
+
+export interface SourceContext {
+	lines: string[]
+	errorIndex: number
+	startLine: number
+}
+
+export interface DisplayFrame {
+	file: string
+	function: string | null
+	line: number | null
+	column: number | null
+	inApp: boolean
+	resolved: boolean
+	source?: SourceContext
+}
+
+export interface EventException {
+	type: string | null
+	value: string | null
+	handled: boolean | null
+	frames: DisplayFrame[]
+}
+
+export interface EventBreadcrumb {
+	timestamp?: number | string
+	type?: string
+	category?: string
+	level?: string
+	message?: string
+}
+
+export interface EventDetail {
+	eventId: string | null
+	platform: string | null
+	release: string | null
+	environment: string | null
+	tags: { key: string; value: string }[]
+	request: { url: string | null; method: string | null } | null
+	user: { id: string | null; email: string | null; username: string | null } | null
+	breadcrumbs: EventBreadcrumb[]
+	runtime: string | null
+	os: string | null
+	serverName: string | null
+	traceId: string | null
+	exceptions: EventException[]
+	rawEvent: string
+}
+
+export interface Occurrence {
+	release?: string
+	receivedAt: number
+}
+
+export interface PriorIssueState {
+	status: IssueStatus
+	resolvedInRelease: string | null
+	snoozeUntil: number | null
+	snoozeUntilCount: number | null
+}
+
+export interface OccurrenceTransition {
+	reopen: boolean
+	regression: boolean
+	at: number | null
+	release: string | null
+	activity: ActivityKind | null
+}
+
+export type IssueMutation =
+	| { kind: 'status'; status: IssueStatus }
+	| { kind: 'comment'; text: string }
+	| { kind: 'assign'; principalId: string | null; principalLabel: string | null }
+	| { kind: 'snooze_until'; until: number }
+	| { kind: 'snooze_count'; additional: number; currentCount: number }
+	| { kind: 'resolve_in_release'; release: string | null }
+	| { kind: 'merge'; target: string }
+
+export interface ActivityDraft {
+	kind: ActivityKind
+	data: Record<string, unknown>
+}
+
+export interface IssueMutationDecision {
+	status: IssueStatus
+	assignedTo?: string | null
+	assignedToLabel?: string | null
+	snoozeUntil?: number | null
+	snoozeUntilCount?: number | null
+	resolvedInRelease?: string | null
+	mergedInto?: string
+	activity: ActivityDraft | null
+}
+
+export type RawEventFrame = StackFrame

package/src/releases.ts

@@ -0,0 +1,118 @@
+/** Versioned private Delivery → Operations release and artifact protocol. */
+
+import { DEFAULT_OPERATIONS_SERVICE_KEY } from './catalog.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/'
+
+export const OPERATIONS_ARTIFACT_HEADERS = {
+	appId: 'X-Fabrika-App-Id',
+	environment: 'X-Fabrika-Environment',
+	serviceKey: 'X-Fabrika-Service-Key',
+	release: 'X-Fabrika-Release',
+	runId: 'X-Fabrika-Run-Id',
+	logicalPath: 'X-Fabrika-Artifact-Path',
+	digest: 'X-Fabrika-Artifact-Sha256',
+}
+
+export type OperationsReleasePhase = 'started' | 'provider_accepted' | 'terminal'
+export type OperationsReleaseOutcome = 'succeeded' | 'failed' | null
+export type OperationsArtifactState = 'pending' | 'complete' | 'incomplete' | 'not_applicable'
+export type OperationsReleaseUnavailableReason = 'dry_run' | 'missing_commit'
+
+export interface OperationsReleaseCoordinateV1 {
+	appId: string
+	environment: string
+	serviceKey?: string
+}
+
+export type OperationsReleaseAvailabilityV1 =
+	| {
+		kind: 'available'
+		name: string
+		commitSha: string
+	}
+	| {
+		kind: 'unavailable'
+		reason: OperationsReleaseUnavailableReason
+	}
+
+export interface OperationsArtifactUploadCredentialV1 {
+	/** 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
+	revision: number
+	runId: string
+	coordinate: OperationsReleaseCoordinateV1
+	phase: OperationsReleasePhase
+	providerRunId: string | null
+	outcome: OperationsReleaseOutcome
+	artifactState: OperationsArtifactState
+	release: OperationsReleaseAvailabilityV1
+	uploadCredential?: OperationsArtifactUploadCredentialV1
+	observedAt: number
+}
+
+export type OperationsReleaseReconcileOutcome = 'applied' | 'unchanged' | 'stale'
+
+export interface OperationsReleaseReconcileResponseV1 {
+	protocolVersion: typeof OPERATIONS_RELEASE_PROTOCOL_VERSION
+	revision: number
+	outcome: OperationsReleaseReconcileOutcome
+	releaseId: string | null
+}
+
+export interface OperationsArtifactUploadConfiguration {
+	url: string
+	bearer: string
+	appId: string
+	environment: string
+	serviceKey: string
+	release: string
+	runId: string
+}
+
+const COMMIT_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
+
+export function normalizeOperationsCommit(value: string | null | undefined): string | null {
+	if (value === null || value === undefined) return null
+	const normalized = value.toLowerCase()
+	return COMMIT_PATTERN.test(normalized) ? normalized : null
+}
+
+export function operationsReleaseName(input: {
+	appId: string
+	environment: string
+	serviceKey?: string
+	commitSha: string
+}): string {
+	const commitSha = normalizeOperationsCommit(input.commitSha)
+	if (commitSha === null) throw new Error('release commit must be a complete immutable git object id')
+	return [
+		'fabrika',
+		encodeURIComponent(input.appId),
+		encodeURIComponent(input.environment),
+		encodeURIComponent(input.serviceKey ?? DEFAULT_OPERATIONS_SERVICE_KEY),
+		commitSha,
+	].join('/')
+}
+
+export function operationsSourceMapUploadUrl(origin: string): string {
+	const url = new URL(origin)
+	if (
+		(url.protocol !== 'https:' && url.protocol !== 'http:')
+		|| url.origin !== origin
+		|| url.username !== ''
+		|| url.password !== ''
+	) {
+		throw new Error('Operations artifact origin must be an HTTP origin')
+	}
+	url.pathname = OPERATIONS_SOURCE_MAP_UPLOAD_PATH
+	return url.toString()
+}

package/src/rpc.ts

@@ -0,0 +1,86 @@
+import type { RpcProcedureContract } from '@fabrika/app'
+import type {
+	OperationsAlertKind,
+	OperationsAlertRuleRequestDto,
+	OperationsAlertSettingsResponseDto,
+	OperationsAssigneeListResponseDto,
+	OperationsBulkIssueStatusRequestDto,
+	OperationsBulkIssueStatusResponseDto,
+	OperationsEventDetailResponseDto,
+	OperationsHealthCheckUpsertRequestDto,
+	OperationsHealthResponseDto,
+	OperationsIssueDetailResponseDto,
+	OperationsIssueListResponseDto,
+	OperationsIssueMutationRequestDto,
+	OperationsIssueOccurrenceListResponseDto,
+	OperationsNotificationChannelRequestDto,
+	OperationsReleaseDetailResponseDto,
+	OperationsReleaseListResponseDto,
+	OperationsSourceDetailResponseDto,
+	OperationsSourceHealthDto,
+	OperationsSourceListResponseDto,
+	OperationsSpikeAlertRequestDto,
+} from './operator-api.js'
+
+export interface OperationsIssueQuery {
+	sourceId?: string
+	status?: 'open' | 'resolved' | 'ignored'
+	level?: 'fatal' | 'error' | 'warning' | 'info'
+	window?: 'all' | '24h' | '7d' | '30d'
+	query?: string
+	assignee?: 'all' | 'me' | 'none'
+	sort?: 'recent' | 'new' | 'frequency'
+	cursor?: string
+	limit?: number
+}
+
+export interface OperationsReleaseQuery {
+	sourceId?: string
+	cursor?: string
+	limit?: number
+}
+
+/** Portable operator API implemented by Operations and consumed by its console. */
+export interface OperationsRpcContract {
+	sources: RpcProcedureContract<void, OperationsSourceListResponseDto>
+	source: RpcProcedureContract<{ sourceId: string }, OperationsSourceDetailResponseDto>
+	issues: RpcProcedureContract<OperationsIssueQuery, OperationsIssueListResponseDto>
+	issue: RpcProcedureContract<{ issueId: string }, OperationsIssueDetailResponseDto>
+	issueOccurrences: RpcProcedureContract<{ issueId: string; cursor?: string; limit?: number }, OperationsIssueOccurrenceListResponseDto>
+	latestEvent: RpcProcedureContract<{ issueId: string }, OperationsEventDetailResponseDto>
+	event: RpcProcedureContract<{ issueId: string; occurrenceId: string }, OperationsEventDetailResponseDto>
+	mutateIssue: RpcProcedureContract<{ issueId: string; mutation: OperationsIssueMutationRequestDto }, OperationsIssueDetailResponseDto>
+	bulkIssueStatus: RpcProcedureContract<OperationsBulkIssueStatusRequestDto, OperationsBulkIssueStatusResponseDto>
+	assignees: RpcProcedureContract<{ sourceId: string }, OperationsAssigneeListResponseDto>
+	releases: RpcProcedureContract<OperationsReleaseQuery, OperationsReleaseListResponseDto>
+	release: RpcProcedureContract<{ releaseId: string }, OperationsReleaseDetailResponseDto>
+	health: RpcProcedureContract<void, OperationsHealthResponseDto>
+	sourceHealth: RpcProcedureContract<{ sourceId: string }, OperationsSourceHealthDto>
+	createHealthCheck: RpcProcedureContract<
+		{ sourceId: string; input: OperationsHealthCheckUpsertRequestDto },
+		{ id: string }
+	>
+	updateHealthCheck: RpcProcedureContract<
+		{ sourceId: string; checkId: string; input: OperationsHealthCheckUpsertRequestDto },
+		{ id: string }
+	>
+	deleteHealthCheck: RpcProcedureContract<{ sourceId: string; checkId: string }, null>
+	alerts: RpcProcedureContract<{ sourceId: string }, OperationsAlertSettingsResponseDto>
+	updateSpikeAlert: RpcProcedureContract<
+		{ sourceId: string; input: OperationsSpikeAlertRequestDto },
+		{ threshold: number; enabled: boolean }
+	>
+	updateAlertRule: RpcProcedureContract<
+		{ sourceId: string; kind: OperationsAlertKind; input: OperationsAlertRuleRequestDto },
+		{ kind: OperationsAlertKind; enabled: boolean }
+	>
+	createAlertChannel: RpcProcedureContract<
+		{ sourceId: string; input: OperationsNotificationChannelRequestDto },
+		{ id: string }
+	>
+	updateAlertChannel: RpcProcedureContract<
+		{ sourceId: string; channelId: string; input: OperationsNotificationChannelRequestDto },
+		{ id: string }
+	>
+	deleteAlertChannel: RpcProcedureContract<{ sourceId: string; channelId: string }, null>
+}