@konfig.ts/k8s 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present David Stahl-Gruber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @konfig.ts/k8s
+
+Kubernetes resource constructors with branded references on top of
+`@konfig.ts/core`'s `Manifest<A>` carrier. The brands are where the
+package earns its keep: cross-resource invariants (env-var → Secret,
+volume → ConfigMap, Ingress TLS → Secret) are checked at the type level,
+and the `Dep.*` tracking propagates needs/provides through Effect
+`Layer`s.
+
+## Branded references
+
+```ts
+import { ConfigMapRef, SecretRef, ServiceAccountRef } from "@konfig.ts/k8s"
+
+const apiCreds = SecretRef.of("api-creds") // SecretRef<"api-creds">
+const cfg = ConfigMapRef.of("oauth-templates") // ConfigMapRef<"oauth-templates">
+const sa = ServiceAccountRef.of("api") // ServiceAccountRef<"api">
+```
+
+Each ref carries the resource _name_ in its type parameter. The
+enforcement points (env var `secretKeyRef` / `configMapKeyRef`, volume
+secret, volume configMap, `imagePullSecret`, Ingress TLS) all accept the
+branded type and reject raw strings.
+
+## Identity constructors expose `.ref`
+
+```ts
+const apiSecret = Secret.make({ name: "api-creds", namespace: "prod", stringData: {...} });
+// apiSecret.ref is a SecretRef<"api-creds">
+```
+
+The `.ref` accessor means consumers wire the brand through without
+restating the name:
+
+```ts
+const env = secretEnv("DATABASE_URL", { ref: apiSecret.ref, key: "url" })
+```
+
+## Env-var helpers
+
+| Helper                                      | Rejects raw string for |
+| ------------------------------------------- | ---------------------- |
+| `valueEnv(name, value)`                     | n/a                    |
+| `secretEnv(name, {ref, key, optional?})`    | `ref`                  |
+| `configMapEnv(name, {ref, key, optional?})` | `ref`                  |
+| `rawEnv({name, value?, valueFrom?})`        | n/a (escape hatch)     |
+
+## Volume helpers
+
+| Helper                              |
+| ----------------------------------- |
+| `volumeFromSecret(name, ref)`       |
+| `volumeFromConfigMap(name, ref)`    |
+| `emptyDirVolume(name, opts?)`       |
+| `pvcVolume(name, claimName, opts?)` |
+
+## Constructors
+
+Workload-tier (`Deployment.make`, `StatefulSet.make`, `Job.make`,
+`CronJob.make`) accept typed containers, `Volume`s,
+`imagePullSecrets: { name: SecretRef<N> }[]`, and
+`serviceAccountName: ServiceAccountRef | string`.
+
+Network-tier (`Service.make`, `Ingress.make`). Ingress TLS uses the
+`ingressTLS(secretName, hosts?)` helper for branded refs.
+
+Identity-tier (`Namespace.make`, `ServiceAccount.make`, `ConfigMap.make`,
+`Secret.make`) return constructors whose returned record carries the
+typed `.ref`.
+
+Policy-tier (`PersistentVolume.make`, `PersistentVolumeClaim.make`,
+`NetworkPolicy.make`, `ClusterRole.make`, `ClusterRoleBinding.make`,
+`Role.make`, `RoleBinding.make`) — simple constructors with no extra
+dependencies.
+
+## Higher-level: `Workload.web` and `Workload.cron`
+
+Built for the workload shapes consumers need today — not speculative.
+
+`Workload.web(...)` composes Deployment + Service + (optional) Ingress
+with derived labels (`app: <name>`). `Workload.cron(...)` composes
+CronJob + ServiceAccount (the SA is private to the cron).
+
+## Secret rotation — build-time hash vs runtime Reloader
+
+konfig provides two complementary stories for restarting pods when a
+Secret or ConfigMap they consume changes:
+
+- **Build time** (`hashSecretValues` / `pod-hash` annotation). A SHA of
+  the secret material lives on the pod spec; re-rendering after a
+  rotation produces a new hash, so the Deployment's pod template
+  changes and Kubernetes rolls. Fast feedback, deterministic — but only
+  fires when konfig re-renders.
+
+- **Runtime** (`Workload.web({ reloader: "stakater" })`). Emits
+  `reloader.stakater.com/auto: "true"` on the Deployment so
+  [Stakater Reloader](https://github.com/stakater/Reloader) watches
+  every referenced Secret/ConfigMap and patches the workload when the
+  in-cluster object changes. Pair with `ExternalSecrets` or a
+  controller that updates Secrets out-of-band.
+
+Pick build-time hashes for stateless render → apply pipelines; pick
+Reloader when secrets rotate independently of CI. They compose — a
+config-managed Secret with `reloader: "stakater"` rolls on both
+re-render and on out-of-band updates.
+
+## Secret backends — `SecretBackend<N, K>`
+
+`SecretBackend` is the contract Sops / SealedSecrets / ExternalSecrets
+implement. `Secret.bind({ secret, backend, source? })` ties an env-bundle
+secret to a backend emission. `backend.requiresSource` is `true` for
+Sops and SealedSecrets (they need plaintext at render time) and `false`
+for ExternalSecrets (it just emits an `ExternalSecret` CR pointing at a
+remote store).
+
+## k8s 1.30 types
+
+Re-exported from `kubernetes-types@1.30.0` under
+`src/.generated/k8s-types/`. We pin to the cluster minor and ship the
+re-export rather than rolling our own OpenAPI codegen.
+
+## Layout
+
+```
+src/
+├── index.ts                  barrel
+├── .generated/k8s-types/     thin re-export from kubernetes-types
+├── refs.ts                   SecretRef, ConfigMapRef, ServiceAccountRef
+├── env.ts                    secretEnv, configMapEnv, valueEnv, rawEnv
+├── volume.ts                 volumeFromSecret, volumeFromConfigMap, ...
+├── container.ts              ContainerInput, PodSpecInput, imagePullSecret
+├── identity.ts               Namespace, ServiceAccount, ConfigMap, Secret
+├── workload.ts               Deployment, StatefulSet, Job, CronJob
+├── network.ts                Service, Ingress, ingressTLS
+├── policy.ts                 PV, PVC, NetworkPolicy, RBAC
+├── workloadHelpers.ts        Workload.web, Workload.cron
+└── backend.ts                SecretBackend contract + Secret.bind
+```
+
+## Requirements
+
+konfig.ts builds on [Effect](https://effect.website/), which is still in
+beta. Until Effect ships a stable 4.x, you must install the exact beta
+konfig is developed against:
+
+- **`effect@4.0.0-beta.70`** — required.
+- **`@effect/platform-node@4.0.0-beta.70`** — required only for `render()`
+  (the Node filesystem/subprocess entrypoint); manifest-only consumers can
+  omit it.
+
+The peer dependency is pinned to the exact version on purpose: Effect's beta
+line makes breaking changes between builds, so a looser range would surface
+as `ERESOLVE` install conflicts rather than a working install. This pin will
+relax to a caret range once Effect reaches a stable 4.x.

package/dist/.generated/k8s-types/index.d.ts

@@ -0,0 +1,6 @@
+export type { Deployment, DeploymentSpec, StatefulSet, StatefulSetSpec, } from "kubernetes-types/apps/v1";
+export type { CronJob, Job, JobSpec, } from "kubernetes-types/batch/v1";
+export type { ConfigMap, Container, ContainerPort, EnvVar, EnvVarSource, LocalObjectReference, Namespace, PersistentVolume, PersistentVolumeClaim, PodSpec, PodTemplateSpec, Secret, Service, ServiceAccount, ServicePort, Volume, VolumeMount, } from "kubernetes-types/core/v1";
+export type { ObjectMeta } from "kubernetes-types/meta/v1";
+export type { Ingress, IngressRule, IngressSpec, IngressTLS, NetworkPolicy, } from "kubernetes-types/networking/v1";
+export type { ClusterRole, ClusterRoleBinding, Role, RoleBinding, } from "kubernetes-types/rbac/v1";

package/dist/backend.d.ts

@@ -0,0 +1,26 @@
+import type { Manifest } from "@konfig.ts/core";
+import type { SecretSource } from "@konfig.ts/env";
+export type BackendTag = "Sops" | "Sops.passthrough" | "SealedSecrets" | "ExternalSecrets" | "NativeSecret";
+export interface BackendEmitInput<N extends string, K extends string> {
+    readonly name: N;
+    readonly namespace: string;
+    readonly keys: ReadonlyArray<K>;
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly annotations?: Readonly<Record<string, string>>;
+    readonly source?: SecretSource<K, Manifest.RenderServices>;
+}
+export interface SecretBackend<N extends string, K extends string, RequiresSource extends boolean = boolean> {
+    readonly _tag: BackendTag;
+    readonly requiresSource: RequiresSource;
+    readonly emit: (input: BackendEmitInput<N, K>) => Manifest.Manifest<unknown>;
+}
+declare const BackendSourceMissing_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BackendSourceMissing";
+} & Readonly<A>;
+export declare class BackendSourceMissing extends BackendSourceMissing_base<{
+    readonly backend: BackendTag;
+    readonly secret: string;
+}> {
+    get message(): string;
+}
+export {};

package/dist/container.d.ts

@@ -0,0 +1,190 @@
+import type { BuiltImageRef, SecretRef, ServiceAccountRef } from "@konfig.ts/core";
+import type { Container as K8sContainer, PodSpec as K8sPodSpec } from "./.generated/k8s-types";
+import type { EnvVar } from "./env";
+import type { ContainerPort, NamesOf, ProbeTarget } from "./ports";
+import type { Volume, VolumeMount, VolumeNamesOf } from "./volume";
+/**
+ * Container input — extends the full K8s Container API. Konfig's
+ * branded helpers (`EnvVar.value`, `EnvVar.fromSecret`,
+ * `EnvVar.fromConfigMap`) produce `EnvVar` instances whose runtime
+ * shape matches `K8sEnvVar`; the override
+ * here narrows the field to readonly + the branded helper output so
+ * `secretKeyRef.name` carries its `SecretRef<N>` brand at construction
+ * time.
+ *
+ * `image` is overridden as required (K8s lets it be optional for
+ * higher-level controllers that default it; konfig wants every
+ * container to have an explicit image).
+ *
+ * `ports[i].name` accepts the branded `PortName<string>` from `Port.make(...)`
+ * as well as a raw string; the typed builder `Container` is the
+ * link that captures the literal name union for cross-reference checks.
+ */
+export interface ContainerInput extends Omit<K8sContainer, "env" | "image" | "ports" | "readinessProbe" | "livenessProbe" | "startupProbe" | "volumeMounts"> {
+    /**
+     * Container image. Accepts a raw string (escape hatch for vendor
+     * images: `ghcr.io/bitnami/postgresql:16.0.0`) or a `BuiltImageRef<App>`
+     * produced by `Dep.builtImageRef` / `Dep.provideImage`. The branded
+     * path ties the workload into the dep graph — a workload referencing
+     * an image whose build module isn't in the composition fails at
+     * `AppOfApps.entrypoint`.
+     */
+    readonly image: string | BuiltImageRef<string>;
+    readonly env?: ReadonlyArray<EnvVar>;
+    readonly ports?: ReadonlyArray<ContainerPort | {
+        readonly containerPort: number;
+        readonly name?: string;
+        readonly protocol?: "TCP" | "UDP" | "SCTP";
+    }>;
+    /**
+     * Probes accept either the upstream K8s shape or konfig's branded
+     * `ProbeTarget<string>` (from `Container`). The two are
+     * structurally close — the union lets a `ContainerSpec` flow
+     * through `Workload.web`'s containers slot without a cast.
+     */
+    readonly readinessProbe?: K8sContainer["readinessProbe"] | ProbeTarget<string>;
+    readonly livenessProbe?: K8sContainer["livenessProbe"] | ProbeTarget<string>;
+    readonly startupProbe?: K8sContainer["startupProbe"] | ProbeTarget<string>;
+    /**
+     * Volume mounts accept the upstream K8s shape or konfig's branded
+     * `VolumeMount<string>` (from `Container` / `mountRef`). Same
+     * rationale as the probe widening above.
+     */
+    readonly volumeMounts?: K8sContainer["volumeMounts"] | ReadonlyArray<VolumeMount<string>>;
+}
+/**
+ * Strongly-typed container builder. Captures the union of named ports
+ * declared via `port({ name, containerPort })` as a phantom type
+ * parameter, then constrains every probe's `port` field to that union.
+ *
+ * Pair with `Service.fromContainer({ forContainer })` in `network.ts`
+ * to link a Service's `targetPort` to the same union — a typo or
+ * undeclared port name is a compile error.
+ */
+export interface ContainerSpec<Ports extends string = string, Mounts extends string = string> extends Omit<ContainerInput, "ports" | "readinessProbe" | "livenessProbe" | "startupProbe" | "volumeMounts"> {
+    readonly name: string;
+    readonly image: string;
+    readonly ports: ReadonlyArray<ContainerPort<Ports>>;
+    readonly readinessProbe?: ProbeTarget<Ports>;
+    readonly livenessProbe?: ProbeTarget<Ports>;
+    readonly startupProbe?: ProbeTarget<Ports>;
+    readonly volumeMounts?: ReadonlyArray<VolumeMount<Mounts>>;
+    readonly __portNames?: Ports;
+    readonly __mountNames?: Mounts;
+}
+export interface DefineContainerInput<Ports extends ReadonlyArray<ContainerPort<string>>, Mounts extends ReadonlyArray<VolumeMount<string>>, Envs extends ReadonlyArray<EnvVar<string>>> extends Omit<ContainerInput, "ports" | "readinessProbe" | "livenessProbe" | "startupProbe" | "volumeMounts" | "env"> {
+    readonly name: string;
+    readonly image: string;
+    readonly ports: Ports;
+    readonly readinessProbe?: ProbeTarget<NamesOf<Ports>>;
+    readonly livenessProbe?: ProbeTarget<NamesOf<Ports>>;
+    readonly startupProbe?: ProbeTarget<NamesOf<Ports>>;
+    readonly volumeMounts?: Mounts;
+    readonly env?: Envs & EnvDupCheck<Envs>;
+}
+type MountNamesOf<M extends ReadonlyArray<VolumeMount<string>>> = {
+    readonly [I in keyof M]: M[I] extends VolumeMount<infer N> ? N : never;
+}[number];
+type _EnvNameOf<X> = X extends EnvVar<infer N> ? N : never;
+/**
+ * Union of any literal env-var names that appear more than once in `Envs`.
+ * Computes the intersection of pairwise names — if `Envs[I]` and `Envs[J]`
+ * share a literal name (i ≠ j), that name leaks into the union. Empty
+ * when every name is unique.
+ */
+type DuplicateEnvNames<Envs extends ReadonlyArray<EnvVar<string>>> = {
+    [I in keyof Envs]: {
+        [J in keyof Envs]: J extends I ? never : _EnvNameOf<Envs[I]> & _EnvNameOf<Envs[J]> extends never ? never : _EnvNameOf<Envs[I]> & _EnvNameOf<Envs[J]>;
+    }[number];
+}[number];
+/**
+ * Empty (`unknown`) when `Envs` has no duplicate names; otherwise an
+ * inline object type whose required `_konfig_duplicate_env_names`
+ * property carries a template-literal hint sentence. Intersected with
+ * the `env` slot, an unmet property surfaces the sentence inline in the
+ * TS error — far more discoverable than a runtime "last-wins" surprise.
+ */
+type EnvDupCheck<Envs extends ReadonlyArray<EnvVar<string>>> = [
+    DuplicateEnvNames<Envs>
+] extends [never] ? unknown : {
+    readonly _konfig_duplicate_env_names: `Duplicate env name(s): "${DuplicateEnvNames<Envs>}". K8s silently last-wins; rename one of the colliding entries or remove the manual valueEnv that shadows another producer.`;
+};
+/**
+ * `Container` value namespace.
+ *
+ *   const apiContainer = Container.define({
+ *     name: "api",
+ *     image: apiImage,
+ *     ports: [Port.make({ name: "http", containerPort: 8080 })],
+ *     readinessProbe: { httpGet: { port: Port.ref("http") } },
+ *     env: [...],
+ *   });
+ *
+ * `Container.define` captures the union of named ports (from
+ * `Port.make`) as `Ports`, the union of mounted volume names (from
+ * `Volume.mountRef`) as `Mounts`, and validates that the `env` list
+ * has no duplicate env-var names. The first two phantoms travel on
+ * `ContainerSpec`; `Pod.define` checks the container's Mounts against
+ * the pod's declared volume names.
+ *
+ * Duplicate env names are caught at the call site via a template-literal
+ * error message — see `EnvDupCheck`. With no volumeMounts and no env,
+ * all phantoms collapse to `never` so the container slots into any pod.
+ */
+export declare const Container: {
+    define: <const Ports extends ReadonlyArray<ContainerPort<string>>, const Mounts extends ReadonlyArray<VolumeMount<string>> = readonly [], const Envs extends ReadonlyArray<EnvVar<string>> = readonly []>(input: DefineContainerInput<Ports, Mounts, Envs>) => ContainerSpec<NamesOf<Ports>, MountNamesOf<Mounts>>;
+};
+/**
+ * `Pod.define` input. The pod declares a tuple of `Volume`s and lists
+ * containers whose `Mounts` phantom is checked against the declared
+ * volume names via `NoInfer`. A container referencing an undeclared
+ * volume — or a typo — fails at the call site rather than at pod-startup
+ * time with "container references volume not found."
+ */
+export interface DefinePodInput<V extends ReadonlyArray<Volume<string>>> {
+    readonly volumes: V;
+    readonly containers: ReadonlyArray<ContainerSpec<string, NoInfer<VolumeNamesOf<V>>>>;
+    readonly initContainers?: ReadonlyArray<ContainerSpec<string, NoInfer<VolumeNamesOf<V>>>>;
+}
+export interface DefinedPod<MountNames extends string> {
+    readonly volumes: ReadonlyArray<Volume<MountNames>>;
+    readonly containers: ReadonlyArray<ContainerSpec<string, MountNames>>;
+    readonly initContainers?: ReadonlyArray<ContainerSpec<string, MountNames>>;
+}
+/**
+ * Pod spec input — extends K8s PodSpec but tightens the fields where
+ * konfig adds brand checking: `imagePullSecrets`, `serviceAccountName`,
+ * and `volumes` (the helpers in `volume.ts` produce konfig `Volume`
+ * objects that lower to K8s `Volume`).
+ */
+export interface PodSpecInput extends Omit<K8sPodSpec, "containers" | "initContainers" | "volumes" | "imagePullSecrets" | "serviceAccountName"> {
+    readonly containers: ReadonlyArray<ContainerInput>;
+    readonly initContainers?: ReadonlyArray<ContainerInput>;
+    readonly volumes?: ReadonlyArray<Volume>;
+    readonly imagePullSecrets?: ReadonlyArray<{
+        readonly name: SecretRef<string>;
+    }>;
+    readonly serviceAccountName?: ServiceAccountRef<string> | string;
+}
+/**
+ * `Pod` value namespace.
+ *
+ *   const pod = Pod.define({
+ *     volumes: [Volume.empty({ name: "config" })],
+ *     containers: [Container.define({ ..., volumeMounts: [...] })],
+ *   });
+ *
+ *   imagePullSecrets: [Pod.imagePullSecret(ghcrRef)],
+ *
+ * - `Pod.define(input)` ties container `volumeMounts[i].name` to the
+ *   pod's declared volume names via `NoInfer`.
+ * - `Pod.imagePullSecret(ref)` returns the `{ name: SecretRef }` entry
+ *   consumed by Deployment / StatefulSet / Job / CronJob workloads.
+ */
+export declare const Pod: {
+    define: <const V extends ReadonlyArray<Volume<string>>>(input: DefinePodInput<V>) => DefinedPod<VolumeNamesOf<V>>;
+    imagePullSecret: (ref: SecretRef<string>) => {
+        readonly name: SecretRef<string>;
+    };
+};
+export {};

package/dist/env.d.ts

@@ -0,0 +1,110 @@
+import type { ConfigMapRef, SecretRef } from "@konfig.ts/core";
+export interface EnvVarSource {
+    readonly secretKeyRef?: {
+        readonly name: string;
+        readonly key: string;
+        readonly optional?: boolean;
+    };
+    readonly configMapKeyRef?: {
+        readonly name: string;
+        readonly key: string;
+        readonly optional?: boolean;
+    };
+    readonly fieldRef?: {
+        readonly fieldPath: string;
+        readonly apiVersion?: string;
+    };
+    readonly resourceFieldRef?: {
+        readonly containerName?: string;
+        readonly resource: string;
+    };
+}
+/**
+ * Container env-var entry. The phantom `N` records the literal env-var
+ * name at the type level so `Container` can detect duplicates
+ * across the entry list. The default `N = string` preserves loose-typed
+ * call sites.
+ */
+export interface EnvVarShape<N extends string = string> {
+    readonly name: N;
+    readonly value?: string;
+    readonly valueFrom?: EnvVarSource;
+}
+export interface ValueEnvInput<N extends string> {
+    readonly name: N;
+    readonly value: string;
+}
+export interface SecretEnvInput<EnvName extends string, N extends string, K extends string> {
+    readonly name: EnvName;
+    readonly ref: SecretRef<N, K>;
+    /**
+     * Constrained to the keys carried by `ref`. `NoInfer` locks `K` to
+     * whatever the ref declares, so the typo `key: "passowrd"` fails at
+     * compile time when the ref's K is `"url" | "username" | "password"`.
+     * Refs constructed with the default `K = string` accept any string.
+     */
+    readonly key: NoInfer<K>;
+    readonly optional?: boolean;
+}
+export interface SecretEnvForPodInput<EnvName extends string, N extends string, K extends string, Ns extends string> {
+    readonly name: EnvName;
+    /**
+     * Ref whose namespace slot must match `podNamespace`. Pass refs that
+     * came from `Secret.make({ namespace })` in the same namespace as
+     * the consuming pod. For legitimate cross-namespace cases, widen
+     * via `SecretRef.unsafeReNamespace(ref)` first.
+     */
+    readonly ref: SecretRef<N, K, NoInfer<Ns>>;
+    readonly key: NoInfer<K>;
+    readonly podNamespace: Ns;
+    readonly optional?: boolean;
+}
+export interface ConfigMapEnvInput<EnvName extends string, N extends string, K extends string> {
+    readonly name: EnvName;
+    readonly ref: ConfigMapRef<N, K>;
+    /**
+     * Constrained to the keys carried by `ref`. `NoInfer` locks `K` to
+     * whatever the ref declares — typos like `key: "passwrod"` fail at
+     * compile time when the ref's K is `"HOST" | "PORT" | "LOG_LEVEL"`.
+     * Refs constructed with the default `K = string` accept any string.
+     */
+    readonly key: NoInfer<K>;
+    readonly optional?: boolean;
+}
+export interface RawEnvInput<N extends string> {
+    readonly name: N;
+    readonly value?: string;
+    readonly valueFrom?: EnvVarSource;
+}
+/**
+ * `EnvVar` value namespace.
+ *
+ *   env: [
+ *     EnvVar.value({ name: "PORT", value: "8080" }),
+ *     EnvVar.fromSecret({ name: "DB_URL", ref: dbCreds.ref, key: "url" }),
+ *     EnvVar.fromSecretForPod({
+ *       name: "DB_URL_PRIMARY", ref: dbCreds.ref, key: "url",
+ *       podNamespace: "app",
+ *     }),
+ *     EnvVar.fromConfigMap({ name: "NEW_UI", ref: flags.ref, key: "NEW_UI" }),
+ *     EnvVar.raw({ name: "POD_NAME", valueFrom: { fieldRef: ... } }),
+ *   ]
+ *
+ * Each constructor captures the literal env-var name (`N`) so
+ * `Container` can detect duplicate entries across the env list.
+ */
+export declare const EnvVar: {
+    value: <const N extends string>(input: ValueEnvInput<N>) => EnvVar<N>;
+    fromSecret: <const EnvName extends string, N extends string, K extends string = string>(input: SecretEnvInput<EnvName, N, K>) => EnvVar<EnvName>;
+    /**
+     * Namespace-checked variant. The ref's namespace slot (`Ns`) must
+     * match `podNamespace`. Catches "pod in namespace A references a
+     * Secret in namespace B" at compile time — kube-apiserver only
+     * resolves `valueFrom.secretKeyRef` against the pod's own namespace,
+     * so cross-namespace refs are runtime errors.
+     */
+    fromSecretForPod: <const EnvName extends string, N extends string, K extends string, const Ns extends string>(input: SecretEnvForPodInput<EnvName, N, K, Ns>) => EnvVar<EnvName>;
+    fromConfigMap: <const EnvName extends string, N extends string, K extends string = string>(input: ConfigMapEnvInput<EnvName, N, K>) => EnvVar<EnvName>;
+    raw: <const N extends string>(input: RawEnvInput<N>) => EnvVar<N>;
+};
+export type EnvVar<N extends string = string> = EnvVarShape<N>;

package/dist/environmentBind.d.ts

@@ -0,0 +1,133 @@
+import { type Manifest, type RenderError } from "@konfig.ts/core";
+import type { DownwardEntry, EnvMember, Environment, LiteralEntry, SecretEntry, SecretSource } from "@konfig.ts/env";
+import { Layer } from "effect";
+import type { SecretBackend } from "./backend";
+import type { EnvVar } from "./env";
+import { type DeclaredSecret } from "./secretBind";
+export interface DeclaredLiteral<EnvName extends string, T> {
+    readonly envName: EnvName;
+    readonly value: T;
+    readonly envVar: EnvVar;
+}
+export interface DeclaredDownward<EnvName extends string> {
+    readonly envName: EnvName;
+    readonly fieldPath: string;
+    readonly envVar: EnvVar;
+}
+/**
+ * Per-member declared shape produced by `Environment.bind`. Mirrors the
+ * structure of the bundle: secrets give `DeclaredSecret`, literals
+ * `DeclaredLiteral`, downwards `DeclaredDownward`, and nested
+ * `Environment` members give a `members` sub-record with the same
+ * recursive shape.
+ */
+export type DeclaredMember<A extends EnvMember, Ns extends string = string> = A extends SecretEntry<infer N, infer K, infer _E> ? [N, K] extends [string, string] ? DeclaredSecret<N, K, Ns> : never : A extends LiteralEntry<infer EnvName, infer T> ? [EnvName] extends [string] ? DeclaredLiteral<EnvName, T> : never : A extends DownwardEntry<infer EnvName> ? [EnvName] extends [string] ? DeclaredDownward<EnvName> : never : A extends Environment<infer SubM> ? {
+    readonly [K in keyof SubM]: DeclaredMember<SubM[K], Ns>;
+} : never;
+export interface DeclaredEnvironment<M extends Readonly<Record<string, EnvMember>>, Ns extends string = string> {
+    readonly envVars: ReadonlyArray<EnvVar>;
+    readonly manifests: ReadonlyArray<Manifest.Manifest<unknown>>;
+    readonly members: {
+        readonly [K in keyof M]: DeclaredMember<M[K], Ns>;
+    };
+    readonly valuesLayer: Layer.Layer<unknown, RenderError, Manifest.RenderServices>;
+}
+interface _SecretMemberOptionsBase {
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly annotations?: Readonly<Record<string, string>>;
+}
+interface _SecretMemberBackendRequiresSource<N extends string, K extends string> extends _SecretMemberOptionsBase {
+    readonly backend: SecretBackend<N, K, true>;
+    readonly source: SecretSource<K, Manifest.RenderServices>;
+}
+interface _SecretMemberBackendOptionalSource<N extends string, K extends string> extends _SecretMemberOptionsBase {
+    readonly backend: SecretBackend<N, K, false>;
+    readonly source?: SecretSource<K, Manifest.RenderServices>;
+}
+interface _SecretMemberSourceOnly<_N extends string, K extends string> extends _SecretMemberOptionsBase {
+    readonly backend?: undefined;
+    readonly source: SecretSource<K, Manifest.RenderServices>;
+}
+/**
+ * Per-secret-member options at bind time. Backends with `RequiresSource: true`
+ * (`Sops.backend`, `SealedSecrets.backend`, `NativeSecret.backend`) make
+ * `source` mandatory at the type level. Backends with `false`
+ * (`ExternalSecrets.backend`, `Sops.passthrough`) make it optional. With no
+ * backend, `source` becomes mandatory — used to feed the in-process
+ * `SecretValues` layer for tests / local renders.
+ */
+export type SecretMemberOptions<N extends string, K extends string> = _SecretMemberBackendRequiresSource<N, K> | _SecretMemberBackendOptionalSource<N, K> | _SecretMemberSourceOnly<N, K>;
+export type SecretMemberOptionsFor<A> = A extends SecretEntry<infer N, infer K, infer _E> ? [N, K] extends [string, string] ? SecretMemberOptions<N, K> : never : never;
+/**
+ * True iff `M` (recursively, via nested `Environment` members)
+ * contains at least one `SecretEntry`. Used to flip `secrets` between
+ * required (any secrets present) and optional (literals/downwards
+ * only) on `BindEnvironmentInput`.
+ */
+export type HasSecrets<M extends Readonly<Record<string, EnvMember>>> = true extends {
+    readonly [K in keyof M]: M[K] extends SecretEntry<infer _N, infer _K, infer _E> ? true : M[K] extends Environment<infer Sub> ? HasSecrets<Sub> : false;
+}[keyof M] ? true : false;
+/**
+ * Recursive per-member secret options. For a secret member, the option
+ * matches its `SecretMemberOptionsFor` and is required. For a nested
+ * `Environment` member that itself contains secrets, the option is
+ * `SecretMembersOpts<SubM>` and is also required. Nested environments
+ * with no secrets are omitted entirely (no key needed).
+ *
+ * Together with `HasSecrets`, this enforces at compile time that every
+ * `Secret` reachable from the bundle is acknowledged at bind
+ * time — adding a new secret to the env contract forces every call
+ * site to update.
+ */
+export type SecretMembersOpts<M extends Readonly<Record<string, EnvMember>>> = {
+    readonly [K in keyof M as M[K] extends SecretEntry<infer _N, infer _K, infer _E> ? K : M[K] extends Environment<infer SubM> ? HasSecrets<SubM> extends true ? K : never : never]: M[K] extends SecretEntry<infer _N, infer _K, infer _E> ? SecretMemberOptionsFor<M[K]> : M[K] extends Environment<infer SubM> ? SecretMembersOpts<SubM> : never;
+};
+/**
+ * Per-literal value override for bind time. Keyed by member name, typed
+ * to each literal's declared `T`. Useful when a `Literal` is a
+ * runtime contract (carries a `schema: Config.string(envName)` for app
+ * code to yield) but the manifest's emitted value differs per env —
+ * e.g. `CLIENT_URL`, `S3_ENDPOINT`, host/URL literals.
+ *
+ * Recurses on nested `Environment` members — pass `{group: {host: "x"}}`
+ * to override a literal nested inside a sub-bundle.
+ */
+export type LiteralMembersOpts<M extends Readonly<Record<string, EnvMember>>> = {
+    readonly [K in keyof M as M[K] extends LiteralEntry<infer _EnvName, infer _T> ? K : M[K] extends Environment<infer _SubM> ? K : never]?: M[K] extends LiteralEntry<infer _EnvName, infer T> ? T : M[K] extends Environment<infer SubM> ? LiteralMembersOpts<SubM> : never;
+};
+interface _BindEnvironmentInputBase<M extends Readonly<Record<string, EnvMember>>, Ns extends string = string> {
+    readonly env: Environment<M>;
+    /**
+     * Per-literal value override for the manifest's emitted env var. The
+     * runtime read (via `entry.schema`, if provided) is unchanged —
+     * overrides only affect what the konfig module writes into the
+     * Deployment's `env` array.
+     */
+    readonly literals?: LiteralMembersOpts<M>;
+    /**
+     * Override every secret member's namespace for this bind. Useful when
+     * the bundle is consumed across multiple k8s namespaces (e.g. prod /
+     * staging / local) without redeclaring each contract. Recurses into
+     * nested `Environment` members.
+     *
+     * When passed as a string literal, the literal flows into each
+     * `DeclaredSecret.ref`'s brand so `secretEnvForPod` can enforce
+     * cross-namespace coherence on hand-spliced env entries.
+     */
+    readonly namespace?: Ns;
+}
+/**
+ * `secrets` flips between required and optional based on whether `M`
+ * actually contains any secrets. A bundle of literals/downwards only
+ * has nothing to bind, so `secrets` stays optional. A bundle with even
+ * one `Secret` (directly or nested) forces the caller to supply
+ * every secret member — and for each member, either a `backend` or a
+ * `source` (see `SecretMemberOptions`).
+ */
+export type BindEnvironmentInput<M extends Readonly<Record<string, EnvMember>>, Ns extends string = string> = _BindEnvironmentInputBase<M, Ns> & (HasSecrets<M> extends true ? {
+    readonly secrets: SecretMembersOpts<M>;
+} : {
+    readonly secrets?: SecretMembersOpts<M>;
+});
+export declare const bindEnvironment: <const M extends Readonly<Record<string, EnvMember>>, const Ns extends string = string>(input: BindEnvironmentInput<M, Ns>) => DeclaredEnvironment<M, Ns>;
+export {};