@fabrika/control-contract 0.5.3 → 0.5.5

package/package.json

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

package/src/index.ts

@@ -1,3 +1,4 @@
+import type { EndpointKind, EndpointMethod } from '@fabrika/auth-core'
 import type { JsonValue, ProviderEnvelope } from '@fabrika/provider-contract'
 import { z } from 'zod'
 
@@ -224,6 +225,8 @@ export interface AppEnvDto {
 	 * sites declare and the database code its migrations declare. Listed whether or not the environment is protected.
 	 */
 	deviationSubjects: DeviationSubjectDto[]
+	/** The published snapshot's endpoints as the outside reaches them, most exposed first; empty until a run publishes one. */
+	surface: SurfaceEndpointDto[]
 	namespaceId: string | null
 	provider: string
 	target: ProviderEnvelopeDto
@@ -239,6 +242,27 @@ export interface DeviationSubjectDto {
 	steps: string[]
 }
 
+/** Who reaches an endpoint, most exposed first. */
+export const SURFACE_REACHES = ['anyone', 'link', 'app', 'machine', 'human'] as const
+
+/** An endpoint is listed under its most exposed caller: `anyone` for an anonymous kind, `app` for an `app:<id>` caller. */
+export type SurfaceReach = (typeof SURFACE_REACHES)[number]
+
+/** One endpoint of a published snapshot, in the approval's words. */
+export interface SurfaceEndpointDto {
+	id: string
+	method: EndpointMethod
+	path: string
+	kind: EndpointKind
+	reach: SurfaceReach
+	/** Every caller kind the endpoint admits; empty for an anonymous kind. */
+	callers: string[]
+	/** What a caller must hold: `who are members` or `` with `notes.read` (on `note`) ``; null for an anonymous kind. */
+	requirement: string | null
+	/** What else opens the endpoint: another origin, a file it answers, a body limit, a form's protection, a signature. */
+	notes: string[]
+}
+
 export interface PutAppEnvRequest {
 	domain?: string | null
 	publicOrigin?: string | null
@@ -459,19 +483,23 @@ export interface RunDto {
 }
 
 /**
- * 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.
+ * One plain-language line of an access change. `effect` is `widens` when it can grant access the baseline did not,
+ * `narrows` when it can only take access away, and `neutral` when it admits no one new and takes nothing away.
+ * `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
+	effect: 'widens' | 'narrows' | 'neutral'
 	line: string
 	review?: 'closer'
+	/** The line opens an endpoint to the pages on the origins the environment lists; `ApprovalDto.crossOrigins` names them. */
+	environmentOrigins?: true
 }
 
 /** A run's access change against its environment's active snapshot (ADR-0050 §3). */
 export interface ApprovalDto {
 	run: RunDto
-	outcome: 'unchanged' | 'removal' | 'widening'
+	/** `none`: no line. `no-widening`: lines that narrow or leave access unchanged; it publishes at once. */
+	outcome: 'none' | 'no-widening' | '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
@@ -479,6 +507,13 @@ export interface ApprovalDto {
 	/** The published run the change was compared with; null when nothing was published. */
 	baselineRunId: string | null
 	protected: boolean
+	/**
+	 * The environment's cross-origin list as it stands now: the pages an endpoint the contract opens to the environment's
+	 * list answers. It is set on the environment, takes effect at once, and no approval covers it (ADR-0050). Only on one
+	 * approval read while the run waits for a decision, its environment exists and a line has `environmentOrigins`;
+	 * empty when the environment lists none.
+	 */
+	crossOrigins?: string[]
 	/** The human who approved it, once one did. */
 	approval: { principalId: string; label: string; approvedAt: number } | null
 }