@konfig.ts/core 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,181 @@
+# @konfig.ts/core
+
+The Kubernetes-agnostic primitives that the rest of konfig.ts builds on:
+the `Manifest<A>` carrier, the `Dep.*` kinds that drive compile-time
+dependency tracking, a stable YAML serializer, structural diff, an Effect
+`Schema` boundary helper, and the `Helm.release` integration.
+
+Higher-level surfaces — workloads, services, env contracts, ArgoCD
+Application aggregation — live in `@konfig.ts/k8s`, `@konfig.ts/env`,
+and `@konfig.ts/argocd`.
+
+## `Manifest<A>` — the carrier
+
+A `Manifest<A>` is a thunk from a `RenderContext` to an Effect that
+produces an `A`:
+
+```ts
+interface Manifest<A> {
+  readonly render: (
+    ctx: RenderContext
+  ) => Effect.Effect<A, AnyRenderError, RenderServices>
+}
+```
+
+`RenderServices` is `FileSystem | Path | ChildProcessSpawner | Scope`.
+Errors are a tagged union: `RenderError`, `EmbedYamlReadError`,
+`BoundaryDecodeError`, `HelmVersionTooLow`, `HelmRenderError`,
+`HelmDigestMismatch`, `CrdExtractError`.
+
+Constructors:
+
+| Op                                   | Behaviour                                      |
+| ------------------------------------ | ---------------------------------------------- |
+| `Manifest.make(run)`                 | Lift a `ctx → A \| Effect<A>` into a Manifest. |
+| `Manifest.combine({ a, b })`         | Render `a` and `b` concurrently into a tuple.  |
+| `Manifest.concat(...ms)`             | Flatten an array of Manifests into one.        |
+| `Manifest.whenever({ cond, thunk })` | Optional inclusion.                            |
+| `Manifest.embedYaml(source)`         | Pass through verbatim YAML (file or literal).  |
+
+The `Manifest<A>` itself is not where dependency-tracking happens — it
+just carries data and effect failures. The compile-time graph lives
+one level up; see below.
+
+## Where the type-safety lives
+
+konfig's dep-graph claim has two boundaries:
+
+1. **`AppOfApps.entrypoint(program)`** in `@konfig.ts/argocd`. Every
+   `Application.define({...})` produces an Effect `Layer.Layer<Out, _, In>`
+   that propagates the `Dep.Provide<K, N>` it produces in `Out` and the
+   `Dep.Need<K, N>` it consumes in `In`. Compose with `Layer.provideMerge`,
+   pass to `entrypoint`, and TypeScript checks `In === never`. A missing
+   provider is a compile error — see
+   [`examples/full-stack/infra/envs/broken.ts`](../../examples/full-stack/infra/envs/broken.ts).
+
+2. **`Environment.bind({ env, secrets })`** in `@konfig.ts/env`. The
+   bundle's secret atoms describe `{ envName, secret, key }` triples; the
+   `bind` checks at the type level that every secret has a backend, the
+   backend's `keys` set matches the bundle's keys, and a `requiresSource`
+   backend has a `source` of the right key shape.
+
+Inside a single `Application.define({ build })` Effect, dep tracking is
+declarative: when you `yield* Dep.Secret("ghcr-pull")` to obtain a
+`SecretRef<"ghcr-pull">`, you add the `Need` to the requirements. Forget
+to yield, and nothing complains — the system catches misses at
+composition, not inside an Application's body.
+
+## `Dep.*` — tracked kinds
+
+```ts
+import { Dep } from "@konfig.ts/core"
+```
+
+| Kind                              | Service                        | Provided value                            |
+| --------------------------------- | ------------------------------ | ----------------------------------------- |
+| `Dep.App<Name>(name)`             | `Need<"App", Name>`            | `Application` record                      |
+| `Dep.Application<Name>(name)`     | `Need<"Application", Name>`    | `Name` literal                            |
+| `Dep.Namespace<Name>(name)`       | `Need<"Namespace", Name>`      | `Name` literal                            |
+| `Dep.Secret<Name>(name)`          | `Need<"Secret", Name>`         | `SecretRef<Name>` brand                   |
+| `Dep.SecretValues<Name, K>(name)` | `Need<"SecretValues", Name>`   | `{ readonly [k in K]: Redacted<string> }` |
+| `Dep.ConfigMap<Name>(name)`       | `Need<"ConfigMap", Name>`      | `ConfigMapRef<Name>` brand                |
+| `Dep.ServiceAccount<Name>(name)`  | `Need<"ServiceAccount", Name>` | `ServiceAccountRef<Name>` brand           |
+| `Dep.Pvc<Name>(name)`             | `Need<"Pvc", Name>`            | `PvcRef<Name>` brand                      |
+
+For each kind there's a matching `provideX` helper (`provideSecret`,
+`provideNamespace`, …) that emits a `Layer.Layer<Provide<K, N>>`.
+
+`brand(value)` and `unsafeCoerce(value, reason)` from `@konfig.ts/core`
+are escape hatches. `brand` is fine — it's a nominal-typing primitive
+for the `*Ref` types. `unsafeCoerce` is the unchecked cast and takes a
+mandatory reason string so every call site documents WHY the cast is
+sound; prefer the schema boundary below for values crossing a trust
+boundary. (`coerce` is deprecated and will be removed before 1.0.)
+
+## Stable YAML — `Yaml.serialize({ value })`
+
+Output rules:
+
+- Top-level keys ordered: `apiVersion`, `kind`, `metadata`, `spec`,
+  `status`, then alphabetical.
+- Inside `metadata`: `name`, `namespace`, `labels`, `annotations`, then
+  alphabetical.
+- Every other map: alphabetical.
+- Lists preserve insertion order.
+- LF endings, 2-space indent, single trailing newline.
+- YAML 1.1 explicit (kubectl/ArgoCD compatibility).
+
+`Yaml.filenameFor(resource)` returns `<Kind>-<metadata.name>.yaml` —
+deterministic per-resource filenames for ArgoCD-friendly diffs.
+
+## Structural diff — `diffFiles({ left, right })`
+
+Each file's YAML is parsed and redacted (Helm-volatile metadata stripped)
+before deep-equality. Output is `Map<filename, FileDiff>`, formatted via
+`formatDiff(result, "summary" | "detail" | "json")`. Today's diff is
+two-way only and treats each file as a single document; richer per-doc
+and anchor-aware diffing is on the roadmap.
+
+## `Helm.release({...})`
+
+Calls `helm pull` and `helm template`, lifts each emitted YAML document
+as a `RawYaml` Manifest under the parent Application. SHA-256 of the
+`.tgz` is verified against `opts.digest` after pull **and** on every
+cache hit — flipping a byte in a cached tarball fails the next render
+with `HelmDigestMismatch`.
+
+`opts.digest` must include the `sha256:` prefix; the cache file name
+includes the first 12 hex digits, but the verifier compares the full
+hash.
+
+## Boundary decode — `boundary({ schema, label })`
+
+Wraps `Schema.decodeUnknownEffect` so that any decode failure becomes
+a `BoundaryDecodeError` with `schema: label`. Use at the seams where
+untyped input enters a module:
+
+```ts
+const decodeApiOptions = boundary({ schema: ApiOptions, label: "api" })
+const cfg = yield * decodeApiOptions(input)
+```
+
+Every place that previously did `coerce<T>(YAML.parse(stdout))` over
+untrusted external output is now expected to use this helper.
+
+## Layout
+
+```
+src/
+├── index.ts              barrel
+├── _cast.ts              brand + coerce (escape hatch)
+├── boundary.ts           Schema.decode wrapper → BoundaryDecodeError
+├── deps.ts               Dep.* kinds + provide* helpers
+├── diff.ts               structural diff + redaction
+├── Helm.ts               Helm.release with digest verification
+├── images.ts             ImagesConfig + decoders
+├── konfigConfig.ts       KonfigConfig schema (top-level config)
+├── Manifest.ts           Manifest interface + combinators
+├── render.ts             render entrypoint
+├── RenderContext.ts      threaded through every render
+├── RenderError.ts        tagged error union
+├── types.ts              Kind enum (legacy; superseded by Dep.*)
+└── yaml/
+    ├── index.ts
+    └── serialize.ts      stable YAML serializer + filenameFor
+```
+
+## 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/Bundle.d.ts

@@ -0,0 +1,125 @@
+import * as Compose from "./Compose";
+import * as Dep from "./deps";
+import type * as CoreManifest from "./Manifest";
+import type * as Module from "./Module";
+import type { AnyRenderError } from "./RenderError";
+import { type Context, Effect, Layer } from "effect";
+export interface Bundle {
+    readonly name: string;
+    readonly namespace?: string;
+    readonly manifests: ReadonlyArray<unknown>;
+}
+export interface BundleMakeOptions {
+    readonly name: string;
+    readonly namespace?: string;
+    readonly manifests: ReadonlyArray<unknown>;
+}
+export declare const make: (opts: BundleMakeOptions) => Bundle;
+/**
+ * Handle returned by `Bundle.define`. Same yieldable-Context-Tag +
+ * `.layer` pattern as argocd's `ApplicationHandle`; only the carried
+ * value type differs (a plain `Bundle` with no argo source/syncPolicy).
+ * `Dep.Need<"App", Name>` keys the dep graph by literal name so
+ * sibling modules can `yield* bundleHandle` to consume it.
+ */
+export interface BundleHandle<Name extends string, Out, In> extends Context.Service<Dep.Need<"App", Name>, Bundle> {
+    readonly layer: Layer.Layer<Out, AnyRenderError, In>;
+}
+/**
+ * Higher-kinded handle constructor that maps `Module`'s
+ * `(Name, Ns, R, Extra)` slots onto a `BundleHandle`. Lets
+ * `Module.fixedNs({ target: Bundle.target, … })` /
+ * `Module.dynamicNs({ target: Bundle.target, … })` return
+ * strongly-typed `BundleHandle`s.
+ */
+export interface HandleKind extends Module.HandleKind {
+    readonly Handle: BundleHandle<this["_Name"] & string, Dep.Provide<"App", this["_Name"] & string> | Dep.Provide<"Namespace", this["_Ns"] & string> | (this["_Extra"] & unknown), Exclude<this["_R"] & unknown, Dep.Need<"Namespace", this["_Ns"] & string> | (this["_Extra"] & unknown)>>;
+}
+/**
+ * Re-export of {@link Module.LiteralName} — preserved as
+ * `Bundle.LiteralName` so existing wrapper code keeps working.
+ * konfig's dep graph keys every `Provide<"App", Name>` slot by literal
+ * `Name`; a wrapper that lets `Name` widen to `string` collapses every
+ * bundle into the same slot.
+ */
+export type LiteralName<T extends string> = Module.LiteralName<T>;
+export interface BundleDefineOptions<Name extends string, Ns extends string, R, Extra> {
+    readonly name: LiteralName<Name>;
+    readonly namespace?: LiteralName<Ns>;
+    readonly build: Effect.Effect<ReadonlyArray<unknown>, AnyRenderError, R> | (() => ReadonlyArray<unknown>);
+    readonly provides?: Layer.Layer<Extra>;
+}
+type _NsProvides<Ns extends string> = [Ns] extends [never] ? never : Dep.Provide<"Namespace", Ns>;
+type _NsExcludes<Ns extends string> = [Ns] extends [never] ? never : Dep.Need<"Namespace", Ns>;
+/**
+ * Build a typed handle for a manifest bundle — a name + optional
+ * namespace + a set of manifests, plus dep-graph wiring. Same
+ * compile-time guarantees as argocd's `Application.define` minus
+ * `source: ArgoSource` / `syncPolicy` / sync-wave annotations:
+ *  - the literal `Name` flows into `Dep.Provide<"App", Name>`,
+ *  - the optional literal namespace flows into `Dep.Provide<"Namespace", Ns>`,
+ *  - the build callback's `R` channel becomes the handle's `In` after
+ *    subtracting what this bundle provides itself.
+ *
+ * Pair with `Bundle.fromModules` to compose multiple bundles
+ * and have the dep-graph residual checked at `Bundle.entrypoint`.
+ *
+ * For `Module.fixedNs` / `Module.dynamicNs` use, see `Bundle.target`
+ * — it adapts this `define` so namespace is required (Module wrappers
+ * always thread a namespace through), which lets the dep-graph drop
+ * the `Provide<"Namespace", never>` cell the optional shape needs.
+ */
+export declare const define: <const Name extends string, const Ns extends string = never, R = never, Extra = never>(opts: BundleDefineOptions<Name, Ns, R, Extra>) => BundleHandle<Name, Dep.Provide<"App", Name> | _NsProvides<Ns> | Extra, Exclude<R, _NsExcludes<Ns> | Extra>>;
+/**
+ * `Module.Target` adapter for `Bundle.define`. `Module.fixedNs` /
+ * `Module.dynamicNs` always pass a namespace through, so this adapter
+ * requires `namespace` (whereas `Bundle.define` itself accepts it as
+ * optional) — pinning `Ns` to a real literal lets the dep-graph emit
+ * a concrete `Provide<"Namespace", Ns>` cell on the resulting handle.
+ *
+ * ```ts
+ * const defineCache = Module.fixedNs({
+ *   target: Bundle.target,
+ *   namespace: "cache",
+ *   build: ({ name, namespace }) => [ ... ],
+ * });
+ * ```
+ */
+export declare const target: Module.Target<HandleKind, Record<never, never>, Record<never, never>>;
+export interface BundleSetResult {
+    readonly name: string;
+    readonly bundles: ReadonlyArray<Bundle>;
+}
+export interface BundleSetMakeOptions {
+    readonly name?: string;
+    readonly bundles: ReadonlyArray<Bundle>;
+}
+export declare const makeSet: (opts: BundleSetMakeOptions) => BundleSetResult;
+/**
+ * Phantom check that rejects a `Bundle.fromModules` program whose `R`
+ * channel still carries unmet dep-graph Needs. Bound to the
+ * "Bundle.fromModules" API label so the `_konfig_unsatisfied` hint
+ * guides the user to the right call site.
+ */
+export declare const entrypoint: <A, E, R>(program: Effect.Effect<A, E, R> & ([Exclude<R, CoreManifest.RenderServices>] extends [never] ? unknown : {
+    readonly _konfig_unsatisfied: Exclude<R, CoreManifest.RenderServices> extends infer T ? T extends Exclude<R, CoreManifest.RenderServices> ? T extends Dep.Need<infer K extends string, infer V extends string> ? `Missing provider for ${K} "${V}". Add a module that provides it to Bundle.fromModules({ modules }), or check that providers come before consumers in the list.` : "Unsatisfied dep — see the Effect Layer error above." : never : never;
+})) => Effect.Effect<A, E, R & CoreManifest.RenderServices>;
+type AnyHandle = BundleHandle<any, any, any>;
+export type ResidualIn<T extends ReadonlyArray<AnyHandle>> = Compose.ResidualIn<T>;
+export interface FromModulesOptions<Ms extends ReadonlyArray<AnyHandle>> {
+    readonly name?: string;
+    readonly modules: Ms;
+}
+/**
+ * One-list composition for a backend-agnostic bundle set. Yields each
+ * module's `Bundle` in tuple order, then wires the merged provider layer
+ * with `Compose.composeLayers`. The returned Effect's R channel is the
+ * residual unmet Needs after the fold (`Compose.ResidualIn<Ms>`),
+ * which `entrypoint` rejects unless empty.
+ *
+ * **Order matters.** List providers before their consumers. A consumer
+ * placed before its provider leaves an unmet `Need` in the residual,
+ * which surfaces at `entrypoint` as a `_konfig_unsatisfied` hint.
+ */
+export declare const fromModules: <const Ms extends ReadonlyArray<AnyHandle>>(opts: FromModulesOptions<Ms>) => Effect.Effect<BundleSetResult, AnyRenderError, ResidualIn<Ms> | CoreManifest.RenderServices>;
+export {};

package/dist/Compose.d.ts

@@ -0,0 +1,68 @@
+import { type Effect, Layer } from "effect";
+import type { Need } from "./deps";
+import type { RenderServices } from "./Manifest";
+import type { AnyRenderError } from "./RenderError";
+/**
+ * The minimal shape `composeLayers` and the residual fold need: anything
+ * with a `.layer` field of the standard `(Out, AnyRenderError, In)`
+ * triple. Each runtime (argocd `ApplicationHandle`, k8s `BundleHandle`,
+ * …) supplies its own wider handle interface — the carried value type
+ * is irrelevant to the fold itself.
+ */
+export interface ComposeHandle<Out = any, In = any> {
+    readonly layer: Layer.Layer<Out, AnyRenderError, In>;
+}
+type AnyHandle = ComposeHandle<any, any>;
+type OutOfHandle<H> = H extends ComposeHandle<infer Out, any> ? Out : never;
+type InOfHandle<H> = H extends ComposeHandle<any, infer In> ? In : never;
+/**
+ * Left-fold over the modules tuple, mirroring the runtime
+ * `reduce(Layer.provideMerge)` below. Each module's `In` is filtered
+ * against the union of every *prior* module's `Out`; whatever survives
+ * is residual. Tuple order matters: a consumer listed before its
+ * provider leaves its Need in the residual.
+ */
+type FoldResidualIn<T extends ReadonlyArray<AnyHandle>, AccIn, AccOut> = T extends readonly [infer H, ...infer Rest] ? H extends AnyHandle ? Rest extends ReadonlyArray<AnyHandle> ? FoldResidualIn<Rest, AccIn | Exclude<InOfHandle<H>, AccOut>, AccOut | OutOfHandle<H>> : never : never : AccIn;
+/**
+ * After folding `Layer.provideMerge` over `Ms` in tuple order, the
+ * leftover `RIn` channel — the Needs that no preceding module's Out
+ * satisfies. Pair with `makeResidualEntrypoint` to surface a non-empty
+ * residual as a compile error at the entrypoint call site.
+ */
+export type ResidualIn<T extends ReadonlyArray<AnyHandle>> = FoldResidualIn<T, never, never>;
+/**
+ * Runtime layer composition — `reduce(Layer.provideMerge)`. Each
+ * successive module receives every prior module's Out as available
+ * services. The runtime type collapses to a bottom Layer; the per-module
+ * Out/In is tracked statically by `ResidualIn`.
+ */
+export declare const composeLayers: (modules: ReadonlyArray<{
+    readonly layer: unknown;
+}>) => Layer.Layer<never, AnyRenderError, never>;
+/**
+ * Per-Need template-literal hint shown when a residual reaches the
+ * entrypoint. `Api` is the calling API's name ("AppOfApps.fromModules",
+ * "Bundle.fromModules", …) so the message points the user at the right
+ * call site.
+ */
+type UnsatisfiedHint<R, Api extends string> = R extends Need<infer K, infer V> ? `Missing provider for ${K} "${V}". Add a module that provides it to ${Api}({ modules }), or check that providers come before consumers in the list.` : "Unsatisfied dep — see the Effect Layer error above.";
+/**
+ * Intersects the program type with a phantom `_konfig_unsatisfied`
+ * object when the residual `R` carries anything beyond
+ * `Manifest.RenderServices`. The program has no such property at runtime,
+ * so the call fails to typecheck and the user sees the hint.
+ */
+type ResidualHintCheck<R, Api extends string> = [
+    Exclude<R, RenderServices>
+] extends [never] ? unknown : {
+    readonly _konfig_unsatisfied: UnsatisfiedHint<Exclude<R, RenderServices>, Api>;
+};
+/**
+ * Build an `entrypoint` function bound to a specific API name. The
+ * returned function accepts only programs whose `R` channel reduces to
+ * `Manifest.RenderServices`; otherwise the call fails at the program
+ * argument with a `_konfig_unsatisfied` hint that names the missing
+ * provider and the calling API.
+ */
+export declare const makeResidualEntrypoint: <const Api extends string>(_api: Api) => <A, E, R>(program: Effect.Effect<A, E, R> & ResidualHintCheck<R, Api>) => Effect.Effect<A, E, R & RenderServices>;
+export {};

package/dist/Helm.d.ts

@@ -0,0 +1,19 @@
+import { type Manifest, type RawYaml } from "./Manifest";
+export interface HelmReleaseOptions {
+    readonly repo: string;
+    readonly chart: string;
+    readonly releaseName?: string;
+    readonly version: string;
+    readonly digest: string;
+    readonly namespace?: string;
+    readonly values: Record<string, unknown>;
+    readonly extraOpts?: readonly string[];
+    /**
+     * Minimum acceptable `helm` CLI version (semver, e.g. `"3.16.0"`).
+     * When set, `release` runs a `helm version --short` preflight before
+     * pulling/templating and fails with `HelmVersionTooLow` if the
+     * installed helm is older (or absent). Omit to skip the check.
+     */
+    readonly minVersion?: string;
+}
+export declare const release: (opts: HelmReleaseOptions) => Manifest<RawYaml[]>;

package/dist/Manifest.d.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+import { FileSystem } from "effect/FileSystem";
+import type { Path } from "effect/Path";
+import type * as Scope from "effect/Scope";
+import type { ChildProcessSpawner } from "./_unstable";
+import type { RenderContext } from "./RenderContext";
+import { type AnyRenderError } from "./RenderError";
+export type RenderServices = FileSystem | Path | ChildProcessSpawner | Scope.Scope;
+export declare const ManifestTypeId: unique symbol;
+export type ManifestTypeId = typeof ManifestTypeId;
+interface Variance<out A> {
+    readonly _A: (_: never) => A;
+}
+export interface Manifest<out A> {
+    readonly [ManifestTypeId]: Variance<A>;
+    readonly render: (ctx: RenderContext) => Effect.Effect<A, AnyRenderError, RenderServices>;
+}
+export type MakeRun<A> = (ctx: RenderContext) => A | Effect.Effect<A, AnyRenderError, RenderServices>;
+export declare const make: <A>(run: MakeRun<A>) => Manifest<A>;
+export interface CombineInput<A1, A2> {
+    readonly a: Manifest<A1>;
+    readonly b: Manifest<A2>;
+}
+export declare const combine: <A1, A2>(input: CombineInput<A1, A2>) => Manifest<readonly [A1, A2]>;
+export declare const concat: <A>(...manifests: Manifest<A | A[]>[]) => Manifest<A[]>;
+export interface WheneverInput<A> {
+    readonly cond: boolean;
+    readonly thunk: () => Manifest<A>;
+}
+export declare const whenever: <A>(input: WheneverInput<A>) => Manifest<A | undefined>;
+export type EmbedYamlSource = {
+    readonly path: string;
+} | {
+    readonly literal: string;
+};
+export interface RawYaml {
+    readonly _tag: "RawYaml";
+    readonly content: string;
+    readonly origin?: string;
+}
+export declare const embedYaml: (source: EmbedYamlSource) => Manifest<RawYaml>;
+export {};

package/dist/Module.d.ts

@@ -0,0 +1,146 @@
+import { Effect, type Layer } from "effect";
+import type { AnyRenderError } from "./RenderError";
+/**
+ * Resolves to `T` if it is a string literal (or template-literal
+ * pattern), and to a structured error type when `T` widens to the bare
+ * `string`. Use as the field type on every name/namespace slot any
+ * module wrapper forwards.
+ *
+ * konfig's dep graph keys each provider by literal name; a wrapper that
+ * lets `Name` widen to `string` collapses every module into the same
+ * slot and silently masks unmet deps. This brand turns that into a
+ * compile error at the call site.
+ */
+export type LiteralName<T extends string> = string extends T ? {
+    readonly _konfig_error: "Module name/namespace must be a string literal. Make the wrapper generic (`<const Name extends string>`) and forward via `Module.LiteralName<Name>`.";
+} : T;
+/**
+ * Context passed to a module's `build` callback. Carries the
+ * per-instance identity (chosen `name` and the module's `namespace`)
+ * so the build can stamp them onto manifests without re-receiving
+ * them via `opts`.
+ */
+export interface BuildContext<Ns extends string = string> {
+    readonly name: string;
+    readonly namespace: Ns;
+}
+/**
+ * Allowed return shapes from a module `build` callback:
+ *  - an `Effect` (when the build reads from Layers, files, etc.)
+ *  - a plain `ReadonlyArray<unknown>` for pure synchronous builds.
+ *
+ * `Module.fixedNs` / `Module.dynamicNs` lift the array form into an
+ * `Effect` internally — wrapper authors don't need to wrap themselves.
+ */
+export type BuildResult<R = never> = Effect.Effect<ReadonlyArray<unknown>, AnyRenderError, R> | ReadonlyArray<unknown>;
+/**
+ * Higher-kinded handle constructor: each backend declares a sub-interface
+ * that maps the four type parameters (`_Name`, `_Ns`, `_R`, `_Extra`)
+ * onto its native handle (`ApplicationHandle` / `BundleHandle` / …).
+ *
+ * `ApplyHandle` substitutes concrete types into the kind's `this`
+ * slots — the standard "type lambda" encoding Effect uses for HKTs.
+ */
+export interface HandleKind {
+    readonly _Name: string;
+    readonly _Ns: string;
+    readonly _R: unknown;
+    readonly _Extra: unknown;
+    readonly Handle: unknown;
+}
+export type ApplyHandle<K extends HandleKind, Name extends string, Ns extends string, R, Extra> = (K & {
+    readonly _Name: Name;
+    readonly _Ns: Ns;
+    readonly _R: R;
+    readonly _Extra: Extra;
+})["Handle"];
+/**
+ * Universal define-args every backend accepts. Each backend layers
+ * additional fields on via the `ExtraConfig` (config-time-only) and
+ * `ExtraCallArgs` (per-instance) generics on `Target`.
+ */
+export interface DefineBaseArgs<Name extends string, Ns extends string, R, Extra> {
+    readonly name: LiteralName<Name>;
+    readonly namespace: LiteralName<Ns>;
+    readonly build: Effect.Effect<ReadonlyArray<unknown>, AnyRenderError, R> | (() => ReadonlyArray<unknown>);
+    readonly provides?: Layer.Layer<Extra>;
+}
+/**
+ * Adapter contract a backend implements to plug into `Module.fixedNs` /
+ * `Module.dynamicNs`. Both `Application` (argocd) and `Bundle` (k8s)
+ * satisfy it via their existing `define` exports — pass the namespace
+ * itself as the first argument.
+ *
+ *  - `Kind`            — HKT mapping `(Name, Ns, R, Extra)` to the
+ *                          backend's native handle type.
+ *  - `ExtraConfig`     — config-time-only fields the backend accepts
+ *                          (e.g. argocd's `syncPolicy`, `annotations`).
+ *  - `ExtraCallArgs`   — per-instance fields the wrapper requires
+ *                          at the call site (e.g. argocd's `source`).
+ */
+export interface Target<Kind extends HandleKind = HandleKind, ExtraConfig extends object = Record<string, never>, ExtraCallArgs extends object = Record<string, never>> {
+    readonly define: <const Name extends string, const Ns extends string, R = never, Extra = never>(args: DefineBaseArgs<Name, Ns, R, Extra> & ExtraConfig & ExtraCallArgs) => ApplyHandle<Kind, Name, Ns, R, Extra>;
+}
+/** Config accepted by `Module.fixedNs` (namespace baked into the wrapper). */
+export interface FixedNsConfig<Kind extends HandleKind, ExtraConfig extends object, ExtraCallArgs extends object, Ns extends string, Opts extends object, R, Extra> {
+    readonly target: Target<Kind, ExtraConfig, ExtraCallArgs>;
+    readonly namespace: Ns;
+    readonly provides?: Layer.Layer<Extra>;
+    readonly build: (ctx: BuildContext<Ns>, opts: Opts) => BuildResult<R>;
+}
+/**
+ * Build a typed wrapper for a module whose namespace is part of its
+ * identity (e.g. `cert-manager` always installs into `cert-manager`).
+ *
+ * `target` is the backend adapter — typically `Application.target`
+ * (argocd) or `Bundle.target` (k8s). The wrapper's call signature
+ * merges the backend's per-instance fields (`source` for argocd,
+ * none for bundle) with the user-defined `Opts`.
+ *
+ * ```ts
+ * const defineSops = Module.fixedNs({
+ *   target: Application.target,
+ *   namespace: "sops",
+ *   annotations: Sync.wave(-1),
+ *   build: ({ namespace }, _opts: Record<never, never>) => [
+ *     Namespace.make({ name: namespace }),
+ *     Helm.release({ ... }),
+ *   ],
+ * });
+ *
+ * const sops = defineSops({ name: "sops-operator", source: src("sops") });
+ * ```
+ */
+export declare const fixedNs: <Kind extends HandleKind, ExtraConfig extends object, ExtraCallArgs extends object, const Ns extends string, Opts extends object = Record<never, never>, R = never, Extra = never>(config: FixedNsConfig<Kind, ExtraConfig, ExtraCallArgs, Ns, Opts, R, Extra> & ExtraConfig) => <const Name extends string>(args: {
+    readonly name: LiteralName<Name>;
+} & ExtraCallArgs & Opts) => ApplyHandle<Kind, Name, Ns, R, Extra>;
+/** Config accepted by `Module.dynamicNs` (namespace chosen per instance). */
+export interface DynamicNsConfig<Kind extends HandleKind, ExtraConfig extends object, ExtraCallArgs extends object, Opts extends object, R, Extra> {
+    readonly target: Target<Kind, ExtraConfig, ExtraCallArgs>;
+    readonly provides?: Layer.Layer<Extra>;
+    readonly build: (ctx: BuildContext, opts: Opts) => BuildResult<R>;
+}
+/**
+ * Build a typed wrapper for a module whose namespace is chosen per
+ * instance (e.g. an `api` module deployed into different namespaces
+ * per env).
+ *
+ * ```ts
+ * const defineApi = Module.dynamicNs({
+ *   target: Application.target,
+ *   annotations: Sync.wave(1),
+ *   build: ({ name, namespace }, opts: ApiOpts) => [ ... ],
+ * });
+ *
+ * const api = defineApi({
+ *   name: "api",
+ *   namespace: "prod",
+ *   source: src("api"),
+ *   replicas: 2,
+ * });
+ * ```
+ */
+export declare const dynamicNs: <Kind extends HandleKind, ExtraConfig extends object, ExtraCallArgs extends object, Opts extends object = Record<never, never>, R = never, Extra = never>(config: DynamicNsConfig<Kind, ExtraConfig, ExtraCallArgs, Opts, R, Extra> & ExtraConfig) => <const Name extends string, const Ns extends string>(args: {
+    readonly name: LiteralName<Name>;
+    readonly namespace: LiteralName<Ns>;
+} & ExtraCallArgs & Opts) => ApplyHandle<Kind, Name, Ns, R, Extra>;

package/dist/RenderContext.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Context object threaded through every `Manifest.render(...)` call.
+ *
+ * `env` is the single load-bearing field: it keys both the file-output
+ * directory under `outDir.manifests` and the choice of bundle entry in
+ * `KonfigConfig.envs`. The optional fields below carry per-cluster
+ * context for renders where one logical env spans multiple clusters.
+ *
+ * **Precedence rules:**
+ *  - The output directory is keyed on `env` alone when `cluster` is
+ *    `undefined`; when set, builds write to `<outDir>/<env>/<cluster>/`.
+ *    Tests that bypass the CLI write into the simpler `<outDir>/<env>/`
+ *    path by construction.
+ *  - `cluster` is informational inside `Manifest.make((ctx) => ...)` —
+ *    no constructor mutates a manifest based on it implicitly; the
+ *    caller branches.
+ *  - `k8sVersion` is a hint for renderers that emit
+ *    apiVersion-conditional resources (e.g. `policy/v1beta1` vs
+ *    `policy/v1`).
+ *  - `flags` is the escape hatch for one-off "render with X" toggles
+ *    that don't deserve their own field. Use sparingly.
+ */
+export interface RenderContext {
+    readonly env: string;
+    readonly cluster?: string;
+    readonly k8sVersion?: string;
+    readonly flags?: ReadonlyMap<string, unknown>;
+}
+export interface RenderContextFullInput {
+    readonly env: string;
+    readonly cluster?: string;
+    readonly k8sVersion?: string;
+    readonly flags?: ReadonlyMap<string, unknown>;
+}
+export declare const RenderContext: {
+    make: (env: string) => RenderContext;
+    makeFull: (input: RenderContextFullInput) => RenderContext;
+};