@cat-factory/contracts 0.70.0 → 0.71.0

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>;
@@ -5290,7 +5772,7 @@ export declare const provisioningDetectionConfidenceSchema: v.PicklistSchema<["h
 export type ProvisioningDetectionConfidence = v.InferOutput<typeof provisioningDetectionConfidenceSchema>;
 /** One inferred aspect of the recommendation, with its confidence + a human-readable rationale. */
 export declare const provisioningDetectionNoteSchema: v.ObjectSchema<{
-    /** Which field this note explains: `provisionType` | `renderer` | `url` | `namespace` | `secretInjections` | `images` | `overlay` | `helmReleases` | `compose`. */
+    /** Which field this note explains: `provisionType` | `renderer` | `url` | `namespace` | `secretInjections` | `images` | `overlay` | `helmReleases` | `compose` | `serviceDir` | `manifestRoot` | `composeService`. */
     readonly field: v.StringSchema<undefined>;
     readonly confidence: v.PicklistSchema<["high", "low"], undefined>;
     /** Rationale for the SPA to surface next to the field (e.g. "kustomization.yaml present ⇒ kustomize"). */
@@ -5311,12 +5793,67 @@ export declare const provisioningOverlayCandidateSchema: v.ObjectSchema<{
     readonly recommended: v.BooleanSchema<undefined>;
 }, undefined>;
 export type ProvisioningOverlayCandidate = v.InferOutput<typeof provisioningOverlayCandidateSchema>;
+/**
+ * A per-service slice found inside a ROOT SHARED deploy directory of a monorepo — the common
+ * layout where a service's manifests live under `deploy/<svc>` / `k8s/<svc>` / `manifests/services/<svc>`
+ * (keyed by the service name) rather than colocated under `services/<svc>/k8s`. The detector
+ * matches the slice whose basename equals the service directory's basename and pre-selects it,
+ * but every candidate is surfaced so the user can pick a different one.
+ */
+export declare const provisioningServiceDirCandidateSchema: v.ObjectSchema<{
+    /** Repo-relative directory of the slice (the value `manifestSource.path` would take), e.g. `deploy/api`. */
+    readonly path: v.StringSchema<undefined>;
+    /** The slice's subfolder basename (e.g. `api`). */
+    readonly name: v.StringSchema<undefined>;
+    /** The candidate matching the service directory's basename (the pre-selected one). */
+    readonly recommended: v.BooleanSchema<undefined>;
+}, undefined>;
+export type ProvisioningServiceDirCandidate = v.InferOutput<typeof provisioningServiceDirCandidateSchema>;
+/**
+ * A `services:` key when a discovered Docker Compose file declares MORE THAN ONE service — the
+ * user picks which service corresponds to this board block. Advisory only: the chosen key is NOT
+ * persisted on the service (the compose backend targets the file, not a single service), so the
+ * chip sets `composePath` and the key rides a note.
+ */
+export declare const provisioningComposeServiceCandidateSchema: v.ObjectSchema<{
+    /** The compose file the service is declared in (the `-f` target — the value `composePath` would take). */
+    readonly composePath: v.StringSchema<undefined>;
+    /** The `services:` key (e.g. `api`). */
+    readonly service: v.StringSchema<undefined>;
+    /** The heuristic top pick (basename match, else the first declared service). */
+    readonly recommended: v.BooleanSchema<undefined>;
+}, undefined>;
+export type ProvisioningComposeServiceCandidate = v.InferOutput<typeof provisioningComposeServiceCandidateSchema>;
+/**
+ * A candidate Kubernetes manifest ROOT when several resolve (e.g. both `k8s/` and `manifests/`
+ * hold real manifests). Generalizes `overlayCandidates` from "which overlay within one root" to
+ * "which root": each carries its own `renderer`. Complementary to `overlayCandidates` — both may
+ * appear (pick the root, then the overlay within it).
+ */
+export declare const provisioningManifestRootCandidateSchema: v.ObjectSchema<{
+    /** Repo-relative manifest directory (the value `manifestSource.path` would take). */
+    readonly path: v.StringSchema<undefined>;
+    /** A human label (the directory's last path segment). */
+    readonly name: v.StringSchema<undefined>;
+    /** The renderer for this root (`kustomization.yaml` present ⇒ `kustomize`, else `raw`). */
+    readonly renderer: v.PicklistSchema<["raw", "kustomize"], undefined>;
+    /** The pre-selected root (the one reflected in `provisioning.manifestSource`). */
+    readonly recommended: v.BooleanSchema<undefined>;
+}, undefined>;
+export type ProvisioningManifestRootCandidate = v.InferOutput<typeof provisioningManifestRootCandidateSchema>;
 /**
  * A non-binding provisioning recommendation detected from a service's repo. `provisioning`
  * carries the service-owned config to prefill (the "what + where"); `urlSource`/`namespace`
  * are engine-level suggestions the workspace handler owns (the detector can READ them from
- * the manifests but they aren't stored on the service); `overlayCandidates` + `notes` drive
+ * the manifests but they aren't stored on the service); the candidate arrays + `notes` drive
  * the confirm UI. `detected: false` ⇒ nothing inferable (`provisioning.type` is `infraless`).
+ *
+ * The candidate arrays let the user CHOOSE instead of accepting a silent auto-pick:
+ * `overlayCandidates` (which overlay within a kustomize root), `manifestRootCandidates` (which
+ * k8s root when several resolve), `serviceDirCandidates` (which root-shared monorepo slice), and
+ * `composeServiceCandidates` (which compose service). Each note's `field` is one of
+ * `provisionType` | `renderer` | `url` | `namespace` | `secretInjections` | `images` | `overlay` |
+ * `helmReleases` | `compose` | `serviceDir` | `manifestRoot` | `composeService`.
  */
 export declare const provisioningRecommendationSchema: v.ObjectSchema<{
     readonly detected: v.BooleanSchema<undefined>;
@@ -5488,9 +6025,38 @@ export declare const provisioningRecommendationSchema: v.ObjectSchema<{
         /** The highest-ranked candidate (the one pre-selected in `provisioning.manifestSource`). */
         readonly recommended: v.BooleanSchema<undefined>;
     }, undefined>, undefined>, undefined>;
+    /** Candidate k8s manifest roots to choose among when several resolve (complements `overlayCandidates`). */
+    readonly manifestRootCandidates: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        /** Repo-relative manifest directory (the value `manifestSource.path` would take). */
+        readonly path: v.StringSchema<undefined>;
+        /** A human label (the directory's last path segment). */
+        readonly name: v.StringSchema<undefined>;
+        /** The renderer for this root (`kustomization.yaml` present ⇒ `kustomize`, else `raw`). */
+        readonly renderer: v.PicklistSchema<["raw", "kustomize"], undefined>;
+        /** The pre-selected root (the one reflected in `provisioning.manifestSource`). */
+        readonly recommended: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>, undefined>;
+    /** Candidate root-shared monorepo deploy slices to choose among (keyed by service name). */
+    readonly serviceDirCandidates: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        /** Repo-relative directory of the slice (the value `manifestSource.path` would take), e.g. `deploy/api`. */
+        readonly path: v.StringSchema<undefined>;
+        /** The slice's subfolder basename (e.g. `api`). */
+        readonly name: v.StringSchema<undefined>;
+        /** The candidate matching the service directory's basename (the pre-selected one). */
+        readonly recommended: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>, undefined>;
+    /** Candidate compose services to pick from when the compose file declares several (advisory). */
+    readonly composeServiceCandidates: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        /** The compose file the service is declared in (the `-f` target — the value `composePath` would take). */
+        readonly composePath: v.StringSchema<undefined>;
+        /** The `services:` key (e.g. `api`). */
+        readonly service: v.StringSchema<undefined>;
+        /** The heuristic top pick (basename match, else the first declared service). */
+        readonly recommended: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>, undefined>;
     /** Per-field confidence + hints for the SPA. */
     readonly notes: v.ArraySchema<v.ObjectSchema<{
-        /** Which field this note explains: `provisionType` | `renderer` | `url` | `namespace` | `secretInjections` | `images` | `overlay` | `helmReleases` | `compose`. */
+        /** Which field this note explains: `provisionType` | `renderer` | `url` | `namespace` | `secretInjections` | `images` | `overlay` | `helmReleases` | `compose` | `serviceDir` | `manifestRoot` | `composeService`. */
         readonly field: v.StringSchema<undefined>;
         readonly confidence: v.PicklistSchema<["high", "low"], undefined>;
         /** Rationale for the SPA to surface next to the field (e.g. "kustomization.yaml present ⇒ kustomize"). */