@cat-factory/contracts 0.70.0 → 0.70.1

package/dist/environments.d.ts

@@ -1952,6 +1952,13 @@ export declare const environmentHandlerViewSchema: v.ObjectSchema<{
     readonly secretKeys: v.ArraySchema<v.StringSchema<undefined>, undefined>;
     /** For `remote-custom`: the manifest id this provider accepts; `null` otherwise. */
     readonly acceptsManifestId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * The registry backend kind that builds this handler's provider (`manifest`, `kubernetes`,
+     * or a deployment-registered custom kind). Lets the connect form pre-select the right backend
+     * when editing a saved handler — distinct from `providerId`, which is the connection's own
+     * identifier, not the registry slug.
+     */
+    readonly backendKind: v.StringSchema<undefined>;
     /** The stored handler config, sans secrets, for connect-form prefill on edit. */
     readonly config: v.OptionalSchema<v.VariantSchema<"engine", [v.ObjectSchema<{
         readonly engine: v.LiteralSchema<"local-docker", undefined>;
@@ -2882,6 +2889,474 @@ export declare const registerEnvironmentHandlerSchema: v.ObjectSchema<{
     readonly secrets: v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>;
 }, undefined>;
 export type RegisterEnvironmentHandlerInput = v.InferOutput<typeof registerEnvironmentHandlerSchema>;
+/**
+ * Probe a per-type infra handler connection before saving (nothing persisted). Carries the
+ * engine connection config + its (write-only) secret bundle, optionally pinning the registry
+ * backend that builds the provider (else resolved from the engine). The same shape as
+ * {@link registerEnvironmentHandlerSchema} minus the persistence-only `provisionType`/`manifestId`.
+ */
+export declare const testEnvironmentHandlerSchema: v.ObjectSchema<{
+    readonly config: v.VariantSchema<"engine", [v.ObjectSchema<{
+        readonly engine: v.LiteralSchema<"local-docker", undefined>;
+        readonly manifest: v.ObjectSchema<{
+            readonly providerId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+            readonly label: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+            /** Management API root; provision/status/teardown paths are appended to it. */
+            readonly baseUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+            readonly auth: v.VariantSchema<"type", [v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"none", undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"api_key", undefined>;
+                readonly headerName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                readonly secretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+                /** Optional prefix prepended to the secret value, e.g. `Token `. */
+                readonly valuePrefix: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"bearer", undefined>;
+                readonly secretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"basic", undefined>;
+                readonly usernameSecretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+                readonly passwordSecretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"oauth2_client_credentials", undefined>;
+                readonly tokenUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly clientIdSecretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+                readonly clientSecretSecretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+                readonly scope: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly audience: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"custom_headers", undefined>;
+                readonly headers: v.ArraySchema<v.ObjectSchema<{
+                    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly secretRef: v.ObjectSchema<{
+                        readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                    }, undefined>;
+                }, undefined>, undefined>;
+            }, undefined>], undefined>;
+            readonly provision: v.ObjectSchema<{
+                readonly method: v.PicklistSchema<["GET", "POST", "PUT", "PATCH", "DELETE"], undefined>;
+                readonly pathTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly query: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly key: v.StringSchema<undefined>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly headers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly bodyTemplate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                /** Per-call timeout (ms). Bounded; defaults applied by the adapter. */
+                readonly timeoutMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 60000, undefined>]>, undefined>;
+            }, undefined>;
+            /** Optional: polled to observe async provisioning progress. */
+            readonly status: v.OptionalSchema<v.ObjectSchema<{
+                readonly method: v.PicklistSchema<["GET", "POST", "PUT", "PATCH", "DELETE"], undefined>;
+                readonly pathTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly query: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly key: v.StringSchema<undefined>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly headers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly bodyTemplate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                /** Per-call timeout (ms). Bounded; defaults applied by the adapter. */
+                readonly timeoutMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 60000, undefined>]>, undefined>;
+            }, undefined>, undefined>;
+            /** Optional: called to destroy the environment (manual or on TTL expiry). */
+            readonly teardown: v.OptionalSchema<v.ObjectSchema<{
+                readonly method: v.PicklistSchema<["GET", "POST", "PUT", "PATCH", "DELETE"], undefined>;
+                readonly pathTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly query: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly key: v.StringSchema<undefined>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly headers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly bodyTemplate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                /** Per-call timeout (ms). Bounded; defaults applied by the adapter. */
+                readonly timeoutMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 60000, undefined>]>, undefined>;
+            }, undefined>, undefined>;
+            readonly response: v.ObjectSchema<{
+                readonly urlPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly statusPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly statusMap: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly from: v.StringSchema<undefined>;
+                    readonly to: v.PicklistSchema<["provisioning", "ready", "failed", "expired", "tearing_down", "torn_down"], undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly expiresAtPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly externalIdPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly access: v.OptionalSchema<v.ObjectSchema<{
+                    readonly scheme: v.PicklistSchema<["none", "bearer", "basic", "custom_header"], undefined>;
+                    readonly tokenPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly usernamePath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly passwordPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly headerName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly headerValuePath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, undefined>;
+            }, undefined>;
+            /** Fallback TTL (ms) when the response carries no explicit expiry. */
+            readonly defaultTtlMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 60000, undefined>]>, undefined>;
+            /**
+             * Opaque, provider-specific configuration for a CUSTOM backend (e.g. a Kargo project,
+             * link-selection key, status map). The generic HttpEnvironmentProvider ignores it
+             * entirely; a custom backend — registered by reference into the app-owned
+             * `EnvironmentBackendRegistry` (see `backend/docs/native-environment-adapter.md`) — reads
+             * + validates it off the per-call
+             * `manifest`. This is the per-WORKSPACE config carrier: a custom backend rides the generic
+             * manifest member of `environmentBackendConfigSchema`, so its bespoke settings live here and
+             * its credentials in the secret bundle. NOT covered by the manifest URL/SSRF checks (which
+             * only guard `baseUrl`/`tokenUrl`); a backend that puts a URL here must guard it itself
+             * (reuse the exported `UrlSafetyPolicy`).
+             */
+            readonly providerConfig: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+        }, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly engine: v.LiteralSchema<"local-k3s", undefined>;
+        readonly kubernetes: v.ObjectSchema<{
+            readonly label: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+            /** kube-apiserver root URL, e.g. `https://my-cluster.example:6443`. */
+            readonly apiServerUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+            /** PEM CA bundle to verify the apiserver TLS cert (omit only for a publicly-trusted CA). */
+            readonly caCertPem: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            /** Skip apiserver TLS verification — strongly discouraged; kind/dev clusters only. */
+            readonly insecureSkipTlsVerify: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            /**
+             * Namespace name template for the per-PR environment, e.g. `cf-env-{{pullNumber}}`. With
+             * `renderer: 'kustomize'`, ABSENT ⇒ honor the overlay's own `namespace:` when it pins one
+             * (the shared-namespace ephemeral-env shape, where base + overlay name a fixed namespace);
+             * SET ⇒ override it (the adapter sets the namespace at build time) for true per-PR
+             * isolation. For raw manifests, absent ⇒ a default derived from the PR number / block id.
+             */
+            readonly namespaceTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
+            /** How the environment URL is derived once applied. */
+            readonly url: v.VariantSchema<"source", [v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"ingressTemplate", undefined>;
+                /** Host template, e.g. `{{branch}}.preview.example.com`; rendered with the provision vars. */
+                readonly hostTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"ingressStatus", undefined>;
+                /** Ingress object to read `.status.loadBalancer` from; absent ⇒ the only Ingress applied. */
+                readonly ingressName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"serviceStatus", undefined>;
+                /** Service object to read `.status.loadBalancer` (k3s ServiceLB) from. */
+                readonly serviceName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+                readonly port: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 65535, undefined>]>, undefined>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"gatewayStatus", undefined>;
+                /** Gateway-API `Gateway` to read `.status.addresses[]` from; absent ⇒ the only one applied. */
+                readonly gatewayName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"httpRouteStatus", undefined>;
+                /** `HTTPRoute` whose `parentRefs` resolve to the Gateway address; absent ⇒ the only one applied. */
+                readonly httpRouteName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>], undefined>;
+            /** Optional image reference made available to the manifests as `{{image}}`. */
+            readonly imageTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+            /** Fallback TTL (ms) after which the env is swept + torn down. */
+            readonly defaultTtlMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 60000, undefined>]>, undefined>;
+            /**
+             * How long (seconds) the container deploy adapter waits for each Deployment to roll out
+             * before reporting the env still `provisioning` (the backend keeps polling). Absent ⇒ the
+             * harness default (180s). Merged into the provision config via `...kube` at provision time.
+             */
+            readonly rolloutTimeoutSeconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>;
+            /** Extra labels stamped on the namespace + every applied resource. */
+            readonly labels: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+            /** Extra annotations stamped on the namespace. */
+            readonly annotations: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+            /**
+             * Workspace-level (cluster-singleton) helm releases the deploy adapter ensures before
+             * applying a service's manifests — e.g. an ingress/gateway controller shared by every
+             * per-PR env. Use `scope: 'shared'`; installed once, never torn down per-PR. Merged
+             * with the service's own (per-environment) `helmReleases` at provision time.
+             */
+            readonly helmReleases: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                /** Release name. */
+                readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                /** Chart ref: an OCI ref (`oci://…`) or, with `repo`, a `repo/chart` name. */
+                readonly chart: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                /** Chart repo URL; absent ⇒ `chart` is an OCI ref. */
+                readonly repo: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+                /** PINNED chart version, e.g. `1.2.3` / `v1.2.3` (floating tags like `latest`/`^1.0` rejected). */
+                readonly version: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.RegexAction<string, "version must be a pinned semver (e.g. 1.2.3), not a floating tag like latest or ^1.0.">]>;
+                /** Namespace to install into, templated; absent ⇒ the environment namespace. */
+                readonly namespaceTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+                /** Inline `--values` overrides. */
+                readonly values: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+                /** Templated `--set` overrides. */
+                readonly set: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    /** Dotted `--set` path, e.g. `config.rateLimit.enabled`. */
+                    readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    /** The value, templated over the provision vars. */
+                    readonly valueTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>;
+                }, undefined>, undefined>, undefined>;
+                /** Secret-bundle-backed values folded in at provision time (`--set <path>=<secret>`). */
+                readonly valuesSecretRefs: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly secretRef: v.ObjectSchema<{
+                        readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                    }, undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly scope: v.OptionalSchema<v.PicklistSchema<["per-environment", "shared"], undefined>, undefined>;
+            }, undefined>, undefined>, undefined>;
+        }, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly engine: v.LiteralSchema<"remote-kubernetes", undefined>;
+        readonly kubernetes: v.ObjectSchema<{
+            readonly label: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+            /** kube-apiserver root URL, e.g. `https://my-cluster.example:6443`. */
+            readonly apiServerUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+            /** PEM CA bundle to verify the apiserver TLS cert (omit only for a publicly-trusted CA). */
+            readonly caCertPem: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            /** Skip apiserver TLS verification — strongly discouraged; kind/dev clusters only. */
+            readonly insecureSkipTlsVerify: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            /**
+             * Namespace name template for the per-PR environment, e.g. `cf-env-{{pullNumber}}`. With
+             * `renderer: 'kustomize'`, ABSENT ⇒ honor the overlay's own `namespace:` when it pins one
+             * (the shared-namespace ephemeral-env shape, where base + overlay name a fixed namespace);
+             * SET ⇒ override it (the adapter sets the namespace at build time) for true per-PR
+             * isolation. For raw manifests, absent ⇒ a default derived from the PR number / block id.
+             */
+            readonly namespaceTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
+            /** How the environment URL is derived once applied. */
+            readonly url: v.VariantSchema<"source", [v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"ingressTemplate", undefined>;
+                /** Host template, e.g. `{{branch}}.preview.example.com`; rendered with the provision vars. */
+                readonly hostTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"ingressStatus", undefined>;
+                /** Ingress object to read `.status.loadBalancer` from; absent ⇒ the only Ingress applied. */
+                readonly ingressName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"serviceStatus", undefined>;
+                /** Service object to read `.status.loadBalancer` (k3s ServiceLB) from. */
+                readonly serviceName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+                readonly port: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 65535, undefined>]>, undefined>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"gatewayStatus", undefined>;
+                /** Gateway-API `Gateway` to read `.status.addresses[]` from; absent ⇒ the only one applied. */
+                readonly gatewayName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly source: v.LiteralSchema<"httpRouteStatus", undefined>;
+                /** `HTTPRoute` whose `parentRefs` resolve to the Gateway address; absent ⇒ the only one applied. */
+                readonly httpRouteName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+                readonly scheme: v.OptionalSchema<v.PicklistSchema<["http", "https"], undefined>, undefined>;
+            }, undefined>], undefined>;
+            /** Optional image reference made available to the manifests as `{{image}}`. */
+            readonly imageTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+            /** Fallback TTL (ms) after which the env is swept + torn down. */
+            readonly defaultTtlMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 60000, undefined>]>, undefined>;
+            /**
+             * How long (seconds) the container deploy adapter waits for each Deployment to roll out
+             * before reporting the env still `provisioning` (the backend keeps polling). Absent ⇒ the
+             * harness default (180s). Merged into the provision config via `...kube` at provision time.
+             */
+            readonly rolloutTimeoutSeconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>;
+            /** Extra labels stamped on the namespace + every applied resource. */
+            readonly labels: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+            /** Extra annotations stamped on the namespace. */
+            readonly annotations: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+            /**
+             * Workspace-level (cluster-singleton) helm releases the deploy adapter ensures before
+             * applying a service's manifests — e.g. an ingress/gateway controller shared by every
+             * per-PR env. Use `scope: 'shared'`; installed once, never torn down per-PR. Merged
+             * with the service's own (per-environment) `helmReleases` at provision time.
+             */
+            readonly helmReleases: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                /** Release name. */
+                readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                /** Chart ref: an OCI ref (`oci://…`) or, with `repo`, a `repo/chart` name. */
+                readonly chart: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                /** Chart repo URL; absent ⇒ `chart` is an OCI ref. */
+                readonly repo: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+                /** PINNED chart version, e.g. `1.2.3` / `v1.2.3` (floating tags like `latest`/`^1.0` rejected). */
+                readonly version: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.RegexAction<string, "version must be a pinned semver (e.g. 1.2.3), not a floating tag like latest or ^1.0.">]>;
+                /** Namespace to install into, templated; absent ⇒ the environment namespace. */
+                readonly namespaceTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+                /** Inline `--values` overrides. */
+                readonly values: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+                /** Templated `--set` overrides. */
+                readonly set: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    /** Dotted `--set` path, e.g. `config.rateLimit.enabled`. */
+                    readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    /** The value, templated over the provision vars. */
+                    readonly valueTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>;
+                }, undefined>, undefined>, undefined>;
+                /** Secret-bundle-backed values folded in at provision time (`--set <path>=<secret>`). */
+                readonly valuesSecretRefs: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly secretRef: v.ObjectSchema<{
+                        readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                    }, undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly scope: v.OptionalSchema<v.PicklistSchema<["per-environment", "shared"], undefined>, undefined>;
+            }, undefined>, undefined>, undefined>;
+        }, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly engine: v.LiteralSchema<"remote-custom", undefined>;
+        readonly manifest: v.ObjectSchema<{
+            readonly providerId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+            readonly label: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+            /** Management API root; provision/status/teardown paths are appended to it. */
+            readonly baseUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+            readonly auth: v.VariantSchema<"type", [v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"none", undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"api_key", undefined>;
+                readonly headerName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                readonly secretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+                /** Optional prefix prepended to the secret value, e.g. `Token `. */
+                readonly valuePrefix: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"bearer", undefined>;
+                readonly secretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"basic", undefined>;
+                readonly usernameSecretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+                readonly passwordSecretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"oauth2_client_credentials", undefined>;
+                readonly tokenUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly clientIdSecretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+                readonly clientSecretSecretRef: v.ObjectSchema<{
+                    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                }, undefined>;
+                readonly scope: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly audience: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"custom_headers", undefined>;
+                readonly headers: v.ArraySchema<v.ObjectSchema<{
+                    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly secretRef: v.ObjectSchema<{
+                        readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+                    }, undefined>;
+                }, undefined>, undefined>;
+            }, undefined>], undefined>;
+            readonly provision: v.ObjectSchema<{
+                readonly method: v.PicklistSchema<["GET", "POST", "PUT", "PATCH", "DELETE"], undefined>;
+                readonly pathTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly query: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly key: v.StringSchema<undefined>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly headers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly bodyTemplate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                /** Per-call timeout (ms). Bounded; defaults applied by the adapter. */
+                readonly timeoutMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 60000, undefined>]>, undefined>;
+            }, undefined>;
+            /** Optional: polled to observe async provisioning progress. */
+            readonly status: v.OptionalSchema<v.ObjectSchema<{
+                readonly method: v.PicklistSchema<["GET", "POST", "PUT", "PATCH", "DELETE"], undefined>;
+                readonly pathTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly query: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly key: v.StringSchema<undefined>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly headers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly bodyTemplate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                /** Per-call timeout (ms). Bounded; defaults applied by the adapter. */
+                readonly timeoutMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 60000, undefined>]>, undefined>;
+            }, undefined>, undefined>;
+            /** Optional: called to destroy the environment (manual or on TTL expiry). */
+            readonly teardown: v.OptionalSchema<v.ObjectSchema<{
+                readonly method: v.PicklistSchema<["GET", "POST", "PUT", "PATCH", "DELETE"], undefined>;
+                readonly pathTemplate: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly query: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly key: v.StringSchema<undefined>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly headers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                    readonly value: v.StringSchema<undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly bodyTemplate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                /** Per-call timeout (ms). Bounded; defaults applied by the adapter. */
+                readonly timeoutMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 60000, undefined>]>, undefined>;
+            }, undefined>, undefined>;
+            readonly response: v.ObjectSchema<{
+                readonly urlPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly statusPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly statusMap: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                    readonly from: v.StringSchema<undefined>;
+                    readonly to: v.PicklistSchema<["provisioning", "ready", "failed", "expired", "tearing_down", "torn_down"], undefined>;
+                }, undefined>, undefined>, undefined>;
+                readonly expiresAtPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly externalIdPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly access: v.OptionalSchema<v.ObjectSchema<{
+                    readonly scheme: v.PicklistSchema<["none", "bearer", "basic", "custom_header"], undefined>;
+                    readonly tokenPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly usernamePath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly passwordPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly headerName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly headerValuePath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, undefined>;
+            }, undefined>;
+            /** Fallback TTL (ms) when the response carries no explicit expiry. */
+            readonly defaultTtlMs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 60000, undefined>]>, undefined>;
+            /**
+             * Opaque, provider-specific configuration for a CUSTOM backend (e.g. a Kargo project,
+             * link-selection key, status map). The generic HttpEnvironmentProvider ignores it
+             * entirely; a custom backend — registered by reference into the app-owned
+             * `EnvironmentBackendRegistry` (see `backend/docs/native-environment-adapter.md`) — reads
+             * + validates it off the per-call
+             * `manifest`. This is the per-WORKSPACE config carrier: a custom backend rides the generic
+             * manifest member of `environmentBackendConfigSchema`, so its bespoke settings live here and
+             * its credentials in the secret bundle. NOT covered by the manifest URL/SSRF checks (which
+             * only guard `baseUrl`/`tokenUrl`); a backend that puts a URL here must guard it itself
+             * (reuse the exported `UrlSafetyPolicy`).
+             */
+            readonly providerConfig: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+        }, undefined>;
+        /** Which custom manifest shape this remote provider consumes — matched to a service's `manifestId`. */
+        readonly acceptsManifestId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>;
+    }, undefined>], undefined>;
+    readonly backendKind: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly secrets: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export type TestEnvironmentHandlerInput = v.InferOutput<typeof testEnvironmentHandlerSchema>;
 /**
  * The body for a per-USER handler override PUT, where the provision type is taken from the
  * path (`/me/environment-handlers/:workspaceId/:provisionType`) — so the body carries only
@@ -3366,6 +3841,13 @@ export declare const environmentHandlersBundleSchema: v.ObjectSchema<{
         readonly secretKeys: v.ArraySchema<v.StringSchema<undefined>, undefined>;
         /** For `remote-custom`: the manifest id this provider accepts; `null` otherwise. */
         readonly acceptsManifestId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * The registry backend kind that builds this handler's provider (`manifest`, `kubernetes`,
+         * or a deployment-registered custom kind). Lets the connect form pre-select the right backend
+         * when editing a saved handler — distinct from `providerId`, which is the connection's own
+         * identifier, not the registry slug.
+         */
+        readonly backendKind: v.StringSchema<undefined>;
         /** The stored handler config, sans secrets, for connect-form prefill on edit. */
         readonly config: v.OptionalSchema<v.VariantSchema<"engine", [v.ObjectSchema<{
             readonly engine: v.LiteralSchema<"local-docker", undefined>;