@fabrika/control-contract 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/control-contract",
-	"version": "0.3.2",
+	"version": "0.4.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -25,8 +25,8 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "^0.3.2",
-		"@fabrika/app": "^0.3.2",
-		"@fabrika/provider-contract": "^0.3.2"
+		"@fabrika/auth-core": "^0.4.0",
+		"@fabrika/app": "^0.4.0",
+		"@fabrika/provider-contract": "^0.4.0"
 	}
 }

package/src/index.ts

@@ -183,6 +183,17 @@ export interface AppEnvDto {
 	domain: string | null
 	publicOrigin: string | null
 	triggerRef: string | null
+	/** An MCP authoring target (ADR-0049): users with `source.workspace.*` grants may edit and deploy it. */
+	authoring: boolean
+	/** A widening of access waits for a human's approval here (ADR-0050); `prod` is protected by default. */
+	protected: boolean
+	/** The run whose snapshot is this environment's active access; null until a run publishes one. */
+	publishedRunId: string | null
+	/**
+	 * The published snapshot's steps off the paved road, one line each: the reach its sites declare and the database code
+	 * its migrations declare. Each needs closer review; listed whether or not the environment is protected.
+	 */
+	deviations: string[]
 	namespaceId: string | null
 	provider: string
 	target: ProviderEnvelopeDto
@@ -194,6 +205,8 @@ export interface PutAppEnvRequest {
 	domain?: string | null
 	publicOrigin?: string | null
 	triggerRef?: string | null
+	/** Omitted keeps the stored value. Only a Zerops environment of an app with a GitHub connection qualifies. */
+	authoring?: boolean
 	namespaceId?: string | null
 	target: ProviderEnvelopeDto
 	artifact: ProviderEnvelopeDto
@@ -216,6 +229,11 @@ export interface DeploymentNamespaceDto {
 	 */
 	lastError: string | null
 	lastErrorCode: string | null
+	/**
+	 * Present only while a `namespaces.update` is unconfirmed (`lastErrorCode` `namespaceUpdateUnconfirmed`):
+	 * the target that update was moving to. Retrying `namespaces.update` with it finishes the update.
+	 */
+	unconfirmedTarget?: ProviderEnvelopeDto
 	createdAt: number
 }
 
@@ -252,6 +270,16 @@ export interface AdoptDeploymentNamespaceRequest {
 	target: ProviderEnvelopeDto
 }
 
+/**
+ * A namespace's new provider target. Its payload may name only what changes; the provider merges it over
+ * the stored one. Only what the provider can change in place is accepted — on Zerops the PostgreSQL
+ * profile. A field the target does not have is a 400; any other change is a 409 that names the supported
+ * path, a new namespace under a new id.
+ */
+export interface UpdateDeploymentNamespaceRequest {
+	target: ProviderEnvelopeDto
+}
+
 export interface DeploymentNamespaceFactDto {
 	readonly label: string
 	readonly value: string
@@ -367,7 +395,8 @@ export interface RegisterAppResponse {
 }
 
 export type RunTrigger = 'webhook' | 'manual' | 'poll'
-export type RunStatus = 'pending' | 'running' | 'succeeded' | 'failed'
+/** `awaiting_approval`: the run widens access on a protected environment and waits for a human (ADR-0050). */
+export type RunStatus = 'pending' | 'running' | 'awaiting_approval' | 'succeeded' | 'failed'
 
 export interface RunDto {
 	id: string
@@ -376,6 +405,8 @@ export interface RunDto {
 	ref: string
 	commitSha: string | null
 	trigger: RunTrigger
+	/** Who created the run: `user:<id>`, `service:<id>`, `oauth:<id>` (an MCP client acting for a user), `webhook:<connection>` or `poll`. */
+	actor: string | null
 	status: RunStatus
 	exitCode: number | null
 	externalRunId: string | null
@@ -385,6 +416,46 @@ export interface RunDto {
 	finishedAt: number | null
 }
 
+/**
+ * One plain-language line of an access change; `widens` when it can grant access the baseline did not. `review: 'closer'`
+ * marks a step off the paved road (declared reach, database code) or a change the diff cannot classify.
+ */
+export interface AccessChangeDto {
+	widens: boolean
+	line: string
+	review?: 'closer'
+}
+
+/** A run's access change against its environment's active snapshot (ADR-0050 §3). */
+export interface ApprovalDto {
+	run: RunDto
+	outcome: 'unchanged' | 'removal' | 'widening'
+	changes: AccessChangeDto[]
+	/** The digest of the run's snapshot and of the active one it was compared with: an approval is bound to both. */
+	candidateDigest: string
+	baselineDigest: string
+	/** The published run the change was compared with; null when nothing was published. */
+	baselineRunId: string | null
+	protected: boolean
+	/** The human who approved it, once one did. */
+	approval: { principalId: string; label: string; approvedAt: number } | null
+}
+
+/** Approve or refuse one parked run. The digests are the ones the approver read; a reclassified run refuses them. */
+export interface CompleteApprovalRequest {
+	runId: string
+	decision: 'approve' | 'reject'
+	candidateDigest: string
+	baselineDigest: string
+}
+
+/** Change whether a widening waits for approval on one environment (ADR-0050 §4). */
+export interface SetEnvironmentProtectionRequest {
+	appId: string
+	env: string
+	protected: boolean
+}
+
 export interface TriggerDeployRequest {
 	appId: string
 	env: string
@@ -410,6 +481,7 @@ export type {
 	AppNamedValueInput,
 	ControlRpcContract,
 	CreateAppRequest,
+	DescribeConnectorRequest,
 	GitHubSourceConnectionInput,
 	GitHubSourceConnectionRpcContract,
 	NamespaceIdInput,
@@ -422,4 +494,5 @@ export type {
 	SecretValueInput,
 	SecretValueResponse,
 	TailRunInput,
+	UpdateNamespaceInput,
 } from './rpc.js'

package/src/rpc.ts

@@ -1,4 +1,5 @@
 import type { RpcProcedureContract } from '@fabrika/app'
+import type { ExportDescription } from '@fabrika/auth-core'
 import type { BuilderConnectionReceiptDto, CreateBuilderConnectionReceiptRequest, GetBuilderConnectionReceiptRequest } from './builder-connections.js'
 import type {
 	ApproveDeviceAuthorizationResult,
@@ -14,8 +15,10 @@ import type {
 	AdoptDeploymentNamespaceRequest,
 	AppDto,
 	AppEnvDto,
+	ApprovalDto,
 	AppSecretDto,
 	AppVarDto,
+	CompleteApprovalRequest,
 	CreateDeploymentNamespaceRequest,
 	CursorList,
 	DeploymentNamespaceDetailDto,
@@ -36,10 +39,12 @@ import type {
 	RunDto,
 	RunLogResponse,
 	RunTailResponse,
+	SetEnvironmentProtectionRequest,
 	StartGitHubSourceConnectionRequest,
 	StartGitHubSourceConnectionResponse,
 	TriggerDeployRequest,
 	UpdateAppRequest,
+	UpdateDeploymentNamespaceRequest,
 } from './index.js'
 
 type RpcProcedure<TInput, TOutput> = RpcProcedureContract<TInput, TOutput>
@@ -95,6 +100,10 @@ export interface AdoptNamespaceInput extends NamespaceIdInput {
 	readonly namespace: AdoptDeploymentNamespaceRequest
 }
 
+export interface UpdateNamespaceInput extends NamespaceIdInput {
+	readonly namespace: UpdateDeploymentNamespaceRequest
+}
+
 export interface RunListInput {
 	readonly appId?: string
 	readonly env?: string
@@ -148,6 +157,8 @@ export interface ControlRpcContract {
 			list: RpcProcedure<AppIdInput, ListResponse<AppEnvDto>>
 			put: RpcProcedure<PutAppEnvironmentInput, AppEnvDto>
 			delete: RpcProcedure<AppEnvironmentInput, OkResponse>
+			/** Human user principals with `access.approve` only, from the console (ADR-0050 §4). */
+			protect: RpcProcedure<SetEnvironmentProtectionRequest, AppEnvDto>
 		}
 		secrets: {
 			list: RpcProcedure<AppIdInput, ListResponse<AppSecretDto>>
@@ -172,6 +183,8 @@ export interface ControlRpcContract {
 		create: RpcProcedure<CreateDeploymentNamespaceRequest, DeploymentNamespaceDetailDto>
 		adopt: RpcProcedure<AdoptNamespaceInput, DeploymentNamespaceDetailDto>
 		reconcile: RpcProcedure<NamespaceIdInput, DeploymentNamespaceDetailDto>
+		/** Change a ready namespace in place, synchronously (backlog 79); also the retry after an unconfirmed update. */
+		update: RpcProcedure<UpdateNamespaceInput, DeploymentNamespaceDetailDto>
 		/** Free a namespace id. Refused while any app environment is registered in it (backlog 73). */
 		remove: RpcProcedure<NamespaceIdInput, RemoveDeploymentNamespaceResponse>
 	}
@@ -182,6 +195,29 @@ export interface ControlRpcContract {
 		tail: RpcProcedure<TailRunInput, RunTailResponse>
 		cancel: RpcProcedure<RunIdInput, RunDto>
 	}
+	/** Runs whose access change waits for a human (ADR-0050 §5), behind `access.approve`. */
+	approvals: {
+		list: RpcProcedure<void, ListResponse<ApprovalDto>>
+		get: RpcProcedure<RunIdInput, ApprovalDto>
+		/** A human user principal, from the console's own origin; no key, service or OAuth token completes one. */
+		complete: RpcProcedure<CompleteApprovalRequest, ApprovalDto>
+	}
 	deploy: RpcProcedure<TriggerDeployRequest, RunDto>
 	register: RpcProcedure<RegisterAppRequest, RegisterAppResponse>
+	/** What a consumer vendors (`fabrika connect add`): the export its owner's environment approved for it. */
+	connectors: {
+		describe: RpcProcedure<DescribeConnectorRequest, ExportDescription>
+	}
+}
+
+/**
+ * One export version of `app` as the environment `env` approved it, read for its consumer `consumer`. Unknown, not
+ * approved, or not exported to that consumer: 404 alike.
+ */
+export interface DescribeConnectorRequest {
+	readonly consumer: string
+	readonly env: string
+	readonly app: string
+	readonly export: string
+	readonly version: number
 }