@fabrika/provider-contract 0.9.0-dev.1 → 0.9.0-dev.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/provider-contract",
3
- "version": "0.9.0-dev.1",
3
+ "version": "0.9.0-dev.10",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -12,18 +12,29 @@
12
12
  },
13
13
  "files": [
14
14
  "src",
15
- "!src/**/__tests__/**"
15
+ "!src/**/__tests__/**",
16
+ "types"
16
17
  ],
17
18
  "exports": {
18
19
  ".": {
19
20
  "bun": "./src/index.ts",
20
- "types": "./src/index.ts",
21
+ "types": "./types/src/index.d.ts",
21
22
  "default": "./src/index.ts"
22
23
  },
23
24
  "./installation": {
24
25
  "bun": "./src/installation.ts",
25
- "types": "./src/installation.ts",
26
+ "types": "./types/src/installation.d.ts",
26
27
  "default": "./src/installation.ts"
28
+ },
29
+ "./app-cli": {
30
+ "bun": "./src/app-cli.ts",
31
+ "types": "./types/src/app-cli.d.ts",
32
+ "default": "./src/app-cli.ts"
33
+ },
34
+ "./conformance": {
35
+ "bun": "./src/conformance.ts",
36
+ "types": "./types/src/conformance.d.ts",
37
+ "default": "./src/conformance.ts"
27
38
  }
28
39
  },
29
40
  "scripts": {
@@ -31,6 +42,7 @@
31
42
  "test": "bun test"
32
43
  },
33
44
  "dependencies": {
34
- "@fabrika/auth-core": "0.9.0-dev.1"
45
+ "@fabrika/auth-core": "0.9.0-dev.10",
46
+ "@fabrika/proxy-core": "0.9.0-dev.10"
35
47
  }
36
48
  }
package/src/app-cli.ts ADDED
@@ -0,0 +1,81 @@
1
+ // What a provider's `/cli` module offers the `fabrika` command for an application: `app build`, `app deploy`,
2
+ // `app register` and `fabrika namespace`. The command loads the module by the provider's id and never branches on it.
3
+
4
+ import type { ProviderDeploymentNamespace, ProviderNamespacePlan } from './control'
5
+
6
+ /** The runtime a contract application's generated entry is written for (`@fabrika/app/build`'s `EntryRuntime`). */
7
+ export type AppEntryRuntime = 'bun' | 'cloudflare'
8
+
9
+ /** What a namespace command asks of Control. The `fabrika` command holds the Control origin, the credential and the transport. */
10
+ export interface NamespaceControl {
11
+ create(namespace: ProviderDeploymentNamespace): Promise<unknown>
12
+ adopt(namespace: ProviderDeploymentNamespace): Promise<unknown>
13
+ reconcile(namespaceId: string): Promise<unknown>
14
+ }
15
+
16
+ /** A plan, or the namespace Control answered with; the `fabrika` command validates and prints either. */
17
+ export type NamespaceCommandResult = { readonly plan: ProviderNamespacePlan } | { readonly namespace: unknown }
18
+
19
+ export interface NamespaceCommandContext {
20
+ readonly source: Readonly<Record<string, string | undefined>>
21
+ /** Reads the Control origin and credential, and throws when either is missing: call it after every other input is checked. */
22
+ control(): NamespaceControl
23
+ }
24
+
25
+ export interface NamespaceCli {
26
+ readonly usage: string
27
+ /** `argv` is the command's own arguments, without the router's `--provider` and `--json`. */
28
+ run(subcommand: string, argv: readonly string[], context: NamespaceCommandContext): Promise<NamespaceCommandResult>
29
+ }
30
+
31
+ export interface AppCli {
32
+ readonly provider: string
33
+ readonly entryRuntime: AppEntryRuntime
34
+ /** `fabrika app build`, after the command wrote a contract application's entry; `contract` says whether it did. */
35
+ build?(argv: readonly string[], context: { readonly contract: boolean }): Promise<void>
36
+ deploy?(argv: readonly string[]): Promise<void>
37
+ /** The text `fabrika app register` hands Control: the application's manifest for one environment. */
38
+ registrationManifest?(options: { readonly config: string; readonly env: string }): Promise<string>
39
+ readonly namespaces?: NamespaceCli
40
+ }
41
+
42
+ export interface AppCliModule {
43
+ readonly appCli: AppCli
44
+ }
45
+
46
+ const optionalFunction = (value: object, key: string): boolean => {
47
+ const member: unknown = Reflect.get(value, key)
48
+ return member === undefined || typeof member === 'function'
49
+ }
50
+
51
+ const isNamespaceCli = (value: unknown): value is NamespaceCli =>
52
+ typeof value === 'object'
53
+ && value !== null
54
+ && 'usage' in value
55
+ && typeof value.usage === 'string'
56
+ && 'run' in value
57
+ && typeof value.run === 'function'
58
+
59
+ export const isAppCli = (value: unknown): value is AppCli =>
60
+ typeof value === 'object'
61
+ && value !== null
62
+ && 'provider' in value
63
+ && typeof value.provider === 'string'
64
+ && value.provider.trim() !== ''
65
+ && 'entryRuntime' in value
66
+ && (value.entryRuntime === 'bun' || value.entryRuntime === 'cloudflare')
67
+ && optionalFunction(value, 'build')
68
+ && optionalFunction(value, 'deploy')
69
+ && optionalFunction(value, 'registrationManifest')
70
+ && (!('namespaces' in value) || value.namespaces === undefined || isNamespaceCli(value.namespaces))
71
+
72
+ /** `specifier` names the module in the error, so an operator knows which package to upgrade. */
73
+ export const appCliFromModule = (value: unknown, expectedProvider: string, specifier: string): AppCli => {
74
+ if (typeof value !== 'object' || value === null || !('appCli' in value) || !isAppCli(value.appCli)) {
75
+ throw new Error(`${specifier} must export a valid \`appCli\`; a provider release older than this CLI has none`)
76
+ }
77
+ if (value.appCli.provider !== expectedProvider) {
78
+ throw new Error(`${specifier} provides "${value.appCli.provider}", expected "${expectedProvider}"`)
79
+ }
80
+ return value.appCli
81
+ }
@@ -0,0 +1,221 @@
1
+ // The cases every `ControlProvider` passes, whatever cloud it deploys to. A provider's own test file calls
2
+ // `describeControlProviderConformance` once with a harness over its fake cloud: the harness builds the provider and a
3
+ // deploy its cloud accepts, and reports what the cloud was asked to change and to stop.
4
+
5
+ import { describe, expect, test } from 'bun:test'
6
+ import {
7
+ type ControlProvider,
8
+ type ProviderDeployInput,
9
+ type ProviderDeployOutcome,
10
+ ProviderInvocationAbort,
11
+ type ProviderRunEvents,
12
+ } from './control'
13
+ import type { JsonValue } from './json'
14
+
15
+ /** What the suite hands a fake cloud: `accepted` is called once the cloud has taken the deploy's operation. */
16
+ export interface ConformanceCloudHooks {
17
+ accepted(): void
18
+ }
19
+
20
+ /** One provider over one fresh fake cloud. */
21
+ export interface ConformanceCloud {
22
+ readonly provider: ControlProvider
23
+ /** A deploy the fake cloud accepts and lets succeed. Each case sets `dryRun`, `signal` and `events` itself. */
24
+ readonly input: Omit<ProviderDeployInput, 'dryRun' | 'signal' | 'events'>
25
+ /** The credentials the provider holds itself (a cloud token, a signed URL); no event may carry one. */
26
+ readonly credentials: readonly string[]
27
+ /** Every request that changed the cloud: a write, a created resource, started work. A preview the cloud runs is none. */
28
+ mutations(): readonly string[]
29
+ /** Every request to stop or remove the deploy's work: a cancelled build or job, a deleted version. */
30
+ stops(): readonly string[]
31
+ }
32
+
33
+ export interface ControlProviderConformanceHarness {
34
+ /** Called once per case, and once per event in the lease-loss sweep. */
35
+ create(hooks: ConformanceCloudHooks): ConformanceCloud
36
+ }
37
+
38
+ /** A secret the suite adds to every deploy; no event may carry it. */
39
+ const SECRET_NAME = 'CONFORMANCE_SECRET'
40
+ const SECRET_VALUE = 'conformance-secret-value-7f3a9c'
41
+
42
+ /** What a deploy reported through its events, as Control would have persisted it. */
43
+ interface Recorded {
44
+ readonly logs: string[]
45
+ readonly externalIds: Array<{ readonly id: string; readonly state?: JsonValue }>
46
+ readonly checkpoints: JsonValue[]
47
+ /** Events that hold the lease: `boundary`, `externalId` and `checkpoint`, in order. */
48
+ events: number
49
+ /** A state Control could not store as given; collected, because a provider may swallow what an event throws. */
50
+ readonly violations: string[]
51
+ }
52
+
53
+ interface Invocation {
54
+ readonly input: ProviderDeployInput
55
+ readonly recorded: Recorded
56
+ /** Lose the lease as Control does: the signal aborts, and every later event rejects with the same reason. */
57
+ loseLease(): void
58
+ readonly signal: AbortSignal
59
+ }
60
+
61
+ const LEASE_LOST = new ProviderInvocationAbort('lease_lost')
62
+
63
+ /** `lostAt`: the lease goes at this event (1-based), which rejects like every one after it. */
64
+ function invocation(cloud: ConformanceCloud, dryRun: boolean, options: { readonly lostAt?: number } = {}): Invocation {
65
+ const controller = new AbortController()
66
+ const recorded: Recorded = { logs: [], externalIds: [], checkpoints: [], events: 0, violations: [] }
67
+ const loseLease = (): void => {
68
+ if (!controller.signal.aborted) controller.abort(LEASE_LOST)
69
+ }
70
+ const held = async (): Promise<void> => {
71
+ recorded.events += 1
72
+ if (recorded.events === options.lostAt) loseLease()
73
+ if (controller.signal.aborted) throw controller.signal.reason
74
+ }
75
+ const stored = (kind: string, state: JsonValue): JsonValue => {
76
+ const parsed: JsonValue = JSON.parse(JSON.stringify(state))
77
+ if (!Bun.deepEquals(parsed, state, true)) recorded.violations.push(`${kind} state is not JSON as given`)
78
+ return parsed
79
+ }
80
+ const events: ProviderRunEvents = {
81
+ log: (line) => {
82
+ recorded.logs.push(line)
83
+ },
84
+ externalId: async (id, state) => {
85
+ await held()
86
+ recorded.externalIds.push(state === undefined ? { id } : { id, state: stored('externalId', state) })
87
+ },
88
+ checkpoint: async (state) => {
89
+ await held()
90
+ recorded.checkpoints.push(stored('checkpoint', state))
91
+ },
92
+ boundary: held,
93
+ }
94
+ const input: ProviderDeployInput = {
95
+ ...cloud.input,
96
+ secrets: { ...cloud.input.secrets, [SECRET_NAME]: SECRET_VALUE },
97
+ dryRun,
98
+ signal: controller.signal,
99
+ events,
100
+ }
101
+ return { input, recorded, loseLease, signal: controller.signal }
102
+ }
103
+
104
+ /**
105
+ * The deploy's outcome, or the reason it rejected with. A step a provider stops waiting for may still run, so the
106
+ * cloud is read only after the tasks already queued have run.
107
+ */
108
+ async function settle(provider: ControlProvider, input: ProviderDeployInput): Promise<ProviderDeployOutcome | { readonly rejected: unknown }> {
109
+ let outcome: ProviderDeployOutcome | { readonly rejected: unknown }
110
+ try {
111
+ outcome = await provider.deploy(input)
112
+ } catch (error) {
113
+ outcome = { rejected: error }
114
+ }
115
+ await new Promise((resolve) => setTimeout(resolve, 0))
116
+ return outcome
117
+ }
118
+
119
+ /** No event carried a credential: the deploy's secrets, its credential managed entries, the upload bearer, the provider's own. */
120
+ function expectCredentialFree(cloud: ConformanceCloud, run: Invocation): void {
121
+ const { input } = run
122
+ const managed = Object.values(input.managedEnvironment).flatMap((entry) => entry.credential && entry.value !== null ? [entry.value] : [])
123
+ const bearer = input.artifactUpload === undefined ? [] : [input.artifactUpload.bearer]
124
+ const reported = JSON.stringify({ logs: run.recorded.logs, externalIds: run.recorded.externalIds, checkpoints: run.recorded.checkpoints })
125
+ for (const credential of [...Object.values(input.secrets), ...managed, ...bearer, ...cloud.credentials]) {
126
+ expect(reported).not.toContain(credential)
127
+ }
128
+ expect(run.recorded.violations).toEqual([])
129
+ }
130
+
131
+ export function describeControlProviderConformance(name: string, harness: ControlProviderConformanceHarness): void {
132
+ const quiet = (): ConformanceCloud => harness.create({ accepted: () => {} })
133
+
134
+ describe(`${name} conforms to ControlProvider`, () => {
135
+ test('a deploy succeeds, and nothing it reports carries a credential', async () => {
136
+ const cloud = quiet()
137
+ const run = invocation(cloud, false)
138
+ expect(await settle(cloud.provider, run.input)).toMatchObject({ state: 'succeeded' })
139
+ expect(cloud.mutations().length).toBeGreaterThan(0)
140
+ expect(cloud.stops()).toEqual([])
141
+ expectCredentialFree(cloud, run)
142
+ })
143
+
144
+ test('a dry run succeeds, changes nothing in the cloud, and reports no credential', async () => {
145
+ const cloud = quiet()
146
+ const run = invocation(cloud, true)
147
+ expect(await settle(cloud.provider, run.input)).toMatchObject({ state: 'succeeded' })
148
+ expect(cloud.mutations()).toEqual([])
149
+ expect(cloud.stops()).toEqual([])
150
+ expectCredentialFree(cloud, run)
151
+ })
152
+
153
+ test('an invocation whose lease is gone at its first event changes nothing in the cloud', async () => {
154
+ const cloud = quiet()
155
+ const run = invocation(cloud, false, { lostAt: 1 })
156
+ expect(await settle(cloud.provider, run.input)).not.toMatchObject({ state: 'succeeded' })
157
+ expect(cloud.mutations()).toEqual([])
158
+ expect(cloud.stops()).toEqual([])
159
+ })
160
+
161
+ test('a lease lost at any event of a deploy stops nothing, and the deploy claims no success', async () => {
162
+ const cloud = quiet()
163
+ const complete = invocation(cloud, false)
164
+ await settle(cloud.provider, complete.input)
165
+ expect(complete.recorded.events).toBeGreaterThan(0)
166
+ for (let lostAt = 1; lostAt <= complete.recorded.events; lostAt += 1) {
167
+ const lost = quiet()
168
+ const run = invocation(lost, false, { lostAt })
169
+ const outcome = await settle(lost.provider, run.input)
170
+ // The cloud may still finish the work; this invocation may not claim it, and may not stop it.
171
+ expect({ lostAt, outcome }).not.toMatchObject({ outcome: { state: 'succeeded' } })
172
+ expect({ lostAt, stops: lost.stops() }).toEqual({ lostAt, stops: [] })
173
+ expectCredentialFree(lost, run)
174
+ }
175
+ })
176
+
177
+ test('a lease lost once the cloud accepted the deploy stops nothing, in the deploy, a reconcile or a cancel', async () => {
178
+ let run: Invocation | undefined
179
+ let accepted = false
180
+ const cloud = harness.create({
181
+ accepted: () => {
182
+ accepted = true
183
+ run?.loseLease()
184
+ },
185
+ })
186
+ run = invocation(cloud, false)
187
+ const outcome = await settle(cloud.provider, run.input)
188
+ expect(accepted).toBe(true)
189
+ expect(outcome).not.toMatchObject({ state: 'succeeded' })
190
+ expect(cloud.stops()).toEqual([])
191
+
192
+ // Control reconciles and cancels a run by what its last owner recorded.
193
+ const recordedId = run.recorded.externalIds[0]
194
+ if (recordedId === undefined) throw new Error('the deploy recorded no external id before its operation was accepted')
195
+ const providerState = run.recorded.checkpoints.at(-1) ?? recordedId.state
196
+ const reference = {
197
+ runId: run.input.runId,
198
+ externalId: recordedId.id,
199
+ environment: run.input.environment,
200
+ signal: run.signal,
201
+ ...(providerState === undefined ? {} : { providerState }),
202
+ }
203
+ const mutations = cloud.mutations().length
204
+ await cloud.provider.reconcile?.(reference).catch(() => {})
205
+ await cloud.provider.cancel?.(reference).catch(() => {})
206
+ await new Promise((resolve) => setTimeout(resolve, 0))
207
+ expect(cloud.stops()).toEqual([])
208
+ expect(cloud.mutations()).toHaveLength(mutations)
209
+ })
210
+
211
+ test('a registration normalizes to itself, and its envelopes survive JSON', () => {
212
+ const cloud = quiet()
213
+ const normalize = cloud.provider.normalizeRegistration
214
+ if (normalize === undefined) return
215
+ const once = normalize({ app: cloud.input.app, environment: cloud.input.environment })
216
+ expect(normalize(once)).toEqual(once)
217
+ expect(JSON.parse(JSON.stringify(once.environment.target))).toEqual(once.environment.target)
218
+ expect(JSON.parse(JSON.stringify(once.environment.artifact))).toEqual(once.environment.artifact)
219
+ })
220
+ })
221
+ }
package/src/control.ts CHANGED
@@ -1,4 +1,5 @@
1
- import type { AppSchema, ContractArtifact } from '@fabrika/auth-core'
1
+ import type { ApplicationObjects, AppSchema, ContractArtifact, ManagedEnvironment } from '@fabrika/auth-core'
2
+ import type { InstallationBrand } from '@fabrika/proxy-core/brand'
2
3
  import type { JsonValue, ProviderEnvelope } from './json'
3
4
 
4
5
  /** Events whose persistence and presentation belong to the control plane. */
@@ -15,8 +16,11 @@ export interface ProviderRunEvents {
15
16
  boundary(): Promise<void>
16
17
  }
17
18
 
18
- /** Complete platform-owned runtime state. A null value removes the key from persistent targets. */
19
- export type ProviderManagedEnvironment = Readonly<Record<string, string | null>>
19
+ /**
20
+ * Complete platform-owned runtime state, parsed by Control (`parseManagedEnvironment`). A provider writes each entry as
21
+ * a secret when it is a `credential`, removes one whose value is null, and removes the stale ones `staleManagedVariables` names.
22
+ */
23
+ export type ProviderManagedEnvironment = ManagedEnvironment
20
24
 
21
25
  /** Provider-neutral coordinates for obtaining one app revision. */
22
26
  export interface ProviderSource {
@@ -41,8 +45,7 @@ export interface ProviderDeploymentNamespace {
41
45
  readonly target: ProviderEnvelope
42
46
  }
43
47
 
44
- /** A framework release as npm publishes it; the only form one may take before it reaches a generated build command. */
45
- export const FRAMEWORK_RELEASE_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
48
+ export { FRAMEWORK_RELEASE_PATTERN } from '@fabrika/auth-core'
46
49
 
47
50
  /**
48
51
  * The access Control approved for one application environment (ADR-0050): the contract the proxy enforces and the
@@ -64,6 +67,12 @@ export interface ProviderApprovedAccess {
64
67
  * the framework minor it pins (ADR-0062). Its build checks with that release.
65
68
  */
66
69
  readonly checker: string
70
+ /**
71
+ * The `@fabrika/app` release the application's `bun.lock` pins (`FRAMEWORK_RELEASE_PATTERN`), which a release gate
72
+ * reads: `checker` is this platform's patch of that minor, newer than a prerelease pin. Absent in an access Control
73
+ * approved before it recorded the pin.
74
+ */
75
+ readonly framework?: string
67
76
  }
68
77
 
69
78
  /**
@@ -87,12 +96,18 @@ export interface ProviderEnvironment {
87
96
  * application's proxy manifest entry as `crossOrigins`.
88
97
  */
89
98
  readonly crossOrigins?: readonly string[]
99
+ /**
100
+ * The origin of the environment's active Operations ingest DSN, never the DSN: a contract application's proxy admits
101
+ * it in `connect-src`. Control sets it on a deploy; absent while the environment has no active ingest.
102
+ */
103
+ readonly operationsOrigin?: string
90
104
  readonly namespace?: ProviderDeploymentNamespace
91
105
  readonly target: ProviderEnvelope
92
106
  readonly artifact: ProviderEnvelope
93
107
  /**
94
108
  * The environment's approved contract, from Control's `approvedSnapshot`. Absent when nothing is approved: then a
95
109
  * provider publishes no endpoint table and reconciles no IAM schema, whatever the artifact claims (ADR-0050).
110
+ * Control refuses a non-dry deploy without it.
96
111
  */
97
112
  readonly access?: ProviderApprovedAccess
98
113
  }
@@ -146,13 +161,23 @@ export interface ProviderDeployInput {
146
161
  /** Platform-owned runtime configuration, separate from operator-managed application vars. */
147
162
  readonly managedEnvironment: ProviderManagedEnvironment
148
163
  /**
149
- * Every origin IAM may hand this app a session at (ADR-0022). App-wide, not per-environment:
150
- * IAM's registry is keyed by app id, so the set is assembled from every environment of the app.
151
- * Absent when the app has no public origin at all, which leaves IAM's registry untouched.
164
+ * The object that serves the environment's ordinary traffic and the objects its ops channel reaches, as Control records
165
+ * them (ADR-0070 §9). A provider whose application runs in no object ignores it; absent, the provider's defaults.
152
166
  */
153
- readonly returnOrigins?: readonly string[]
167
+ readonly applicationObjects?: ApplicationObjects
154
168
  readonly dryRun: boolean
155
169
  readonly sourceBinding?: ProviderSourceBinding
170
+ /**
171
+ * Present on a dev bootstrap: the provider deploys into this workspace's sandbox, which `devSandboxes.ensure` created
172
+ * before the run, and serves it at `origin`. Absent on every other deploy.
173
+ */
174
+ readonly devSandbox?: {
175
+ readonly workspaceId: string
176
+ readonly sandboxId: string
177
+ readonly origin: string
178
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
179
+ readonly sandboxKey: string
180
+ }
156
181
  /** Optional short-lived, run-scoped Operations artifact destination. */
157
182
  readonly artifactUpload?: {
158
183
  readonly url: string
@@ -167,7 +192,10 @@ export interface ProviderDeployInput {
167
192
  readonly events: ProviderRunEvents
168
193
  }
169
194
 
170
- /** A terminal provider operation result. */
195
+ /**
196
+ * A terminal provider operation result. `succeeded` means the version is live: Control then writes the environment's
197
+ * approved IAM schema itself (ADR-0011), so a provider never calls IAM for an application.
198
+ */
171
199
  export interface ProviderTerminalOutcome {
172
200
  readonly state: 'succeeded' | 'failed'
173
201
  readonly exitCode?: number
@@ -230,14 +258,10 @@ export interface ProviderRunReference {
230
258
 
231
259
  export interface ProviderCancelInput extends ProviderRunReference {
232
260
  readonly signal: AbortSignal
233
- /** See `ProviderDeployInput.returnOrigins`; a cancel that settles an activated deploy projects the same set. */
234
- readonly returnOrigins?: readonly string[]
235
261
  }
236
262
 
237
263
  export interface ProviderReconcileInput extends ProviderRunReference {
238
264
  readonly signal: AbortSignal
239
- /** See `ProviderDeployInput.returnOrigins`; a provider that settles a deploy here projects the same set. */
240
- readonly returnOrigins?: readonly string[]
241
265
  /** Append a line to the run's log. */
242
266
  log?(line: string): Promise<void>
243
267
  }
@@ -331,6 +355,24 @@ export interface ProviderNamespaceMember {
331
355
  readonly operationsOrigin?: string
332
356
  /** See `ProviderEnvironment.access`: the proxy table of a contract application comes only from here. */
333
357
  readonly access?: ProviderApprovedAccess
358
+ /**
359
+ * Present for a dev member, which is routed ONLY through these entries (none while it has no sandbox), never through
360
+ * its own `domain` and `access`.
361
+ */
362
+ readonly devSandboxes?: readonly ProviderNamespaceDevSandbox[]
363
+ }
364
+
365
+ /** One workspace sandbox of a `dev` member, which the namespace proxy routes as its own entry. */
366
+ export interface ProviderNamespaceDevSandbox {
367
+ readonly workspaceId: string
368
+ /** The public host the proxy answers the workspace on (`<workspaceId>.<domain>`). */
369
+ readonly host: string
370
+ /** See `ProviderDevSandbox.upstreamHost`. */
371
+ readonly upstreamHost: string
372
+ /** See `ProviderNamespaceMember.proxySecret`: sealed per workspace. */
373
+ readonly proxySecret?: string
374
+ /** The access of the workspace's own published bootstrap run. */
375
+ readonly access: ProviderApprovedAccess
334
376
  }
335
377
 
336
378
  /** One idempotent namespace lifecycle invocation. */
@@ -338,6 +380,16 @@ export interface ProviderNamespaceMutationInput {
338
380
  readonly namespace: ProviderDeploymentNamespace
339
381
  /** Every app environment assigned to the namespace, read under its lease. */
340
382
  readonly members: readonly ProviderNamespaceMember[]
383
+ /**
384
+ * The installation's client logo for the pages the namespace's proxy answers with (ADR-0066), read from IAM for this
385
+ * mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
386
+ */
387
+ readonly brand?: InstallationBrand | null
388
+ /**
389
+ * Present when a member is a `dev` environment: the namespace's sandbox host is provisioned with it as its API key, and
390
+ * see `ProviderDevSandboxInput.sandboxKey`. Absent, the provider provisions no sandbox host.
391
+ */
392
+ readonly sandboxKey?: string
341
393
  readonly signal: AbortSignal
342
394
  readonly events: ProviderNamespaceEvents
343
395
  }
@@ -366,6 +418,18 @@ export const PROVIDER_NAMESPACE_IMMUTABLE = 'namespaceImmutable'
366
418
  */
367
419
  export const PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED = 'namespaceUpdateUnconfirmed'
368
420
 
421
+ /**
422
+ * The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace's sandbox host has no room
423
+ * to create or wake one more sandbox. Nothing changed; it succeeds once another sandbox is parked or removed.
424
+ */
425
+ export const PROVIDER_DEV_CAPACITY = 'devCapacity'
426
+
427
+ /**
428
+ * The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace has no sandbox host yet.
429
+ * Nothing changed; it succeeds once a namespace mutation handed the sandbox host key has created the host.
430
+ */
431
+ export const PROVIDER_DEV_HOST_PENDING = 'devHostPending'
432
+
369
433
  /** One provider-described change, safe to audit: names and values only, never a credential. */
370
434
  export interface ProviderNamespaceChange {
371
435
  readonly field: string
@@ -470,6 +534,19 @@ export interface ProviderNamespaceOperator {
470
534
  present(namespace: ProviderDeploymentNamespace): ProviderNamespacePresentation
471
535
  }
472
536
 
537
+ /** The app-owned claims of one namespace whose resources Control is asked to confirm gone. */
538
+ export interface ProviderClaimedResourcesInput {
539
+ readonly namespace: ProviderDeploymentNamespace
540
+ readonly resourceKeys: readonly string[]
541
+ readonly signal: AbortSignal
542
+ }
543
+
544
+ /** What the provider observed for one claimed resource. */
545
+ export interface ProviderClaimedResource {
546
+ readonly resourceKey: string
547
+ readonly exists: boolean
548
+ }
549
+
473
550
  /** Optional placement lifecycle owned by providers that use deployment namespaces. */
474
551
  export interface ProviderNamespaceCapabilities {
475
552
  normalize(namespace: ProviderDeploymentNamespace): ProviderDeploymentNamespace
@@ -486,24 +563,80 @@ export interface ProviderNamespaceCapabilities {
486
563
  reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>
487
564
  /** Absent means the namespace has no entry point that follows its members. */
488
565
  republish?(input: ProviderNamespaceRepublishInput): Promise<ProviderNamespaceRepublishResult>
566
+ /**
567
+ * Read-only: whether each claimed resource still exists, one answer per key. Throws when it cannot tell, so Control
568
+ * releases a claim only over a resource the provider confirmed gone. Absent means no claim can be released.
569
+ */
570
+ claimedResources?(input: ProviderClaimedResourcesInput): Promise<readonly ProviderClaimedResource[]>
489
571
  /** Absent means the provider changes no namespace in place. */
490
572
  readonly updates?: ProviderNamespaceUpdates
491
573
  readonly operator?: ProviderNamespaceOperator
492
574
  }
493
575
 
494
- /** One call on the service of a `dev` environment, between its bootstrap runs. */
495
- export interface ProviderDevEnvironmentInput {
576
+ export interface ProviderAuthoring {
577
+ /** The file NAMES (no `/`) that configure the provider's deploy; a workspace changes none of them, at any depth. */
578
+ readonly protectedFiles: readonly string[]
579
+ }
580
+
581
+ /** The provider's handle on one workspace sandbox, which Control persists; stable for the workspace's life. */
582
+ export interface ProviderDevSandboxRef {
583
+ readonly sandboxId: string
584
+ }
585
+
586
+ /** One running workspace sandbox of a `dev` environment. */
587
+ export interface ProviderDevSandbox {
588
+ readonly sandboxId: string
589
+ /** The base image the sandbox was created from. */
590
+ readonly baseDigest: string
591
+ /** The Host the namespace proxy sends to reach the sandbox's application port (e.g. `3000-<id>.<box domain>`). */
592
+ readonly upstreamHost: string
593
+ }
594
+
595
+ /** Create a workspace's sandbox, or return the one it already has. */
596
+ export interface ProviderDevSandboxEnsureInput {
496
597
  readonly environment: ProviderEnvironment
598
+ readonly workspaceId: string
599
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
600
+ readonly sandboxKey: string
601
+ readonly signal: AbortSignal
602
+ }
603
+
604
+ /** One lifecycle call on an existing workspace sandbox. */
605
+ export interface ProviderDevSandboxInput {
606
+ readonly environment: ProviderEnvironment
607
+ readonly sandbox: ProviderDevSandboxRef
608
+ /** The bearer of the namespace's sandbox host API, composed by Control from its vault for this call; never persisted or logged. */
609
+ readonly sandboxKey: string
610
+ readonly signal: AbortSignal
611
+ }
612
+
613
+ /** Remove a workspace's sandbox; with no recorded `sandbox`, the one an unrecorded `ensure` may have created. */
614
+ export interface ProviderDevSandboxRemoveInput {
615
+ readonly environment: ProviderEnvironment
616
+ readonly workspaceId: string
617
+ readonly sandbox: ProviderDevSandboxRef | null
618
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
619
+ readonly sandboxKey: string
497
620
  readonly signal: AbortSignal
498
621
  }
499
622
 
500
623
  /**
501
- * The service of a `dev` environment outside a run (ADR-0049): Control stops it after an idle period and starts it on
502
- * the next commit. Files the launcher wrote survive both.
624
+ * The per-workspace sandboxes of a `dev` environment outside a run. Every call is idempotent: `ensure` creates at most
625
+ * one sandbox per `workspaceId` and returns it running, `park` and `wake` converge on their state, and `remove` treats a
626
+ * sandbox already gone as removed. A full sandbox host throws `PROVIDER_DEV_CAPACITY`, a namespace without one yet
627
+ * `PROVIDER_DEV_HOST_PENDING`; `remove` there is a no-op, since no sandbox can exist.
503
628
  */
504
- export interface ProviderDevEnvironments {
505
- stop(input: ProviderDevEnvironmentInput): Promise<void>
506
- start(input: ProviderDevEnvironmentInput): Promise<void>
629
+ export interface ProviderDevSandboxes {
630
+ /**
631
+ * Mutation-free check that the environment's placement can serve a workspace sandbox. Control calls it before it
632
+ * records one, because a recorded sandbox reaches every later republish of the namespace. A refusal is a
633
+ * `ProviderNamespaceError` that is not retryable, whose one-line message the author may read; any other throw is a failure.
634
+ */
635
+ admit(input: { readonly environment: ProviderEnvironment }): void
636
+ ensure(input: ProviderDevSandboxEnsureInput): Promise<ProviderDevSandbox>
637
+ park(input: ProviderDevSandboxInput): Promise<void>
638
+ wake(input: ProviderDevSandboxInput): Promise<void>
639
+ remove(input: ProviderDevSandboxRemoveInput): Promise<void>
507
640
  }
508
641
 
509
642
  /**
@@ -527,8 +660,29 @@ export interface ControlProvider {
527
660
  reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>
528
661
  readonly secrets?: ProviderManagedSecrets
529
662
  readonly namespaces?: ProviderNamespaceCapabilities
663
+ /** MCP authoring (ADR-0049): an environment of this provider can be an authoring target. Absent means none can. */
664
+ readonly authoring?: ProviderAuthoring
665
+ /**
666
+ * Every application environment gets `FABRIKA_PROXY_SECRET`, with or without a namespace proxy: the provider's own
667
+ * hop to the application carries it (Cloudflare's Worker to its Durable Object, ADR-0065). Absent means only a
668
+ * namespace proxy's environments get one.
669
+ */
670
+ readonly applicationHopSecret?: true
530
671
  /** Absent means the provider runs no `dev` environment, and Control refuses one. */
531
- readonly devEnvironments?: ProviderDevEnvironments
672
+ readonly devSandboxes?: ProviderDevSandboxes
673
+ /**
674
+ * Whether an environment at this approved access is served the ops channel through which Control reaches its object
675
+ * (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no
676
+ * release logic. Absent means no environment of this provider is.
677
+ */
678
+ opsChannel?(access: ProviderApprovedAccess): boolean
679
+ /**
680
+ * Whether the object at this approved access, served the ops channel, also holds the maintenance barrier (`state`,
681
+ * `migrate`) and serves Control's data operations: the daily backups, a deploy's migration phase and the side restore
682
+ * (ADR-0069 §3, ADR-0070). A release can serve the channel without them. Absent means no environment of this
683
+ * provider is.
684
+ */
685
+ dataOperations?(access: ProviderApprovedAccess): boolean
532
686
  /** Absent means the provider deploys public sources only. */
533
687
  readonly source?: ProviderSourceCapabilities
534
688
  /**