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

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.
@@ -0,0 +1,628 @@
1
+ import type { ApplicationObjects, AppSchema, ContractArtifact, ManagedEnvironment } from '@fabrika/auth-core';
2
+ import type { InstallationBrand } from '@fabrika/proxy-core/brand';
3
+ import type { JsonValue, ProviderEnvelope } from './json';
4
+ /** Events whose persistence and presentation belong to the control plane. */
5
+ export interface ProviderRunEvents {
6
+ log(line: string): void;
7
+ /** Atomically persist the external operation id and, when supplied, its credential-free checkpoint. */
8
+ externalId(id: string, state?: JsonValue): Promise<void>;
9
+ /** Replace the credential-free checkpoint while this run remains active. */
10
+ checkpoint(state: JsonValue): Promise<void>;
11
+ /**
12
+ * A step boundary: Control checks its lease and reads the run's cancellation request. Rejects with a
13
+ * `ProviderInvocationAbort` after aborting the run's signal. A long step calls it at its own boundaries.
14
+ */
15
+ boundary(): Promise<void>;
16
+ }
17
+ /**
18
+ * Complete platform-owned runtime state, parsed by Control (`parseManagedEnvironment`). A provider writes each entry as
19
+ * a secret when it is a `credential`, removes one whose value is null, and removes the stale ones `staleManagedVariables` names.
20
+ */
21
+ export type ProviderManagedEnvironment = ManagedEnvironment;
22
+ /** Provider-neutral coordinates for obtaining one app revision. */
23
+ export interface ProviderSource {
24
+ readonly repoUrl: string;
25
+ readonly ref: string;
26
+ readonly workerDir?: string;
27
+ readonly buildCommand?: string;
28
+ readonly configPath?: string;
29
+ }
30
+ /** App data needed by a control provider. */
31
+ export interface ProviderApp {
32
+ readonly id: string;
33
+ readonly source: ProviderSource;
34
+ }
35
+ /** One provider-owned placement boundary shared by zero or more app environments. */
36
+ export interface ProviderDeploymentNamespace {
37
+ readonly id: string;
38
+ readonly env: string;
39
+ readonly exclusiveAppId?: string;
40
+ readonly target: ProviderEnvelope;
41
+ }
42
+ export { FRAMEWORK_RELEASE_PATTERN } from '@fabrika/auth-core';
43
+ /**
44
+ * The access Control approved for one application environment (ADR-0050): the contract the proxy enforces and the
45
+ * IAM vocabulary compiled from it. A provider publishes a contract application's endpoint table and reconciles its
46
+ * IAM schema from this, never from the artifact or a runner's report.
47
+ */
48
+ export interface ProviderApprovedAccess {
49
+ /** The contract in this platform release's model, upcast from the application's own release's artifact (ADR-0062). */
50
+ readonly contract: ContractArtifact;
51
+ /**
52
+ * The digest the application's own framework release computes for its contract, which it compares with
53
+ * `FABRIKA_CONTRACT_DIGEST` at startup. It is `contractDigest(contract)` only when the application is on this
54
+ * release's artifact format, so a provider never derives it from `contract`.
55
+ */
56
+ readonly contractDigest: string;
57
+ readonly schema: AppSchema;
58
+ /**
59
+ * The `@fabrika/check` release whose reader read the application (`FRAMEWORK_RELEASE_PATTERN`): the newest patch of
60
+ * the framework minor it pins (ADR-0062). Its build checks with that release.
61
+ */
62
+ readonly checker: string;
63
+ /**
64
+ * The `@fabrika/app` release the application's `bun.lock` pins (`FRAMEWORK_RELEASE_PATTERN`), which a release gate
65
+ * reads: `checker` is this platform's patch of that minor, newer than a prerelease pin. Absent in an access Control
66
+ * approved before it recorded the pin.
67
+ */
68
+ readonly framework?: string;
69
+ }
70
+ /**
71
+ * `dev`: the environment follows a workspace through a platform-owned launcher, which its provider starts instead of the
72
+ * serving entry (ADR-0043). The kind is Control's registry, never the application's.
73
+ */
74
+ export type ProviderEnvironmentKind = 'standard' | 'dev';
75
+ /** Persisted deploy data for one app environment. */
76
+ export interface ProviderEnvironment {
77
+ readonly appId: string;
78
+ readonly env: string;
79
+ /** Absent means `standard`. */
80
+ readonly kind?: ProviderEnvironmentKind;
81
+ readonly domain?: string;
82
+ /** Canonical externally reachable HTTP(S) origin; independent of provider domain routing. */
83
+ readonly publicOrigin?: string;
84
+ /**
85
+ * The exact origins whose pages may call the environment's cross-origin endpoints, as the operator listed them in
86
+ * Control's registry (ADR-0022 "Cross-origin endpoints"). Absent when it lists none. A provider writes them into the
87
+ * application's proxy manifest entry as `crossOrigins`.
88
+ */
89
+ readonly crossOrigins?: readonly string[];
90
+ /**
91
+ * The origin of the environment's active Operations ingest DSN, never the DSN: a contract application's proxy admits
92
+ * it in `connect-src`. Control sets it on a deploy; absent while the environment has no active ingest.
93
+ */
94
+ readonly operationsOrigin?: string;
95
+ readonly namespace?: ProviderDeploymentNamespace;
96
+ readonly target: ProviderEnvelope;
97
+ readonly artifact: ProviderEnvelope;
98
+ /**
99
+ * The environment's approved contract, from Control's `approvedSnapshot`. Absent when nothing is approved: then a
100
+ * provider publishes no endpoint table and reconciles no IAM schema, whatever the artifact claims (ADR-0050).
101
+ * Control refuses a non-dry deploy without it.
102
+ */
103
+ readonly access?: ProviderApprovedAccess;
104
+ }
105
+ /** Raw registration data passed to provider-owned validation and normalization. */
106
+ export interface ProviderRegistrationInput {
107
+ readonly app: ProviderApp;
108
+ readonly environment: ProviderEnvironment;
109
+ }
110
+ /** Canonical registration returned after provider-owned validation and normalization. */
111
+ export type ProviderRegistration = ProviderRegistrationInput;
112
+ /** Provider-neutral input for resolving one requested source ref to an immutable Git object id. */
113
+ export interface ProviderSourceResolutionInput {
114
+ readonly runId: string;
115
+ readonly app: ProviderApp;
116
+ readonly environment: ProviderEnvironment;
117
+ /** An immutable commit already recorded by the trigger, which resolution must verify exactly. */
118
+ readonly expectedCommitSha?: string;
119
+ readonly sourceBinding?: ProviderSourceBinding;
120
+ readonly signal: AbortSignal;
121
+ }
122
+ /** The exact source revision a provider resolved before starting deploy work. */
123
+ export interface ProviderSourceResolution {
124
+ readonly commitSha: string;
125
+ }
126
+ /**
127
+ * Credential-free selector of the GitHub connection and installation that read a private source
128
+ * (ADR-0029). Absent means a public source; an installation id alone never selects a credential.
129
+ */
130
+ export interface ProviderSourceBinding {
131
+ readonly connectionId: string;
132
+ readonly installationId: number;
133
+ }
134
+ /** How private GitHub sources reach a provider (ADR-0029): one keyed connection's App and installation. */
135
+ export interface ProviderSourceCapabilities {
136
+ readonly binding: 'connection';
137
+ }
138
+ /** One control-plane deploy invocation. */
139
+ export interface ProviderDeployInput {
140
+ readonly runId: string;
141
+ readonly app: ProviderApp;
142
+ readonly environment: ProviderEnvironment;
143
+ readonly secrets: Readonly<Record<string, string>>;
144
+ readonly vars: Readonly<Record<string, string>>;
145
+ /** Platform-owned runtime configuration, separate from operator-managed application vars. */
146
+ readonly managedEnvironment: ProviderManagedEnvironment;
147
+ /**
148
+ * The object that serves the environment's ordinary traffic and the objects its ops channel reaches, as Control records
149
+ * them (ADR-0070 §9). A provider whose application runs in no object ignores it; absent, the provider's defaults.
150
+ */
151
+ readonly applicationObjects?: ApplicationObjects;
152
+ readonly dryRun: boolean;
153
+ readonly sourceBinding?: ProviderSourceBinding;
154
+ /**
155
+ * Present on a dev bootstrap: the provider deploys into this workspace's sandbox, which `devSandboxes.ensure` created
156
+ * before the run, and serves it at `origin`. Absent on every other deploy.
157
+ */
158
+ readonly devSandbox?: {
159
+ readonly workspaceId: string;
160
+ readonly sandboxId: string;
161
+ readonly origin: string;
162
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
163
+ readonly sandboxKey: string;
164
+ };
165
+ /** Optional short-lived, run-scoped Operations artifact destination. */
166
+ readonly artifactUpload?: {
167
+ readonly url: string;
168
+ readonly bearer: string;
169
+ readonly appId: string;
170
+ readonly environment: string;
171
+ readonly serviceKey: string;
172
+ readonly release: string;
173
+ readonly runId: string;
174
+ };
175
+ readonly signal: AbortSignal;
176
+ readonly events: ProviderRunEvents;
177
+ }
178
+ /**
179
+ * A terminal provider operation result. `succeeded` means the version is live: Control then writes the environment's
180
+ * approved IAM schema itself (ADR-0011), so a provider never calls IAM for an application.
181
+ */
182
+ export interface ProviderTerminalOutcome {
183
+ readonly state: 'succeeded' | 'failed';
184
+ readonly exitCode?: number;
185
+ /** Whether provider-local release artifacts reached Operations. */
186
+ readonly artifactState?: 'complete' | 'incomplete' | 'not_applicable';
187
+ }
188
+ /** Running means external settlement is unresolved, including an ambiguous submission response. */
189
+ export type ProviderDeployOutcome = ProviderTerminalOutcome | {
190
+ readonly state: 'running';
191
+ };
192
+ /** Settled does not imply rollback: when activation won before cancellation, `outcome` is `succeeded`. */
193
+ export type ProviderCancelOutcome = {
194
+ readonly state: 'pending';
195
+ } | {
196
+ readonly state: 'settled';
197
+ readonly outcome?: 'succeeded' | 'failed';
198
+ };
199
+ /** Losing invocation ownership must never be interpreted as permission to cancel external work. */
200
+ export declare class ProviderInvocationAbort extends Error {
201
+ readonly kind: 'lease_lost' | 'cancel_requested';
202
+ constructor(kind: 'lease_lost' | 'cancel_requested');
203
+ }
204
+ export declare const isLeaseLoss: (reason: unknown) => boolean;
205
+ /** A signal that aborts with `signal`'s reason only when the lease is lost, never on a cancel. */
206
+ export declare const followLeaseLoss: (signal: AbortSignal) => AbortSignal;
207
+ /** Resolve after `ms`, or reject with the signal's reason once it aborts. */
208
+ export declare const abortableWait: (ms: number, signal: AbortSignal) => Promise<void>;
209
+ /** A platform-owned run that can be cancelled or reconciled. */
210
+ export interface ProviderRunReference {
211
+ readonly runId: string;
212
+ readonly externalId: string;
213
+ readonly environment: ProviderEnvironment;
214
+ /** Credential-free provider-owned checkpoint recorded by the run's last owner. */
215
+ readonly providerState?: JsonValue;
216
+ /** When the run started (`started_at`, else `created_at`), in epoch milliseconds; bounds how long a provider polls. */
217
+ readonly startedAtMs?: number;
218
+ }
219
+ export interface ProviderCancelInput extends ProviderRunReference {
220
+ readonly signal: AbortSignal;
221
+ }
222
+ export interface ProviderReconcileInput extends ProviderRunReference {
223
+ readonly signal: AbortSignal;
224
+ /** Append a line to the run's log. */
225
+ log?(line: string): Promise<void>;
226
+ }
227
+ /** The latest state reported while reconciling a platform-owned run. */
228
+ export interface ProviderReconcileOutcome {
229
+ readonly state: 'running' | 'succeeded' | 'failed';
230
+ readonly exitCode?: number;
231
+ /** See `ProviderTerminalOutcome.artifactState`. */
232
+ readonly artifactState?: 'complete' | 'incomplete' | 'not_applicable';
233
+ /** The settled run was a preview: core projects it as a dry run. */
234
+ readonly dryRun?: boolean;
235
+ }
236
+ /** Write one secret value to provider-managed storage. */
237
+ export interface ProviderSecretPutInput {
238
+ readonly environment: ProviderEnvironment;
239
+ readonly name: string;
240
+ readonly value: string;
241
+ }
242
+ /** Remove one secret value from provider-managed storage. */
243
+ export interface ProviderSecretDeleteInput {
244
+ readonly environment: ProviderEnvironment;
245
+ readonly name: string;
246
+ }
247
+ /** Opaque reference persisted by core instead of the provider-managed secret value. */
248
+ export interface ProviderSecretPutResult {
249
+ readonly valueRef: string;
250
+ }
251
+ /** Optional edit-time secret storage owned by a provider. */
252
+ export interface ProviderManagedSecrets {
253
+ put(input: ProviderSecretPutInput): Promise<ProviderSecretPutResult>;
254
+ delete(input: ProviderSecretDeleteInput): Promise<void>;
255
+ }
256
+ /**
257
+ * A namespace lifecycle failure an operator can act on.
258
+ *
259
+ * `code` is a STABLE identifier — a platform error code, or one this provider defines for a lifecycle
260
+ * invariant — so core can record and a console can render the CLASS of a failure instead of matching
261
+ * prose. `message` is the provider's own summary; `detail` carries the upstream's words VERBATIM.
262
+ * Neither is safe to persist as-is: core redacts both before they reach a row or a log, because only
263
+ * core knows what a credential looks like in this installation.
264
+ */
265
+ export declare class ProviderNamespaceError extends Error {
266
+ readonly code: string;
267
+ readonly retryable: boolean;
268
+ readonly detail?: string | undefined;
269
+ constructor(message: string, code: string, retryable: boolean, detail?: string | undefined);
270
+ }
271
+ /**
272
+ * A provider-managed secret write the provider refuses on the app's own terms — a value naming a
273
+ * service the app does not own, say. `message` carries the secret's name and the offending host,
274
+ * never the value, so core may hand it to the caller as a 4xx.
275
+ */
276
+ export declare class ProviderSecretError extends Error {
277
+ readonly code: string;
278
+ constructor(message: string, code: string);
279
+ }
280
+ /** Persist a canonical namespace target immediately after one external mutation succeeds. */
281
+ export interface ProviderNamespaceEvents {
282
+ checkpoint(namespace: ProviderDeploymentNamespace): Promise<void>;
283
+ /** A step boundary: Control checks the namespace lease and, for a deploy, the run's cancellation request. */
284
+ boundary(): Promise<void>;
285
+ }
286
+ /** One app environment assigned to a namespace, as its proxy routes it. */
287
+ export interface ProviderNamespaceMember {
288
+ readonly appId: string;
289
+ readonly env: string;
290
+ readonly domain?: string;
291
+ /** See `ProviderEnvironment.crossOrigins`: the namespace proxy's entry for this member lists them. */
292
+ readonly crossOrigins?: readonly string[];
293
+ readonly artifact: ProviderEnvelope;
294
+ /**
295
+ * The secret the namespace proxy authenticates itself to this application environment with (ADR-0022 rule 5).
296
+ * Control generates it once and keeps it in its vault; absent when Control has no vault.
297
+ */
298
+ readonly proxySecret?: string;
299
+ /**
300
+ * The origin of this environment's active Operations ingest DSN, never the DSN itself: a contract application's
301
+ * proxy admits it in `connect-src`, as the framework does. Absent while the environment has no active ingest.
302
+ */
303
+ readonly operationsOrigin?: string;
304
+ /** See `ProviderEnvironment.access`: the proxy table of a contract application comes only from here. */
305
+ readonly access?: ProviderApprovedAccess;
306
+ /**
307
+ * Present for a dev member, which is routed ONLY through these entries (none while it has no sandbox), never through
308
+ * its own `domain` and `access`.
309
+ */
310
+ readonly devSandboxes?: readonly ProviderNamespaceDevSandbox[];
311
+ }
312
+ /** One workspace sandbox of a `dev` member, which the namespace proxy routes as its own entry. */
313
+ export interface ProviderNamespaceDevSandbox {
314
+ readonly workspaceId: string;
315
+ /** The public host the proxy answers the workspace on (`<workspaceId>.<domain>`). */
316
+ readonly host: string;
317
+ /** See `ProviderDevSandbox.upstreamHost`. */
318
+ readonly upstreamHost: string;
319
+ /** See `ProviderNamespaceMember.proxySecret`: sealed per workspace. */
320
+ readonly proxySecret?: string;
321
+ /** The access of the workspace's own published bootstrap run. */
322
+ readonly access: ProviderApprovedAccess;
323
+ }
324
+ /** One idempotent namespace lifecycle invocation. */
325
+ export interface ProviderNamespaceMutationInput {
326
+ readonly namespace: ProviderDeploymentNamespace;
327
+ /** Every app environment assigned to the namespace, read under its lease. */
328
+ readonly members: readonly ProviderNamespaceMember[];
329
+ /**
330
+ * The installation's client logo for the pages the namespace's proxy answers with (ADR-0066), read from IAM for this
331
+ * mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
332
+ */
333
+ readonly brand?: InstallationBrand | null;
334
+ /**
335
+ * Present when a member is a `dev` environment: the namespace's sandbox host is provisioned with it as its API key, and
336
+ * see `ProviderDevSandboxInput.sandboxKey`. Absent, the provider provisions no sandbox host.
337
+ */
338
+ readonly sandboxKey?: string;
339
+ readonly signal: AbortSignal;
340
+ readonly events: ProviderNamespaceEvents;
341
+ }
342
+ /** `settled` is false while the rebuild is still in flight; core then hands it to a `reconcile` job. */
343
+ export interface ProviderNamespaceRepublishResult {
344
+ readonly namespace: ProviderDeploymentNamespace;
345
+ readonly settled: boolean;
346
+ }
347
+ /** Rebuild a ready namespace's entry point from its current members. */
348
+ export interface ProviderNamespaceRepublishInput extends ProviderNamespaceMutationInput {
349
+ /** `started`: return once the rebuild is submitted. `active`: return once it is live. */
350
+ readonly wait: 'started' | 'active';
351
+ }
352
+ /**
353
+ * The `code` of a `ProviderNamespaceError` an update plan throws when the requested target changes
354
+ * something the provider cannot move in place. Core answers it as a conflict that names the supported path.
355
+ */
356
+ export declare const PROVIDER_NAMESPACE_IMMUTABLE = "namespaceImmutable";
357
+ /**
358
+ * The `code` of a `ProviderNamespaceError` an update apply throws when the live change MAY have been made
359
+ * and is not confirmed. Any other failure means nothing changed. Applying the same plan again must converge.
360
+ */
361
+ export declare const PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED = "namespaceUpdateUnconfirmed";
362
+ /**
363
+ * The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace's sandbox host has no room
364
+ * to create or wake one more sandbox. Nothing changed; it succeeds once another sandbox is parked or removed.
365
+ */
366
+ export declare const PROVIDER_DEV_CAPACITY = "devCapacity";
367
+ /**
368
+ * The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace has no sandbox host yet.
369
+ * Nothing changed; it succeeds once a namespace mutation handed the sandbox host key has created the host.
370
+ */
371
+ export declare const PROVIDER_DEV_HOST_PENDING = "devHostPending";
372
+ /** One provider-described change, safe to audit: names and values only, never a credential. */
373
+ export interface ProviderNamespaceChange {
374
+ readonly field: string;
375
+ readonly from: string | null;
376
+ readonly to: string;
377
+ }
378
+ /** The validated result of merging a requested target over the stored one. `change` is null for a no-op. */
379
+ export interface ProviderNamespaceUpdatePlan {
380
+ readonly namespace: ProviderDeploymentNamespace;
381
+ readonly change: ProviderNamespaceChange | null;
382
+ }
383
+ /** Apply one plan. `next` is the planned namespace, with the same coordinates as `namespace`. */
384
+ export interface ProviderNamespaceUpdateInput {
385
+ readonly namespace: ProviderDeploymentNamespace;
386
+ readonly next: ProviderDeploymentNamespace;
387
+ /** The namespace an earlier, unconfirmed update planned; the live resources may already match it. */
388
+ readonly unconfirmed?: ProviderDeploymentNamespace;
389
+ readonly signal: AbortSignal;
390
+ }
391
+ /** In-place change of a settled namespace. */
392
+ export interface ProviderNamespaceUpdates {
393
+ /**
394
+ * Merge `requested` — whose payload may name only what changes — over the stored `namespace` and
395
+ * validate the result. Pure. A change that cannot be made in place throws `PROVIDER_NAMESPACE_IMMUTABLE`.
396
+ */
397
+ plan(namespace: ProviderDeploymentNamespace, requested: ProviderEnvelope): ProviderNamespaceUpdatePlan;
398
+ /** Move the live resources to `next` and return the target core stores. */
399
+ apply(input: ProviderNamespaceUpdateInput): Promise<ProviderDeploymentNamespace>;
400
+ }
401
+ /** One registration whose provider coordinates do not exist until namespace services are prepared. */
402
+ export interface ProviderRegistrationPreparationInput {
403
+ readonly registration: ProviderRegistration;
404
+ readonly signal: AbortSignal;
405
+ }
406
+ /** One provider-defined operator choice. Core does not interpret its id or description. */
407
+ export interface ProviderNamespacePreset {
408
+ readonly id: string;
409
+ readonly label: string;
410
+ readonly description: string;
411
+ readonly requiresExclusiveApp: boolean;
412
+ }
413
+ /** Provider-neutral coordinates plus opaque provider options for a namespace preview. */
414
+ export interface ProviderNamespacePlanInput {
415
+ readonly id: string;
416
+ readonly env: string;
417
+ readonly preset: string;
418
+ readonly exclusiveAppId?: string;
419
+ readonly options?: JsonValue;
420
+ }
421
+ /** One safe, human-readable provider fact. Values must never contain credentials. */
422
+ export interface ProviderNamespaceFact {
423
+ readonly label: string;
424
+ readonly value: string;
425
+ /**
426
+ * Marks a fact that NAMES A LIVE PROVIDER RESOURCE, not a policy choice. Core deletes no provider
427
+ * resource, so removal has to tell the operator what it stopped tracking — and only the provider
428
+ * knows which of its facts is a real thing with an id. Absent means "not a resource"; a fact is
429
+ * marked only when its value identifies something that outlives the namespace row.
430
+ */
431
+ readonly resource?: true;
432
+ }
433
+ /**
434
+ * One public host this namespace's own entry point answers on, with the listener port that publishes it.
435
+ *
436
+ * Only the provider knows how a host comes to exist — Zerops generates one per published HTTP port — and
437
+ * core knows which of them an application environment already claims, so the provider names them and core
438
+ * marks them. A namespace whose domains are bound out of band names none: the provider cannot see them.
439
+ */
440
+ export interface ProviderNamespaceHost {
441
+ readonly host: string;
442
+ readonly port: number;
443
+ }
444
+ /** Provider-owned operator copy for a planned or persisted namespace. */
445
+ export interface ProviderNamespacePresentation {
446
+ readonly preset: string;
447
+ readonly title: string;
448
+ readonly facts: readonly ProviderNamespaceFact[];
449
+ readonly instructions: readonly string[];
450
+ /** The hosts this namespace can serve, so an operator can name one as an environment's domain. */
451
+ readonly hosts?: readonly ProviderNamespaceHost[];
452
+ }
453
+ /** A mutation-free preview that can be submitted unchanged to namespace creation. */
454
+ export interface ProviderNamespacePlan {
455
+ readonly namespace: ProviderDeploymentNamespace;
456
+ readonly presentation: ProviderNamespacePresentation;
457
+ }
458
+ /** Optional operator surface for providers that offer opinionated namespace presets. */
459
+ export interface ProviderNamespaceOperator {
460
+ readonly presets: readonly ProviderNamespacePreset[];
461
+ plan(input: ProviderNamespacePlanInput): ProviderNamespacePlan;
462
+ present(namespace: ProviderDeploymentNamespace): ProviderNamespacePresentation;
463
+ }
464
+ /** The app-owned claims of one namespace whose resources Control is asked to confirm gone. */
465
+ export interface ProviderClaimedResourcesInput {
466
+ readonly namespace: ProviderDeploymentNamespace;
467
+ readonly resourceKeys: readonly string[];
468
+ readonly signal: AbortSignal;
469
+ }
470
+ /** What the provider observed for one claimed resource. */
471
+ export interface ProviderClaimedResource {
472
+ readonly resourceKey: string;
473
+ readonly exists: boolean;
474
+ }
475
+ /** Optional placement lifecycle owned by providers that use deployment namespaces. */
476
+ export interface ProviderNamespaceCapabilities {
477
+ normalize(namespace: ProviderDeploymentNamespace): ProviderDeploymentNamespace;
478
+ /** Namespace-owned resources that must be reserved before provisioning starts. */
479
+ namespaceResourceClaims(namespace: ProviderDeploymentNamespace): readonly string[];
480
+ /** App-owned resources derived from one canonical normalized registration. */
481
+ registrationResourceClaims(registration: ProviderRegistration): readonly string[];
482
+ /**
483
+ * Materialize app-owned provider resources and return their canonical coordinates.
484
+ * Core acquires every registration resource claim before invoking this mutation.
485
+ */
486
+ prepareRegistration?(input: ProviderRegistrationPreparationInput): Promise<ProviderRegistration>;
487
+ provision(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>;
488
+ reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>;
489
+ /** Absent means the namespace has no entry point that follows its members. */
490
+ republish?(input: ProviderNamespaceRepublishInput): Promise<ProviderNamespaceRepublishResult>;
491
+ /**
492
+ * Read-only: whether each claimed resource still exists, one answer per key. Throws when it cannot tell, so Control
493
+ * releases a claim only over a resource the provider confirmed gone. Absent means no claim can be released.
494
+ */
495
+ claimedResources?(input: ProviderClaimedResourcesInput): Promise<readonly ProviderClaimedResource[]>;
496
+ /** Absent means the provider changes no namespace in place. */
497
+ readonly updates?: ProviderNamespaceUpdates;
498
+ readonly operator?: ProviderNamespaceOperator;
499
+ }
500
+ export interface ProviderAuthoring {
501
+ /** The file NAMES (no `/`) that configure the provider's deploy; a workspace changes none of them, at any depth. */
502
+ readonly protectedFiles: readonly string[];
503
+ }
504
+ /** The provider's handle on one workspace sandbox, which Control persists; stable for the workspace's life. */
505
+ export interface ProviderDevSandboxRef {
506
+ readonly sandboxId: string;
507
+ }
508
+ /** One running workspace sandbox of a `dev` environment. */
509
+ export interface ProviderDevSandbox {
510
+ readonly sandboxId: string;
511
+ /** The base image the sandbox was created from. */
512
+ readonly baseDigest: string;
513
+ /** The Host the namespace proxy sends to reach the sandbox's application port (e.g. `3000-<id>.<box domain>`). */
514
+ readonly upstreamHost: string;
515
+ }
516
+ /** Create a workspace's sandbox, or return the one it already has. */
517
+ export interface ProviderDevSandboxEnsureInput {
518
+ readonly environment: ProviderEnvironment;
519
+ readonly workspaceId: string;
520
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
521
+ readonly sandboxKey: string;
522
+ readonly signal: AbortSignal;
523
+ }
524
+ /** One lifecycle call on an existing workspace sandbox. */
525
+ export interface ProviderDevSandboxInput {
526
+ readonly environment: ProviderEnvironment;
527
+ readonly sandbox: ProviderDevSandboxRef;
528
+ /** The bearer of the namespace's sandbox host API, composed by Control from its vault for this call; never persisted or logged. */
529
+ readonly sandboxKey: string;
530
+ readonly signal: AbortSignal;
531
+ }
532
+ /** Remove a workspace's sandbox; with no recorded `sandbox`, the one an unrecorded `ensure` may have created. */
533
+ export interface ProviderDevSandboxRemoveInput {
534
+ readonly environment: ProviderEnvironment;
535
+ readonly workspaceId: string;
536
+ readonly sandbox: ProviderDevSandboxRef | null;
537
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
538
+ readonly sandboxKey: string;
539
+ readonly signal: AbortSignal;
540
+ }
541
+ /**
542
+ * The per-workspace sandboxes of a `dev` environment outside a run. Every call is idempotent: `ensure` creates at most
543
+ * one sandbox per `workspaceId` and returns it running, `park` and `wake` converge on their state, and `remove` treats a
544
+ * sandbox already gone as removed. A full sandbox host throws `PROVIDER_DEV_CAPACITY`, a namespace without one yet
545
+ * `PROVIDER_DEV_HOST_PENDING`; `remove` there is a no-op, since no sandbox can exist.
546
+ */
547
+ export interface ProviderDevSandboxes {
548
+ /**
549
+ * Mutation-free check that the environment's placement can serve a workspace sandbox. Control calls it before it
550
+ * records one, because a recorded sandbox reaches every later republish of the namespace. A refusal is a
551
+ * `ProviderNamespaceError` that is not retryable, whose one-line message the author may read; any other throw is a failure.
552
+ */
553
+ admit(input: {
554
+ readonly environment: ProviderEnvironment;
555
+ }): void;
556
+ ensure(input: ProviderDevSandboxEnsureInput): Promise<ProviderDevSandbox>;
557
+ park(input: ProviderDevSandboxInput): Promise<void>;
558
+ wake(input: ProviderDevSandboxInput): Promise<void>;
559
+ remove(input: ProviderDevSandboxRemoveInput): Promise<void>;
560
+ }
561
+ /**
562
+ * The control-plane capability bundle selected statically by one composition root.
563
+ *
564
+ * Core owns no provider registry. The selected provider validates registration envelopes and owns
565
+ * every provider-specific deploy lifecycle capability.
566
+ */
567
+ export interface ControlProvider {
568
+ readonly id: string;
569
+ /** Absent means core stores the registration as submitted. */
570
+ normalizeRegistration?(input: ProviderRegistrationInput): ProviderRegistration;
571
+ resolveSource?(input: ProviderSourceResolutionInput): Promise<ProviderSourceResolution>;
572
+ /**
573
+ * Mutation-free check of a candidate's compatibility with its placement. Control calls it before publishing the
574
+ * snapshot, under the namespace lease, on every publication attempt. The candidate is not yet approved access.
575
+ */
576
+ validateAccess?(input: {
577
+ readonly environment: ProviderEnvironment;
578
+ readonly access: ProviderApprovedAccess;
579
+ }): void;
580
+ deploy(input: ProviderDeployInput): Promise<ProviderDeployOutcome>;
581
+ cancel?(input: ProviderCancelInput): Promise<ProviderCancelOutcome>;
582
+ reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>;
583
+ readonly secrets?: ProviderManagedSecrets;
584
+ readonly namespaces?: ProviderNamespaceCapabilities;
585
+ /** MCP authoring (ADR-0049): an environment of this provider can be an authoring target. Absent means none can. */
586
+ readonly authoring?: ProviderAuthoring;
587
+ /**
588
+ * Every application environment gets `FABRIKA_PROXY_SECRET`, with or without a namespace proxy: the provider's own
589
+ * hop to the application carries it (Cloudflare's Worker to its Durable Object, ADR-0065). Absent means only a
590
+ * namespace proxy's environments get one.
591
+ */
592
+ readonly applicationHopSecret?: true;
593
+ /** Absent means the provider runs no `dev` environment, and Control refuses one. */
594
+ readonly devSandboxes?: ProviderDevSandboxes;
595
+ /**
596
+ * Whether an environment at this approved access is served the ops channel through which Control reaches its object
597
+ * (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no
598
+ * release logic. Absent means no environment of this provider is.
599
+ */
600
+ opsChannel?(access: ProviderApprovedAccess): boolean;
601
+ /**
602
+ * Whether the object at this approved access, served the ops channel, also holds the maintenance barrier (`state`,
603
+ * `migrate`) and serves Control's data operations: the daily backups, a deploy's migration phase and the side restore
604
+ * (ADR-0069 §3, ADR-0070). A release can serve the channel without them. Absent means no environment of this
605
+ * provider is.
606
+ */
607
+ dataOperations?(access: ProviderApprovedAccess): boolean;
608
+ /** Absent means the provider deploys public sources only. */
609
+ readonly source?: ProviderSourceCapabilities;
610
+ /**
611
+ * The variable names this artifact declares, so core can refuse one it would silently ignore
612
+ * ([ADR-0035](../../../docs/decisions/0035-the-platform-owns-the-application-iam-issuer.md)).
613
+ *
614
+ * OPTIONAL, and `undefined` is the honest answer rather than an empty set: a provider whose artifact
615
+ * names a config path in the repository cannot know what that config declares, and guessing would
616
+ * refuse a variable that works. A provider that CAN answer — one whose artifact is the compiled
617
+ * manifest — constrains what an operator may set.
618
+ */
619
+ declaredVariables?(input: {
620
+ readonly artifact: ProviderEnvelope;
621
+ }): readonly string[] | undefined;
622
+ /**
623
+ * The repository-relative directory this provider executes the application from, normalized as its execution
624
+ * normalizes it (`''` for the repository root), or null for a root execution refuses. Control reads the run's
625
+ * access snapshot there (ADR-0050). Absent means the repository root.
626
+ */
627
+ applicationRoot?(source: ProviderSource): string | null;
628
+ }
@@ -0,0 +1,6 @@
1
+ export * from './authoring';
2
+ export * from './control';
3
+ export * from './json';
4
+ export * from './plain-credentials';
5
+ export * from './schema';
6
+ export * from './steps';
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The platform commands a provider MAY offer. Every one of them is optional — a provider declares the
3
+ * subset it implements and the CLI prints its usage for anything else.
4
+ *
5
+ * `install` is the newest and the narrowest in support: it BRINGS UP an installation that does not
6
+ * exist yet, generating and placing every credential it needs. Only Zerops declares it, because only
7
+ * there is a from-scratch bring-up a sequence of API calls; on Cloudflare the same ground is covered by
8
+ * `init` plus the workflow it scaffolds.
9
+ *
10
+ * `admin` admits the FIRST HUMAN to an installation that already runs. It is a verb of its own rather
11
+ * than a step of `install`, because it is the one command that is useful long after the bring-up: an
12
+ * installation whose only administrator left needs it, and a bring-up that got as far as the console
13
+ * does not need to be repeated to use it.
14
+ *
15
+ * `upgrade` rolls a RUNNING installation onto a newer published fabrika release. It is separate from
16
+ * `deploy` because the two run in different places: `deploy` runs inside the operator's own pipeline
17
+ * and brings an installation to the checkout it was handed, while `upgrade` runs on the operator's
18
+ * machine and moves the pin that pipeline reads. A provider whose operator edits no pin does not
19
+ * declare it.
20
+ *
21
+ * `guide` prints the operator's procedure for the whole bring-up, with the traps the per-command usage
22
+ * cannot show. It ships with the provider package, so an agent reads the guide of the release it runs.
23
+ */
24
+ export type InstallationCommand = 'init' | 'install' | 'plan' | 'deploy' | 'admin' | 'upgrade' | 'guide';
25
+ export declare const isInstallationCommand: (value: unknown) => value is InstallationCommand;
26
+ export interface InstallationCli {
27
+ readonly provider: string;
28
+ readonly commands: readonly InstallationCommand[];
29
+ readonly usage: string;
30
+ run(command: InstallationCommand, argv: readonly string[]): Promise<void>;
31
+ }
32
+ export interface InstallationCliModule {
33
+ readonly installationCli: InstallationCli;
34
+ }
35
+ export declare const isInstallationCli: (value: unknown) => value is InstallationCli;
36
+ export declare const supportsInstallationCommand: (installation: InstallationCli, command: InstallationCommand) => boolean;
37
+ export declare const installationCliFromModule: (value: unknown, expectedProvider?: string) => InstallationCli;