@cat-factory/contracts 0.60.0 → 0.62.0

package/dist/environments.d.ts

@@ -275,15 +275,28 @@ export declare const manifestIdSchema: v.SchemaWithPipe<readonly [v.StringSchema
 export type ManifestId = v.InferOutput<typeof manifestIdSchema>;
 /** The secret-bundle key the Kubernetes env backend reads the ServiceAccount token from. */
 export declare const KUBERNETES_ENV_TOKEN_SECRET_KEY = "apiToken";
+/**
+ * How the manifests at `path` are turned into apiserver-ready resources. `raw` (the
+ * default, and the only one the in-Worker native REST adapter handles) treats `path` as
+ * a single manifest file or a flat directory of already-valid YAML docs. `kustomize`
+ * treats `path` as an overlay directory (`kustomization.yaml` + `resources`/`components`/
+ * `bases`) that must be `kustomize build`-rendered before apply — which only the
+ * container-backed deploy adapter can do (it shells out to real `kustomize`/`helm`).
+ */
+export declare const kubernetesRendererSchema: v.PicklistSchema<["raw", "kustomize"], undefined>;
+export type KubernetesRenderer = v.InferOutput<typeof kubernetesRendererSchema>;
 /**
  * Where the per-PR manifests are read from. `colocated` reads them from the block's
  * own repo at the PR head branch; `separate` reads them from a different repo (the
- * Kubernetes definition often lives outside the service repo).
+ * Kubernetes definition often lives outside the service repo). `renderer` (absent ⇒
+ * `raw`) selects how `path` is turned into resources; `kustomize` requires the
+ * container-backed deploy adapter.
  */
 export declare const kubernetesManifestSourceSchema: v.VariantSchema<"type", [v.ObjectSchema<{
     readonly type: v.LiteralSchema<"colocated", undefined>;
     /** File or directory path within the PR repo (read at the PR head branch). */
     readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+    readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
 }, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"separate", undefined>;
     /** `owner/repo` of the manifests repo. */
@@ -292,6 +305,7 @@ export declare const kubernetesManifestSourceSchema: v.VariantSchema<"type", [v.
     readonly ref: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
     /** File or directory path within the manifests repo. */
     readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+    readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
 }, undefined>], undefined>;
 export type KubernetesManifestSource = v.InferOutput<typeof kubernetesManifestSourceSchema>;
 /** How the environment URL is derived once the manifests are applied. */
@@ -311,6 +325,16 @@ export declare const kubernetesUrlSourceSchema: v.VariantSchema<"source", [v.Obj
     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>;
 export type KubernetesUrlSource = v.InferOutput<typeof kubernetesUrlSourceSchema>;
 export declare const kubernetesEnvironmentConfigSchema: v.ObjectSchema<{
@@ -333,6 +357,7 @@ export declare const kubernetesEnvironmentConfigSchema: v.ObjectSchema<{
         readonly type: v.LiteralSchema<"colocated", undefined>;
         /** File or directory path within the PR repo (read at the PR head branch). */
         readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+        readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
     }, undefined>, v.ObjectSchema<{
         readonly type: v.LiteralSchema<"separate", undefined>;
         /** `owner/repo` of the manifests repo. */
@@ -341,6 +366,7 @@ export declare const kubernetesEnvironmentConfigSchema: v.ObjectSchema<{
         readonly ref: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
         /** File or directory path within the manifests repo. */
         readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+        readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
     }, undefined>], undefined>;
     /** How the environment URL is derived once applied. */
     readonly url: v.VariantSchema<"source", [v.ObjectSchema<{
@@ -359,6 +385,16 @@ export declare const kubernetesEnvironmentConfigSchema: v.ObjectSchema<{
         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}}` (e.g. a
@@ -373,6 +409,157 @@ export declare const kubernetesEnvironmentConfigSchema: v.ObjectSchema<{
     readonly annotations: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
 }, undefined>;
 export type KubernetesEnvironmentConfig = v.InferOutput<typeof kubernetesEnvironmentConfigSchema>;
+/**
+ * A structured image override (the kustomize `images:` equivalent, generalizing the
+ * legacy `{{image}}` text substitution). Matches a container image by `name` and
+ * overrides its repo and/or tag/digest; the override values are templated over the
+ * provision vars (e.g. `newTagTemplate: '{{branch}}'`).
+ */
+export declare const kubernetesImageOverrideSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
+    /** The image to match (the `name:` in a kustomization `images:` entry), e.g. `registry/app`. */
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    /** Optional replacement repo, templated; absent ⇒ keep the original repo. */
+    readonly newNameTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    /** Replacement tag, templated (e.g. `{{branch}}` / `{{sha}}`); mutually exclusive with digest. */
+    readonly newTagTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    /** Replacement digest, templated; alternative to a tag. */
+    readonly digestTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+}, undefined>, v.CheckAction<{
+    name: string;
+    newNameTemplate?: string | undefined;
+    newTagTemplate?: string | undefined;
+    digestTemplate?: string | undefined;
+}, "an image override must set at least one of newNameTemplate, newTagTemplate, or digestTemplate.">, v.CheckAction<{
+    name: string;
+    newNameTemplate?: string | undefined;
+    newTagTemplate?: string | undefined;
+    digestTemplate?: string | undefined;
+}, "newTagTemplate and digestTemplate are mutually exclusive on an image override.">]>;
+export type KubernetesImageOverride = v.InferOutput<typeof kubernetesImageOverrideSchema>;
+/** A single templated `--set path=value` for a helm release. */
+export declare const kubernetesHelmSetSchema: 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>;
+export type KubernetesHelmSet = v.InferOutput<typeof kubernetesHelmSetSchema>;
+/**
+ * A helm release the deploy adapter installs/upgrades (`helm upgrade --install`).
+ * `scope: 'shared'` is a cluster singleton (installed once, never torn down per-PR —
+ * e.g. an ingress/gateway controller); `per-environment` (the default) re-installs in
+ * each per-PR namespace. The `version` pin is required so provisioning is deterministic.
+ */
+export declare const kubernetesHelmReleaseSchema: 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>;
+export type KubernetesHelmRelease = v.InferOutput<typeof kubernetesHelmReleaseSchema>;
+/** One entry inside an injected Secret: a logical key mapped to a secret-bundle ref OR a templated value. */
+export declare const kubernetesSecretEntrySchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
+    /** Key inside the rendered Secret / `.env`. */
+    readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 256, undefined>]>;
+    /** Resolve the value from the workspace encrypted bundle by key. */
+    readonly secretRef: v.OptionalSchema<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>;
+    /** OR a non-secret value, templated over the provision vars. */
+    readonly valueTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+}, undefined>, v.CheckAction<{
+    key: string;
+    secretRef?: {
+        key: string;
+    } | undefined;
+    valueTemplate?: string | undefined;
+}, "a secret entry must set exactly one of secretRef or valueTemplate.">]>;
+export type KubernetesSecretEntry = v.InferOutput<typeof kubernetesSecretEntrySchema>;
+/**
+ * How the deploy adapter feeds resolved secret values in before apply, discriminated by
+ * `mode`. The mapping of logical keys is in-repo intent; the values resolve from the
+ * encrypted bundle at provision time (the config carries secret KEYS, never values).
+ *
+ * - `secret`: materialize a `Secret` resource named `secretName` directly in the namespace.
+ * - `generatorEnvFile`: write the entries as a `KEY=value` `.env` file at `envFilePath`
+ *   (repo-relative, inside the overlay tree) BEFORE `kustomize build`, so the overlay's own
+ *   existing `secretGenerator` consumes it. This is the common ephemeral-environment shape
+ *   where a Component declares `secretGenerator: { envs: ['.env'] }`, the Secret is named by
+ *   the overlay, and the real `.env` is supplied at deploy time (e.g. from a secrets manager).
+ *   Use this instead of `secret` when the manifests already declare a `secretGenerator`, so
+ *   the two don't collide.
+ */
+export declare const kubernetesSecretInjectionSchema: v.VariantSchema<"mode", [v.ObjectSchema<{
+    readonly mode: v.LiteralSchema<"secret", undefined>;
+    /** Target Secret name in the namespace. */
+    readonly secretName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    /** Secret `type`; absent ⇒ `Opaque`. */
+    readonly secretType: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly entries: v.ArraySchema<v.SchemaWithPipe<readonly [v.ObjectSchema<{
+        /** Key inside the rendered Secret / `.env`. */
+        readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 256, undefined>]>;
+        /** Resolve the value from the workspace encrypted bundle by key. */
+        readonly secretRef: v.OptionalSchema<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>;
+        /** OR a non-secret value, templated over the provision vars. */
+        readonly valueTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+    }, undefined>, v.CheckAction<{
+        key: string;
+        secretRef?: {
+            key: string;
+        } | undefined;
+        valueTemplate?: string | undefined;
+    }, "a secret entry must set exactly one of secretRef or valueTemplate.">]>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly mode: v.LiteralSchema<"generatorEnvFile", undefined>;
+    /**
+     * Repo-relative path within the overlay tree to write the `KEY=value` env file the
+     * overlay's `secretGenerator` reads (e.g. `overlays/<env>/<component>/.env`). The
+     * overlay names the Secret.
+     */
+    readonly envFilePath: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+    readonly entries: v.ArraySchema<v.SchemaWithPipe<readonly [v.ObjectSchema<{
+        /** Key inside the rendered Secret / `.env`. */
+        readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 256, undefined>]>;
+        /** Resolve the value from the workspace encrypted bundle by key. */
+        readonly secretRef: v.OptionalSchema<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>;
+        /** OR a non-secret value, templated over the provision vars. */
+        readonly valueTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+    }, undefined>, v.CheckAction<{
+        key: string;
+        secretRef?: {
+            key: string;
+        } | undefined;
+        valueTemplate?: string | undefined;
+    }, "a secret entry must set exactly one of secretRef or valueTemplate.">]>, undefined>;
+}, undefined>], undefined>;
+export type KubernetesSecretInjection = v.InferOutput<typeof kubernetesSecretInjectionSchema>;
 /** Built-in environment backend kinds the contract knows by name. */
 export declare const RESERVED_ENVIRONMENT_BACKEND_KINDS: readonly ['manifest', 'kubernetes'];
 /**
@@ -547,6 +734,7 @@ export declare const environmentBackendConfigSchema: v.VariantSchema<"kind", [v.
             readonly type: v.LiteralSchema<"colocated", undefined>;
             /** File or directory path within the PR repo (read at the PR head branch). */
             readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+            readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
         }, undefined>, v.ObjectSchema<{
             readonly type: v.LiteralSchema<"separate", undefined>;
             /** `owner/repo` of the manifests repo. */
@@ -555,6 +743,7 @@ export declare const environmentBackendConfigSchema: v.VariantSchema<"kind", [v.
             readonly ref: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
             /** File or directory path within the manifests repo. */
             readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+            readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
         }, undefined>], undefined>;
         /** How the environment URL is derived once applied. */
         readonly url: v.VariantSchema<"source", [v.ObjectSchema<{
@@ -573,6 +762,16 @@ export declare const environmentBackendConfigSchema: v.VariantSchema<"kind", [v.
             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}}` (e.g. a
@@ -733,6 +932,7 @@ export declare const serviceProvisioningSchema: v.ObjectSchema<{
         readonly type: v.LiteralSchema<"colocated", undefined>;
         /** File or directory path within the PR repo (read at the PR head branch). */
         readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+        readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
     }, undefined>, v.ObjectSchema<{
         readonly type: v.LiteralSchema<"separate", undefined>;
         /** `owner/repo` of the manifests repo. */
@@ -741,6 +941,7 @@ export declare const serviceProvisioningSchema: v.ObjectSchema<{
         readonly ref: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
         /** File or directory path within the manifests repo. */
         readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+        readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
     }, undefined>], undefined>, undefined>;
     /** `docker-compose`: path to the compose file relative to the repo root. */
     readonly composePath: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
@@ -750,6 +951,107 @@ export declare const serviceProvisioningSchema: v.ObjectSchema<{
     readonly manifestId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>]>, undefined>;
     /** `custom`: optional path to the custom manifest within the repo. */
     readonly manifestPath: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    /**
+     * `kubernetes` (container-backed deploy adapter only): structured image overrides, the
+     * helm releases the env composes, and the Secrets to materialize before apply. The
+     * native REST adapter ignores these (raw manifests). See the schemas above.
+     */
+    readonly images: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.ObjectSchema<{
+        /** The image to match (the `name:` in a kustomization `images:` entry), e.g. `registry/app`. */
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        /** Optional replacement repo, templated; absent ⇒ keep the original repo. */
+        readonly newNameTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+        /** Replacement tag, templated (e.g. `{{branch}}` / `{{sha}}`); mutually exclusive with digest. */
+        readonly newTagTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+        /** Replacement digest, templated; alternative to a tag. */
+        readonly digestTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    }, undefined>, v.CheckAction<{
+        name: string;
+        newNameTemplate?: string | undefined;
+        newTagTemplate?: string | undefined;
+        digestTemplate?: string | undefined;
+    }, "an image override must set at least one of newNameTemplate, newTagTemplate, or digestTemplate.">, v.CheckAction<{
+        name: string;
+        newNameTemplate?: string | undefined;
+        newTagTemplate?: string | undefined;
+        digestTemplate?: string | undefined;
+    }, "newTagTemplate and digestTemplate are mutually exclusive on an image override.">]>, undefined>, undefined>;
+    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>;
+    readonly secretInjections: v.OptionalSchema<v.ArraySchema<v.VariantSchema<"mode", [v.ObjectSchema<{
+        readonly mode: v.LiteralSchema<"secret", undefined>;
+        /** Target Secret name in the namespace. */
+        readonly secretName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        /** Secret `type`; absent ⇒ `Opaque`. */
+        readonly secretType: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        readonly entries: v.ArraySchema<v.SchemaWithPipe<readonly [v.ObjectSchema<{
+            /** Key inside the rendered Secret / `.env`. */
+            readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 256, undefined>]>;
+            /** Resolve the value from the workspace encrypted bundle by key. */
+            readonly secretRef: v.OptionalSchema<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>;
+            /** OR a non-secret value, templated over the provision vars. */
+            readonly valueTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+        }, undefined>, v.CheckAction<{
+            key: string;
+            secretRef?: {
+                key: string;
+            } | undefined;
+            valueTemplate?: string | undefined;
+        }, "a secret entry must set exactly one of secretRef or valueTemplate.">]>, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly mode: v.LiteralSchema<"generatorEnvFile", undefined>;
+        /**
+         * Repo-relative path within the overlay tree to write the `KEY=value` env file the
+         * overlay's `secretGenerator` reads (e.g. `overlays/<env>/<component>/.env`). The
+         * overlay names the Secret.
+         */
+        readonly envFilePath: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+        readonly entries: v.ArraySchema<v.SchemaWithPipe<readonly [v.ObjectSchema<{
+            /** Key inside the rendered Secret / `.env`. */
+            readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 256, undefined>]>;
+            /** Resolve the value from the workspace encrypted bundle by key. */
+            readonly secretRef: v.OptionalSchema<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>;
+            /** OR a non-secret value, templated over the provision vars. */
+            readonly valueTemplate: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+        }, undefined>, v.CheckAction<{
+            key: string;
+            secretRef?: {
+                key: string;
+            } | undefined;
+            valueTemplate?: string | undefined;
+        }, "a secret entry must set exactly one of secretRef or valueTemplate.">]>, undefined>;
+    }, undefined>], undefined>, undefined>, undefined>;
 }, undefined>;
 export type ServiceProvisioning = v.InferOutput<typeof serviceProvisioningSchema>;
 /**
@@ -766,7 +1068,13 @@ export declare const kubernetesEngineConfigSchema: v.ObjectSchema<{
     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}}`. */
+    /**
+     * 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<{
@@ -785,6 +1093,16 @@ export declare const kubernetesEngineConfigSchema: v.ObjectSchema<{
         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>;
@@ -794,6 +1112,41 @@ export declare const kubernetesEngineConfigSchema: v.ObjectSchema<{
     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>;
 export type KubernetesEngineConfig = v.InferOutput<typeof kubernetesEngineConfigSchema>;
 /**
@@ -944,7 +1297,13 @@ export declare const infraHandlerConfigSchema: v.VariantSchema<"engine", [v.Obje
         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}}`. */
+        /**
+         * 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<{
@@ -963,6 +1322,16 @@ export declare const infraHandlerConfigSchema: v.VariantSchema<"engine", [v.Obje
             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>;
@@ -972,6 +1341,41 @@ export declare const infraHandlerConfigSchema: v.VariantSchema<"engine", [v.Obje
         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>;
@@ -983,7 +1387,13 @@ export declare const infraHandlerConfigSchema: v.VariantSchema<"engine", [v.Obje
         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}}`. */
+        /**
+         * 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<{
@@ -1002,6 +1412,16 @@ export declare const infraHandlerConfigSchema: v.VariantSchema<"engine", [v.Obje
             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>;
@@ -1011,6 +1431,41 @@ export declare const infraHandlerConfigSchema: v.VariantSchema<"engine", [v.Obje
         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>;
@@ -1381,6 +1836,7 @@ export declare const environmentConnectionSchema: v.ObjectSchema<{
                 readonly type: v.LiteralSchema<"colocated", undefined>;
                 /** File or directory path within the PR repo (read at the PR head branch). */
                 readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+                readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
             }, undefined>, v.ObjectSchema<{
                 readonly type: v.LiteralSchema<"separate", undefined>;
                 /** `owner/repo` of the manifests repo. */
@@ -1389,6 +1845,7 @@ export declare const environmentConnectionSchema: v.ObjectSchema<{
                 readonly ref: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
                 /** File or directory path within the manifests repo. */
                 readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+                readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
             }, undefined>], undefined>;
             /** How the environment URL is derived once applied. */
             readonly url: v.VariantSchema<"source", [v.ObjectSchema<{
@@ -1407,6 +1864,16 @@ export declare const environmentConnectionSchema: v.ObjectSchema<{
                 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}}` (e.g. a
@@ -1716,6 +2183,7 @@ export declare const registerEnvironmentProviderSchema: v.ObjectSchema<{
                 readonly type: v.LiteralSchema<"colocated", undefined>;
                 /** File or directory path within the PR repo (read at the PR head branch). */
                 readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+                readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
             }, undefined>, v.ObjectSchema<{
                 readonly type: v.LiteralSchema<"separate", undefined>;
                 /** `owner/repo` of the manifests repo. */
@@ -1724,6 +2192,7 @@ export declare const registerEnvironmentProviderSchema: v.ObjectSchema<{
                 readonly ref: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
                 /** File or directory path within the manifests repo. */
                 readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+                readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
             }, undefined>], undefined>;
             /** How the environment URL is derived once applied. */
             readonly url: v.VariantSchema<"source", [v.ObjectSchema<{
@@ -1742,6 +2211,16 @@ export declare const registerEnvironmentProviderSchema: v.ObjectSchema<{
                 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}}` (e.g. a
@@ -2053,6 +2532,7 @@ export declare const testEnvironmentConnectionSchema: v.ObjectSchema<{
                 readonly type: v.LiteralSchema<"colocated", undefined>;
                 /** File or directory path within the PR repo (read at the PR head branch). */
                 readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+                readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
             }, undefined>, v.ObjectSchema<{
                 readonly type: v.LiteralSchema<"separate", undefined>;
                 /** `owner/repo` of the manifests repo. */
@@ -2061,6 +2541,7 @@ export declare const testEnvironmentConnectionSchema: v.ObjectSchema<{
                 readonly ref: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
                 /** File or directory path within the manifests repo. */
                 readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+                readonly renderer: v.OptionalSchema<v.PicklistSchema<["raw", "kustomize"], undefined>, undefined>;
             }, undefined>], undefined>;
             /** How the environment URL is derived once applied. */
             readonly url: v.VariantSchema<"source", [v.ObjectSchema<{
@@ -2079,6 +2560,16 @@ export declare const testEnvironmentConnectionSchema: v.ObjectSchema<{
                 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}}` (e.g. a