@fabrika/provider-contract 0.3.3 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-contract",
-	"version": "0.3.3",
+	"version": "0.4.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -31,6 +31,6 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "^0.3.3"
+		"@fabrika/auth-core": "^0.4.1"
 	}
 }

package/src/control.ts

@@ -1,3 +1,4 @@
+import type { AppSchema, ContractArtifact } from '@fabrika/auth-core'
 import type { JsonValue, ProviderEnvelope } from './json'
 
 /** Events whose persistence and presentation belong to the control plane. */
@@ -40,6 +41,18 @@ export interface ProviderDeploymentNamespace {
 	readonly target: ProviderEnvelope
 }
 
+/**
+ * The access Control approved for one application environment (ADR-0050): the contract the proxy enforces and the
+ * IAM vocabulary compiled from it. A provider publishes a contract application's endpoint table and reconciles its
+ * IAM schema from this, never from the artifact or a runner's report.
+ */
+export interface ProviderApprovedAccess {
+	readonly contract: ContractArtifact
+	/** `contractDigest(contract)`, which the application compares with `FABRIKA_CONTRACT_DIGEST` at startup. */
+	readonly contractDigest: string
+	readonly schema: AppSchema
+}
+
 /** Persisted deploy data for one app environment. */
 export interface ProviderEnvironment {
 	readonly appId: string
@@ -50,6 +63,11 @@ export interface ProviderEnvironment {
 	readonly namespace?: ProviderDeploymentNamespace
 	readonly target: ProviderEnvelope
 	readonly artifact: ProviderEnvelope
+	/**
+	 * The environment's approved contract, from Control's `approvedSnapshot`. Absent when nothing is approved: then a
+	 * provider publishes no endpoint table and reconciles no IAM schema, whatever the artifact claims (ADR-0050).
+	 */
+	readonly access?: ProviderApprovedAccess
 }
 
 /** Raw registration data passed to provider-owned validation and normalization. */
@@ -272,6 +290,18 @@ export interface ProviderNamespaceMember {
 	readonly env: string
 	readonly domain?: string
 	readonly artifact: ProviderEnvelope
+	/**
+	 * The secret the namespace proxy authenticates itself to this application environment with (ADR-0022 rule 5).
+	 * Control generates it once and keeps it in its vault; absent when Control has no vault.
+	 */
+	readonly proxySecret?: string
+	/**
+	 * The origin of this environment's active Operations ingest DSN, never the DSN itself: a contract application's
+	 * proxy admits it in `connect-src`, as the framework does. Absent while the environment has no active ingest.
+	 */
+	readonly operationsOrigin?: string
+	/** See `ProviderEnvironment.access`: the proxy table of a contract application comes only from here. */
+	readonly access?: ProviderApprovedAccess
 }
 
 /** One idempotent namespace lifecycle invocation. */
@@ -295,6 +325,51 @@ export interface ProviderNamespaceRepublishInput extends ProviderNamespaceMutati
 	readonly wait: 'started' | 'active'
 }
 
+/**
+ * The `code` of a `ProviderNamespaceError` an update plan throws when the requested target changes
+ * something the provider cannot move in place. Core answers it as a conflict that names the supported path.
+ */
+export const PROVIDER_NAMESPACE_IMMUTABLE = 'namespaceImmutable'
+
+/**
+ * The `code` of a `ProviderNamespaceError` an update apply throws when the live change MAY have been made
+ * and is not confirmed. Any other failure means nothing changed. Applying the same plan again must converge.
+ */
+export const PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED = 'namespaceUpdateUnconfirmed'
+
+/** One provider-described change, safe to audit: names and values only, never a credential. */
+export interface ProviderNamespaceChange {
+	readonly field: string
+	readonly from: string | null
+	readonly to: string
+}
+
+/** The validated result of merging a requested target over the stored one. `change` is null for a no-op. */
+export interface ProviderNamespaceUpdatePlan {
+	readonly namespace: ProviderDeploymentNamespace
+	readonly change: ProviderNamespaceChange | null
+}
+
+/** Apply one plan. `next` is the planned namespace, with the same coordinates as `namespace`. */
+export interface ProviderNamespaceUpdateInput {
+	readonly namespace: ProviderDeploymentNamespace
+	readonly next: ProviderDeploymentNamespace
+	/** The namespace an earlier, unconfirmed update planned; the live resources may already match it. */
+	readonly unconfirmed?: ProviderDeploymentNamespace
+	readonly signal: AbortSignal
+}
+
+/** In-place change of a settled namespace. */
+export interface ProviderNamespaceUpdates {
+	/**
+	 * Merge `requested` — whose payload may name only what changes — over the stored `namespace` and
+	 * validate the result. Pure. A change that cannot be made in place throws `PROVIDER_NAMESPACE_IMMUTABLE`.
+	 */
+	plan(namespace: ProviderDeploymentNamespace, requested: ProviderEnvelope): ProviderNamespaceUpdatePlan
+	/** Move the live resources to `next` and return the target core stores. */
+	apply(input: ProviderNamespaceUpdateInput): Promise<ProviderDeploymentNamespace>
+}
+
 /** One registration whose provider coordinates do not exist until namespace services are prepared. */
 export interface ProviderRegistrationPreparationInput {
 	readonly registration: ProviderRegistration
@@ -382,6 +457,8 @@ export interface ProviderNamespaceCapabilities {
 	reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>
 	/** Absent means the namespace has no entry point that follows its members. */
 	republish?(input: ProviderNamespaceRepublishInput): Promise<ProviderNamespaceRepublishResult>
+	/** Absent means the provider changes no namespace in place. */
+	readonly updates?: ProviderNamespaceUpdates
 	readonly operator?: ProviderNamespaceOperator
 }
 
@@ -413,4 +490,10 @@ export interface ControlProvider {
 	 * manifest — constrains what an operator may set.
 	 */
 	declaredVariables?(input: { readonly artifact: ProviderEnvelope }): readonly string[] | undefined
+	/**
+	 * The repository-relative directory this provider executes the application from, normalized as its execution
+	 * normalizes it (`''` for the repository root), or null for a root execution refuses. Control reads the run's
+	 * access snapshot there (ADR-0050). Absent means the repository root.
+	 */
+	applicationRoot?(source: ProviderSource): string | null
 }