@namzu/sandbox 14.0.0 → 15.0.0

package/dist/backends/kubernetes/egress-policy.d.ts

@@ -76,7 +76,9 @@
  * the kernel, not by the workload's cooperation.
  */
 import type { EgressPolicy } from '../../index.js';
+import { type SelectorMatch, type UnreadPolicySource } from './ingress-policy.js';
 import { type KubernetesClient } from './k8s-client.js';
+import type { KubernetesOwnerReference } from './objects.js';
 /**
  * `'core'` (the default) is plain Kubernetes `NetworkPolicy` — every cluster
  * has it, and it cannot express a hostname. `'cilium'` opts into emitting a
@@ -84,6 +86,151 @@ import { type KubernetesClient } from './k8s-client.js';
  * the target cluster actually runs Cilium as its CNI.
  */
 export type KubernetesEgressEngine = 'core' | 'cilium';
+/**
+ * The two egress kinds that exist only here, because only a `NetworkPolicy`
+ * can express them and the shared {@link EgressPolicy} union describes what
+ * every tier can carry.
+ *
+ *  - `'no-network'` is the one the shared union has no word for: NOTHING
+ *    leaves the pod, the cluster's own resolver included. `'deny-all'` is not
+ *    that and never was — it emits {@link CLUSTER_DNS_EGRESS_RULE}, and a
+ *    cluster resolver forwards outside names upstream, so a `'deny-all'`
+ *    sandbox keeps a channel out through DNS. `'deny-all'` is deliberately
+ *    NOT tightened into this: its emitted manifest is byte-identical to
+ *    every release before this one, because verification of the named object
+ *    is an exact match and changing the translation would fail every
+ *    `create()` on every deployment that already applied a policy until an
+ *    operator re-applied it. A workload under `'no-network'` resolves
+ *    nothing at all — that is the point, and the agent needs no resolver
+ *    because the host dials in.
+ *  - `'public-internet'` is `'allow-all'` minus everything that is not the
+ *    public internet: the private ranges, the carrier-grade NAT range, the
+ *    link-local range that carries cloud instance metadata, loopback, the
+ *    platform endpoint some clouds answer on, and IPv6's equivalents. It
+ *    exists because `'allow-all'` reaches the node, the API server, the
+ *    service network and every other sandbox pod, and nothing between the
+ *    two said "out, but not sideways".
+ *
+ * `exceptCidrs` adds to the excluded list; it never removes from it. A CIDR
+ * that is not one this check can parse is refused at construction rather
+ * than emitted into a manifest the API server would reject on apply.
+ */
+export type KubernetesOnlyEgressPolicy = {
+    readonly kind: 'no-network';
+} | {
+    readonly kind: 'public-internet';
+    readonly exceptCidrs?: readonly string[];
+};
+/**
+ * What {@link KubernetesEgressConfig.policy} accepts: the shared
+ * {@link EgressPolicy} union plus the two {@link KubernetesOnlyEgressPolicy}
+ * kinds. The shared union itself is untouched — a kind no other tier can
+ * enforce does not belong in the type every tier reads.
+ */
+export type KubernetesEgressPolicy = EgressPolicy | KubernetesOnlyEgressPolicy;
+/**
+ * How thoroughly the applied boundary is checked before a sandbox is handed
+ * back.
+ *
+ *  - `'union'` (the default) reads the NAMED object exactly as before AND
+ *    enumerates every `NetworkPolicy` — and, under `engine: 'cilium'`, every
+ *    `CiliumNetworkPolicy` — in the namespace, refusing when any policy that
+ *    selects the pod allows egress the configured translation does not. That
+ *    is not belt-and-braces: the API server UNIONS every policy selecting a
+ *    pod, so a second policy widens egress however exactly the named one
+ *    matches, and a `SandboxTemplate`'s own `networkPolicy` block becomes
+ *    exactly such a policy.
+ *  - `'named-object-only'` is the documented opt-out, and restores the
+ *    previous behaviour exactly: one GET of the named object, memoized for
+ *    the backend's lifetime, and no enumeration. For a deployment whose
+ *    other policies a namespaced Role cannot read, or which accepts the
+ *    union it has. It mirrors `ingress: 'unverified'` — a claim a deployment
+ *    makes on purpose rather than a default it inherits.
+ */
+export type KubernetesEgressVerification = 'union' | 'named-object-only';
+/**
+ * How {@link KubernetesCiliumEgressNarrowing.dnsNames} narrows the kube-dns
+ * L7 rule. `true` uses every default below; an object customises them.
+ *
+ * The exact-name list a narrowed policy emits is, for each allowed host,
+ * the bare name plus the host under `<namespace>.svc.<clusterDomain>`,
+ * `svc.<clusterDomain>` and `<clusterDomain>` — because Cilium's `matchName`
+ * is an EXACT name and does not match across a `.` the way `matchPattern`
+ * does, and a search-list query for `github.com.svc.cluster.local` is a
+ * DIFFERENT name than `github.com`. `searchSuffixes` adds more: kubelet
+ * appends the node's own search domains, which this backend cannot see, so a
+ * deployment whose nodes carry extra search domains lists them here or a
+ * search-list query for one of them is refused by the DNS proxy — and, per
+ * Cilium's own docs, some images (musl/Alpine) stop trying the search list
+ * entirely the first time that happens, breaking the bare name lookup too.
+ */
+export interface KubernetesCiliumDnsNarrowing {
+    /** Defaults to the egress target's own namespace (where the sandbox pods run). */
+    readonly namespace?: string;
+    /** Defaults to `'cluster.local'`. */
+    readonly clusterDomain?: string;
+    /** Appended after the three built-in suffixes, not replacing them. */
+    readonly searchSuffixes?: readonly string[];
+}
+/**
+ * Opt-in narrowing of a `static`/`resolver` hostname allowlist under
+ * `engine: 'cilium'` — see the module doc and `#490`. Every field here is
+ * OFF unless set, and setting none of them leaves the translation
+ * byte-for-byte what it always emitted: that is the compatibility guarantee
+ * a deployment with an already-applied policy relies on.
+ *
+ * Setting any field switches the translation from one shared `toFQDNs` rule
+ * naming every host to one `toFQDNs` rule PER HOST, so ports and server
+ * names can differ host by host. Refused synchronously (alongside
+ * {@link assertEgressPolicyIsEnforceable}'s existing refusals) unless
+ * `engine` is `'cilium'` and `policy.kind` is `'static'` or `'resolver'`.
+ */
+export interface KubernetesCiliumEgressNarrowing {
+    /**
+     * TCP ports allowed to every host that has no entry in `hostPorts`, e.g.
+     * `[443]`. Leaving both this and `hostPorts` unset — with `dnsNames` and
+     * `tlsServerNames` also unset — means no port narrowing: a host's
+     * `toFQDNs` rule carries no `toPorts` at all, exactly as the
+     * unnarrowed translation emits today (every port reachable).
+     */
+    readonly ports?: readonly number[];
+    /**
+     * Per-host TCP port overrides, keyed by the host exactly as it appears in
+     * `allowedHosts` or a `resolver`'s result. A host with no entry here
+     * falls back to `ports`.
+     */
+    readonly hostPorts?: Readonly<Record<string, readonly number[]>>;
+    /**
+     * Narrow the kube-dns L7 rule from `rules.dns: [{ matchPattern: '*' }]`
+     * to an exact `matchName` per allowed host, and per host-plus-suffix. See
+     * {@link KubernetesCiliumDnsNarrowing}.
+     */
+    readonly dnsNames?: boolean | KubernetesCiliumDnsNarrowing;
+    /**
+     * Add `serverNames: [<host>]` to each host's TLS ports (SNI enforcement,
+     * which needs Cilium's L7 proxy — see the module doc). A host with no
+     * port configured in `ports`/`hostPorts` is limited to `tlsPorts` rather
+     * than left with no port restriction at all, because a `serverNames`
+     * rule needs a port to attach to.
+     *
+     * REFUSED for a `.domain` allowlist entry, with
+     * {@link KubernetesNetworkPolicyHostError} and nothing written: a server
+     * name is one exact SNI value a handshake presents, while the entry means
+     * a name PLUS its subdomains, and no single value means both — see
+     * {@link assertHostsFitNarrowing}. The refusal is the entry's, not this
+     * option's, so it fires wherever `tlsServerNames` can be set:
+     * `config.egress.ciliumNarrowing` on the config-level allowlist and
+     * `config.egress.perSandbox.narrowing` on the per-sandbox one.
+     */
+    readonly tlsServerNames?: boolean;
+    /**
+     * Which of a host's configured ports are TLS ports, for
+     * `tlsServerNames`: those get `serverNames` on their own `toPorts`
+     * entry, the rest (if any) get a separate entry with none. Defaults to
+     * `[443]`. Meaningless unless `tlsServerNames` is set.
+     */
+    readonly tlsPorts?: readonly number[];
+}
 /**
  * The config-level egress hook on {@link KubernetesBackendConfig}.
  *
@@ -96,7 +243,7 @@ export type KubernetesEgressEngine = 'core' | 'cilium';
  * the one egress policy the whole backend enforces.
  */
 export interface KubernetesEgressConfig {
-    readonly policy: EgressPolicy;
+    readonly policy: KubernetesEgressPolicy;
     /**
      * Name of the `NetworkPolicy` (or `CiliumNetworkPolicy`, under the
      * `'cilium'` engine) an operator applied. Defaults to
@@ -106,7 +253,442 @@ export interface KubernetesEgressConfig {
     readonly networkPolicyName?: string;
     /** Default `'core'`. See the type doc. */
     readonly engine?: KubernetesEgressEngine;
+    /** Default `'union'`. See {@link KubernetesEgressVerification}. */
+    readonly verify?: KubernetesEgressVerification;
+    /**
+     * Opt-in port/DNS-name/TLS-server-name narrowing for a `static`/
+     * `resolver` allowlist under `engine: 'cilium'`. Unset (the default)
+     * emits exactly what every release before this one did. See
+     * {@link KubernetesCiliumEgressNarrowing}.
+     */
+    readonly ciliumNarrowing?: KubernetesCiliumEgressNarrowing;
+    /**
+     * Which egress PROFILE the sandboxes this backend produces run under —
+     * a DNS-1123 label value such as `none` or `internet`.
+     *
+     * Unset (the default) is the single-profile world this backend has
+     * always had: one policy per backend, selected by the template label
+     * alone, and every emitted body, selector and policy name byte-identical
+     * to the release before profiles existed.
+     *
+     * SET, it becomes a pod LABEL — {@link profileLabelKey} is its key —
+     * which travels three places at once: onto the `SandboxClaim`'s
+     * `additionalPodMetadata.labels`, onto a directly created Sandbox's pod
+     * template, and into the translated policy's own selector. That is what
+     * lets ONE warm pool serve several network modes: a claim carrying a
+     * profile label adopts a warm replica and the controller patches the
+     * label onto the running pod, with no cold start and no second pool —
+     * measured on agent-sandbox v1.0.2 (two profiles out of one two-replica
+     * pool, every adopt under 70 ms, each bound pod a replica that already
+     * existed). A label is the only claim-time metadata that is warm-safe:
+     * `env` and `volumeClaimTemplates` force a cold start, which is why
+     * neither appears on the claim body.
+     *
+     * OPERATOR PREREQUISITE, and it is not optional: the controller refuses
+     * a claim whose label key sits outside its `allowed-label-domains`
+     * allowlist (the `agent-sandbox-config` ConfigMap in the controller's
+     * namespace; default `sandbox.users.io`), so the DEFAULT key below is
+     * refused by a stock controller until an operator adds
+     * `sandbox.namzu.ai` to that key — or sets {@link profileLabelKey} to
+     * something already allowed. That refusal is fast and carries the
+     * controller's own reason and message: it is the acquire's ordinary
+     * `claim-rejected` failure, with a
+     * {@link KubernetesPodLabelsRejectedError} as its cause naming the labels
+     * that were sent and the key that moves them.
+     */
+    readonly profile?: string;
+    /**
+     * Label key {@link profile} is written under. Defaults to
+     * {@link DEFAULT_EGRESS_PROFILE_LABEL_KEY}.
+     *
+     * Worth setting to `sandbox.users.io/egress-profile` on a cluster whose
+     * controller still carries the stock `allowed-label-domains` — that
+     * domain is upstream's own default and needs no ConfigMap edit at all.
+     */
+    readonly profileLabelKey?: string;
+    /**
+     * Opt in to PER-SANDBOX egress: one `CiliumNetworkPolicy` per live
+     * sandbox, written by this host when a caller calls
+     * `Sandbox.setNetworkPolicy`, owned by the object the acquire created so
+     * the cluster garbage-collects it.
+     *
+     * Unset (the default) is every release before this one: `setNetworkPolicy`
+     * is ABSENT from the handle, exactly as the SDK's omit-or-throw contract
+     * asks of a backend that cannot honour an optional method, and this
+     * backend issues no policy write of any kind. Presence depends only on
+     * this field — never on a runtime probe — so a host can decide what it
+     * has from its own config rather than from a call that might fail.
+     *
+     * TWO OPERATOR PREREQUISITES, and neither is a nicety: the admission
+     * policy named below (with its binding) has to exist, and the host's
+     * ServiceAccount needs the write verbs the default Role deliberately does
+     * not grant. See {@link KubernetesPerSandboxEgressConfig}.
+     */
+    readonly perSandbox?: KubernetesPerSandboxEgressConfig;
+}
+/**
+ * Per-sandbox egress: what it takes to let a host narrow ONE live sandbox's
+ * egress without touching any other sandbox's.
+ *
+ * The mechanism is a `CiliumNetworkPolicy` per sandbox, named
+ * `namzu-sbx-<uid of the object this backend created>`, selecting that one
+ * sandbox's pod through a per-sandbox label, and carrying an
+ * `ownerReferences` entry naming that same object — so `destroy()` deletes
+ * the claim (or the Sandbox) and the cluster's garbage collector removes the
+ * policy, with this backend issuing no deletion of its own.
+ *
+ * It is NOT the docker backend's mechanism. That one is an egress PROXY with
+ * no relationship to any policy object; the only two things worth taking from
+ * it are its refusal discipline and `SandboxNetworkPolicy.allowedHosts`'s
+ * `.domain`-prefix wildcard semantics.
+ *
+ * A per-sandbox list ADDS to {@link KubernetesEgressConfig.policy}, because
+ * the cluster unions every policy that selects a pod. That makes it the whole
+ * boundary under a `'no-network'` or `'deny-all'` baseline — the deployment
+ * this is for — and a no-op addition under `'allow-all'`, where
+ * `setNetworkPolicy([])` also does not deny everything the way
+ * `SandboxNetworkPolicy` describes. Neither combination is refused; pair this
+ * with a denying `policy.kind` when `setNetworkPolicy` is meant to BE the
+ * boundary rather than to widen one.
+ */
+export interface KubernetesPerSandboxEgressConfig {
+    /**
+     * Must be `'cilium'`. `'core'` is accepted by the TYPE and refused
+     * SYNCHRONOUSLY during host wiring, the same way
+     * {@link assertEgressPolicyIsEnforceable} refuses a hostname allowlist
+     * with no FQDN-capable engine: core `NetworkPolicy` has no hostname
+     * concept at all, so there is nothing for an `allowedHosts` list to
+     * become. It is spelled out in the type rather than fixed to the one
+     * legal value so the refusal can name what was configured.
+     */
+    readonly engine: KubernetesEgressEngine;
+    /**
+     * Name of the operator-applied `ValidatingAdmissionPolicy` that bounds
+     * what this host may write. Checked — with its binding — BEFORE the first
+     * write, and the write is refused with nothing sent if either object is
+     * missing.
+     *
+     * The fence is the whole reason this capability can be granted at all:
+     * the RBAC it needs is `create`/`patch`/`delete` on the namespace's
+     * `ciliumnetworkpolicies`, which without a fence would let a compromised
+     * host widen or delete the operator's own baseline policy. The shipped
+     * example is `k8s/manifests/validatingadmissionpolicy-cilium.yaml`.
+     */
+    readonly admissionPolicyName: string;
+    /**
+     * Name of the `ValidatingAdmissionPolicyBinding` that ATTACHES the policy
+     * above. Defaults to `${admissionPolicyName}-binding`, which is what the
+     * shipped manifest names it.
+     *
+     * Checked separately because a `ValidatingAdmissionPolicy` with no
+     * binding validates nothing at all — it is inert, and an inert fence
+     * reads exactly like an enforced one from the object alone.
+     */
+    readonly admissionPolicyBindingName?: string;
+    /**
+     * Label key the per-sandbox selector is written under. Defaults to
+     * {@link DEFAULT_PER_SANDBOX_EGRESS_LABEL_KEY}.
+     *
+     * Its VALUE is the name of the object this backend created for the
+     * sandbox, so it is unique per acquire and known before the create POST —
+     * which is what lets it travel as claim-time pod metadata through
+     * {@link composeAdditionalPodLabels}, the ONE composer, rather than as a
+     * patch to a running pod this backend has no verb for.
+     *
+     * Same operator prerequisite as {@link KubernetesEgressConfig.profile}:
+     * the key's domain has to be in the controller's `allowed-label-domains`
+     * allowlist, or the claim is refused with the controller's own reason.
+     */
+    readonly labelKey?: string;
+    /**
+     * Port, DNS-name and TLS-server-name narrowing applied to the policies
+     * `setNetworkPolicy` writes — the same shape as
+     * {@link KubernetesEgressConfig.ciliumNarrowing}, and deliberately its own
+     * field rather than a reuse of it: that one narrows the ONE config-level
+     * policy, which is only a hostname allowlist at all when
+     * `policy.kind` is `'static'` or `'resolver'`, while these narrow the
+     * per-sandbox policies of a deployment whose baseline is usually
+     * `'deny-all'` or `'no-network'`.
+     *
+     * Unset (the default) emits one `toFQDNs` rule per host with no
+     * `toPorts` at all — every port on an allowed host reachable, which is
+     * what `SandboxNetworkPolicy` itself says (it names hosts, not ports).
+     *
+     * `hostPorts` is keyed by the `allowedHosts` entry AS WRITTEN, leading
+     * dot included: a `.example.com` entry needs the key `.example.com`, even
+     * though the rule it produces says `example.com` plus `*.example.com`.
+     *
+     * `tlsServerNames` and a `.domain` entry are REFUSED together, with
+     * {@link KubernetesNetworkPolicyHostError} and nothing written. A TLS
+     * server name is one exact SNI value; the expanded entry is a name and a
+     * pattern, and no single SNI value means both — `example.com` would deny
+     * every subdomain the policy claims to allow. List the exact hosts, or
+     * leave `tlsServerNames` off for a domain list.
+     */
+    readonly narrowing?: KubernetesCiliumEgressNarrowing;
+}
+/**
+ * Default {@link KubernetesEgressConfig.profileLabelKey} — this backend's
+ * own label domain, matching `SANDBOX_TEMPLATE_LABEL_KEY`'s prefix so
+ * every label a namzu host puts on a sandbox pod reads as one family.
+ *
+ * It is deliberately NOT upstream's `sandbox.users.io`: a key in someone
+ * else's domain is a key someone else may define differently. The cost is
+ * the ConfigMap edit named on {@link KubernetesEgressConfig.profile}, and
+ * the controller's refusal spells that edit out itself.
+ */
+export declare const DEFAULT_EGRESS_PROFILE_LABEL_KEY = "sandbox.namzu.ai/egress-profile";
+/** One resolved profile label: the key it is written under and its value. */
+export interface EgressProfileLabel {
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * Named refusal for an egress PROFILE this backend can read but not use.
+ * Sibling of {@link KubernetesEgressPolicyConfigError} rather than a reuse of
+ * it: that one names a field under `config.egress.policy` and this one names
+ * a field beside it, and an operator reading either should not have to work
+ * out which level of the config the path belongs to.
+ *
+ * Thrown SYNCHRONOUSLY from `buildKubernetesBackend` and
+ * `createKubernetesWorkspace`, so a misconfigured profile surfaces during
+ * host wiring rather than on the first `create()`.
+ */
+export declare class KubernetesEgressProfileConfigError extends Error {
+    readonly field: 'profile' | 'profileLabelKey';
+    readonly value: string;
+    readonly name = "KubernetesEgressProfileConfigError";
+    constructor(field: 'profile' | 'profileLabelKey', value: string, reason: string);
+}
+/**
+ * The profile label this config asks for, or nothing at all — the ONE place
+ * the key/value pair is derived, so the claim body, the Sandbox pod
+ * template, the policy selector and the policy name cannot disagree about
+ * what the profile is.
+ *
+ * Validates as it resolves: the value has to be a DNS-1123 label and the key
+ * a legal label key, both refused with {@link KubernetesEgressProfileConfigError}.
+ */
+export declare function egressProfileLabel(egress: KubernetesEgressConfig | undefined): EgressProfileLabel | undefined;
+/**
+ * Validate the profile without needing its value — the wiring-time hook, so
+ * `buildKubernetesBackend` and `createKubernetesWorkspace` refuse a bad
+ * profile the same moment they refuse an unenforceable policy.
+ */
+export declare function assertEgressProfileIsUsable(egress: KubernetesEgressConfig | undefined): void;
+/**
+ * Default {@link KubernetesPerSandboxEgressConfig.labelKey} — the key the
+ * per-sandbox policy's `endpointSelector` matches on.
+ *
+ * In this backend's own label domain, for the same reason the profile key is
+ * (see {@link DEFAULT_EGRESS_PROFILE_LABEL_KEY}), and carrying the same
+ * operator prerequisite: the controller's `allowed-label-domains` allowlist
+ * has to admit `sandbox.namzu.ai`, or every claim carrying it is refused with
+ * {@link KubernetesPodLabelsRejectedError} as the cause. A deployment that
+ * would rather not edit that ConfigMap sets this to a key under
+ * `sandbox.users.io`, which is upstream's own default domain.
+ */
+export declare const DEFAULT_PER_SANDBOX_EGRESS_LABEL_KEY = "sandbox.namzu.ai/per-sandbox-egress";
+/**
+ * Named refusal for a `config.egress.perSandbox` this backend can read but
+ * not honour. Thrown SYNCHRONOUSLY from `buildKubernetesBackend`, beside the
+ * policy and profile refusals, so a host that has mis-declared the capability
+ * learns it during wiring rather than from the first `setNetworkPolicy` call
+ * — which may be an hour into a run, after work that cannot be redone.
+ *
+ * Its own class rather than a reuse of {@link KubernetesEgressProfileConfigError}
+ * for the reason that one is not a reuse of
+ * {@link KubernetesEgressPolicyConfigError}: an operator reading a refusal
+ * should not have to work out which level of `config.egress` the named field
+ * belongs to.
+ */
+export declare class KubernetesPerSandboxEgressConfigError extends Error {
+    readonly field: 'engine' | 'admissionPolicyName' | 'admissionPolicyBindingName' | 'labelKey';
+    readonly value: string;
+    readonly name = "KubernetesPerSandboxEgressConfigError";
+    constructor(field: 'engine' | 'admissionPolicyName' | 'admissionPolicyBindingName' | 'labelKey', value: string, reason: string);
+}
+/**
+ * The per-sandbox selector label KEY this config asks for, or nothing at all
+ * when `perSandbox` is unset — the one place the default is applied, so the
+ * pod label, the policy selector and the admission policy's own expectation
+ * cannot disagree.
+ *
+ * Validates as it resolves, exactly as {@link egressProfileLabel} does.
+ */
+export declare function perSandboxEgressLabelKey(egress: KubernetesEgressConfig | undefined): string | undefined;
+/**
+ * Validate `config.egress.perSandbox` in full — the wiring-time hook, so a
+ * mis-declared capability is refused the same moment an unenforceable policy
+ * or an unusable profile is.
+ *
+ * `engine: 'core'` is the refusal the SDK's contract cares about: core
+ * `NetworkPolicy` cannot express a hostname at all, so a host that configured
+ * it would be told "policy applied" about an object that could never carry
+ * the allowlist. It is refused here rather than from the method, which means
+ * a `'core'` deployment never gets a handle carrying the method in the first
+ * place.
+ */
+export declare function assertPerSandboxEgressIsUsable(egress: KubernetesEgressConfig | undefined): void;
+/**
+ * Named refusal for `config.egress.perSandbox` reaching an entry point that
+ * can never carry the capability it configures: `createKubernetesWorkspace`.
+ *
+ * `perSandbox` exists to make `Sandbox.setNetworkPolicy` PRESENT on a TASK
+ * handle, where the acquire creates the object each policy is named after and
+ * owned by and stamps the per-sandbox pod label its selector matches, and
+ * where the RBAC and the admission fence are the ones that bound the write.
+ * A workspace's create path does none of that — it composes no per-sandbox
+ * pod label and tracks no owner uid for one — so on that path the option
+ * would be accepted and mean nothing at all: exactly the "declared and
+ * silently unused" configuration this module refuses everywhere else. The
+ * alternative, omitting the method and saying nothing, is how a host comes to
+ * believe it narrowed a workspace's egress.
+ *
+ * NOT a variant of {@link KubernetesPerSandboxEgressConfigError}, which is
+ * about a `perSandbox` value this backend cannot honour ANYWHERE (an engine
+ * with no hostname concept, an unnamed fence). This one is about a `perSandbox`
+ * value it honours perfectly well on the other entry point, so a caller
+ * catching the sibling for a typo'd value does not also catch a correct
+ * configuration aimed at the wrong path.
+ */
+export declare class KubernetesWorkspacePerSandboxEgressConfigError extends Error {
+    readonly name = "KubernetesWorkspacePerSandboxEgressConfigError";
+    constructor();
+}
+/**
+ * Refuse `config.egress.perSandbox` on the entry point that cannot carry it —
+ * `createKubernetesWorkspace`. See
+ * {@link KubernetesWorkspacePerSandboxEgressConfigError}.
+ *
+ * Deliberately not {@link assertPerSandboxEgressIsUsable}, which validates the
+ * same config for the path that DOES honour it: a workspace has nothing to
+ * validate the option for, whatever its `engine` or `admissionPolicyName` say,
+ * because it serves no `setNetworkPolicy` at all. Calling that validator here
+ * instead would be worse than saying nothing — it would report a
+ * `perSandbox` this deployment can use as if it were in use.
+ */
+export declare function assertWorkspaceCarriesNoPerSandboxEgress(egress: KubernetesEgressConfig | undefined): void;
+/**
+ * The ONE composer for a sandbox pod's `additionalPodMetadata.labels`.
+ *
+ * Every label this backend asks the controller to put on a POD is built
+ * here: the egress profile today, and whatever a later capability
+ * contributes through `extra` (a per-sandbox policy selector, for one). Two
+ * independent constructions would be two answers to "what labels is this pod
+ * selected by", and the policy selector is built from the same resolution —
+ * so a second builder would be a pod bound under a policy nobody checked.
+ *
+ * Deliberately NOT where `KubernetesBackendInternalConfig.claimLabels`
+ * goes. Those are a host's own bookkeeping on the CLAIM object's
+ * `metadata.labels`; putting them on the pod would change what selectors
+ * match a running sandbox, which is a different question on a different
+ * object.
+ *
+ * Returns an empty object when nothing applies, which every caller reads as
+ * "emit nothing at all" — that is what keeps an unprofiled body byte-identical.
+ *
+ * A key in `extra` that is ALSO the profile's is refused rather than merged
+ * either way round. Whichever won, the loser would be a label the translated
+ * policy's selector still expects: the profile's selector is built from this
+ * same resolution, so a pod carrying the other value is selected by no
+ * per-profile policy while `create()` reported the boundary verified. It is
+ * the same failure {@link egressProfileLabel} refuses the template key for,
+ * reached from the other direction.
+ */
+export declare function composeAdditionalPodLabels(egress: KubernetesEgressConfig | undefined, extra?: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+/**
+ * Why a claim the controller refused with `InvalidMetadata` was refused, in
+ * this backend's own terms — in practice a pod label whose domain is not in
+ * the controller's `allowed-label-domains` allowlist, which today means the
+ * egress profile's.
+ *
+ * NOT what an acquire throws. A refused claim comes out of `create()` as
+ * `KubernetesAcquireError { reason: 'claim-rejected' }` whether or not a
+ * profile is configured — one condition, one taxonomy, one `catch` — and this
+ * rides as that error's `cause`. Two classes for one controller condition
+ * would make a host's error handling correct or incorrect depending on
+ * whether `config.egress.profile` happened to be set.
+ *
+ * What it adds to the acquire error is what the controller cannot know: the
+ * map this backend actually sent, and the `config.egress.profileLabelKey`
+ * that moves the offending key to an allowed domain. It carries the whole map
+ * rather than the profile alone, and `profile` is optional, because the map is
+ * {@link composeAdditionalPodLabels}'s — the profile is the only thing in it
+ * today, and a later capability adding a second key would otherwise get an
+ * explanation that named a label it did not send.
+ *
+ * It carries the controller's OWN `reason` and `message` rather than a
+ * translation of them: the message agent-sandbox v1.0.2 writes names the
+ * offending key, the domain, the ConfigMap key to edit and its default, and
+ * no paraphrase of it would be as useful. Measured verbatim against a kind
+ * cluster running that controller:
+ *
+ * > invalid additionalPodMetadata: failed to validate label
+ * > "sandbox.namzu.ai/egress-profile": label domain "sandbox.namzu.ai" is
+ * > not in the allowlist (configure the allowed-label-domains key of the
+ * > agent-sandbox-config ConfigMap in the controller namespace; default:
+ * > sandbox.users.io)
+ *
+ * The refusal is raised as soon as that condition is read rather than after
+ * the readiness budget, because `InvalidMetadata` is one of
+ * `TERMINAL_CLAIM_REASONS` — nothing about it becomes true by waiting — and
+ * the claim is deleted on the way out, so a misconfigured profile costs one
+ * round trip rather than a minute of polling.
+ */
+export declare class KubernetesPodLabelsRejectedError extends Error {
+    /** Every label this backend put on the claim's `additionalPodMetadata`. */
+    readonly requestedPodLabels: Readonly<Record<string, string>>;
+    readonly claimName: string;
+    readonly namespace: string;
+    /** The controller's own condition `reason`, e.g. `InvalidMetadata`. */
+    readonly controllerReason: string;
+    /** The controller's own condition `message`, verbatim. */
+    readonly controllerMessage: string;
+    /** The egress profile among those labels, when one is configured. */
+    readonly profile?: EgressProfileLabel | undefined;
+    readonly name = "KubernetesPodLabelsRejectedError";
+    constructor(
+    /** Every label this backend put on the claim's `additionalPodMetadata`. */
+    requestedPodLabels: Readonly<Record<string, string>>, claimName: string, namespace: string, 
+    /** The controller's own condition `reason`, e.g. `InvalidMetadata`. */
+    controllerReason: string, 
+    /** The controller's own condition `message`, verbatim. */
+    controllerMessage: string, 
+    /** The egress profile among those labels, when one is configured. */
+    profile?: EgressProfileLabel | undefined);
+}
+/**
+ * Named refusal for a bound pod that never carried a label this backend asked
+ * the controller to put on it — the egress profile's, today the only one
+ * {@link composeAdditionalPodLabels} produces, which is why the class is named
+ * for the LABEL rather than for the profile.
+ *
+ * This is the one failure this capability must not have quietly. An
+ * unlabelled pod handed back is a sandbox running under the DEFAULT policy
+ * while the host believes it is on a narrower profile — the translated
+ * policy's selector includes the profile label, so a pod without it is
+ * selected by neither this profile's policy nor, necessarily, anything else.
+ * Refusing is correct and waiting is correct; proceeding is not, so the
+ * acquire releases what it claimed and raises this instead.
+ *
+ * `missingLabel` is the pair that never arrived rather than "the profile", so
+ * the refusal stays true for whatever a later capability contributes to that
+ * same map: the wait in `readAddressedPod` already covers every entry of it,
+ * and this refusal covers exactly the same set.
+ */
+export declare class KubernetesPodLabelNotObservedError extends Error {
+    /** The label this backend requested and never saw on the bound pod. */
+    readonly missingLabel: EgressProfileLabel;
+    readonly subject: string;
+    readonly observedLabels: Readonly<Record<string, string>>;
+    readonly name = "KubernetesPodLabelNotObservedError";
+    constructor(
+    /** The label this backend requested and never saw on the bound pod. */
+    missingLabel: EgressProfileLabel, subject: string, observedLabels: Readonly<Record<string, string>>);
 }
+/** `true` unless the deployment asked for the single-object check by name. */
+export declare function egressUnionVerificationEnabled(egress: KubernetesEgressConfig | undefined): boolean;
 /** Where a translated policy is targeted, and what its `podSelector` names. */
 export interface EgressPolicyTarget {
     readonly namespace: string;
@@ -118,7 +700,26 @@ export interface EgressPolicyTarget {
      * carries it.
      */
     readonly sandboxTemplateName: string;
+    /**
+     * The egress PROFILE label this policy also selects, when
+     * {@link KubernetesEgressConfig.profile} is set. Absent, the selector is
+     * the template label alone and every translation is what it always was.
+     *
+     * It is part of the SELECTOR rather than a second policy because that is
+     * what makes one warm pool serve several modes: pods out of one template
+     * carry one template label and differ only by this one, so
+     * `${template}-none-egress` selects exactly the `none` pods and
+     * `${template}-internet-egress` exactly the `internet` ones.
+     */
+    readonly profile?: EgressProfileLabel;
 }
+/**
+ * What a translated policy's `podSelector`/`endpointSelector` matches: the
+ * template label, plus the profile label when one is configured. One
+ * function so the two manifest builders below and every reader of a
+ * translation agree on the selector down to the key order.
+ */
+export declare function egressPolicySelectorLabels(target: EgressPolicyTarget): Readonly<Record<string, string>>;
 /**
  * A translated policy: which kind of Kubernetes object it is, where it
  * lives, and the manifest an operator applies verbatim. `kind` is the
@@ -131,12 +732,31 @@ export interface EgressPolicyTarget {
  */
 export interface KubernetesTranslatedEgressPolicy {
     readonly kind: 'NetworkPolicy' | 'CiliumNetworkPolicy';
+    /**
+     * The CONFIGURED kind this came from, carried so a refusal can name what
+     * the deployment asked for (`no-network`, `public-internet`, …) rather
+     * than only the resource it produced.
+     */
+    readonly policyKind: KubernetesEgressPolicy['kind'];
     readonly namespace: string;
     readonly name: string;
     readonly manifest: Readonly<Record<string, unknown>>;
 }
-/** `${sandboxTemplateName}-egress`, the name {@link KubernetesEgressConfig.networkPolicyName} defaults to. */
-export declare function defaultEgressPolicyName(sandboxTemplateName: string): string;
+/**
+ * `${sandboxTemplateName}-egress`, the name
+ * {@link KubernetesEgressConfig.networkPolicyName} defaults to — or
+ * `${sandboxTemplateName}-${profile}-egress` when a profile is configured,
+ * because one template under two profiles needs two policy objects and a
+ * single default name would have the second silently verify against the
+ * first's manifest.
+ *
+ * The profile is bounded at 63 characters on its own, but the CONCATENATION
+ * is what has to be a legal object name, and only this function knows both
+ * halves. Refused here, during host wiring, rather than as an API-server
+ * rejection on the first policy GET of the first `create()`: `networkPolicyName`
+ * is the way out and it is a config field, so this is a config error.
+ */
+export declare function defaultEgressPolicyName(sandboxTemplateName: string, profile?: string): string;
 /**
  * Named refusal for a hostname allowlist with no FQDN-capable engine
  * declared. Thrown SYNCHRONOUSLY from `buildKubernetesBackend` — see
@@ -149,15 +769,236 @@ export declare class KubernetesUnenforceableEgressPolicyError extends Error {
     readonly name = "KubernetesUnenforceableEgressPolicyError";
     constructor(policyKind: 'static' | 'resolver');
 }
+/**
+ * Named refusal for a config value this backend can read but not use — today
+ * only a `public-internet` `exceptCidrs` entry that is not a CIDR. Thrown
+ * SYNCHRONOUSLY from `buildKubernetesBackend`, beside
+ * {@link KubernetesUnenforceableEgressPolicyError}, so a typo surfaces
+ * during host wiring rather than as a policy the API server rejects when an
+ * operator applies it.
+ */
+export declare class KubernetesEgressPolicyConfigError extends Error {
+    readonly field: string;
+    readonly name = "KubernetesEgressPolicyConfigError";
+    constructor(field: string, reason: string);
+}
+/**
+ * Named refusal for `config.egress.ciliumNarrowing` set on a policy/engine
+ * combination it does not apply to. Thrown SYNCHRONOUSLY from
+ * {@link assertEgressPolicyIsEnforceable}, beside
+ * {@link KubernetesUnenforceableEgressPolicyError}, so a narrowing option
+ * that would silently do nothing is refused at host-wiring time rather than
+ * accepted and ignored.
+ */
+export declare class KubernetesEgressNarrowingUnsupportedError extends Error {
+    readonly policyKind: KubernetesEgressPolicy['kind'];
+    readonly engine: KubernetesEgressEngine;
+    readonly name = "KubernetesEgressNarrowingUnsupportedError";
+    constructor(policyKind: KubernetesEgressPolicy['kind'], engine: KubernetesEgressEngine);
+}
+/**
+ * Raised for an `allowedHosts` entry this backend will not translate.
+ *
+ * Named for the ENTRY rather than for a config field, because entries arrive
+ * from two directions: a host's `Sandbox.setNetworkPolicy` call, and the
+ * `allowedHosts` of a `static`/`resolver` `config.egress.policy`.
+ * `SandboxNetworkPolicy` names HOSTS: `api.example.com` for one host,
+ * `.example.com` for a domain and its subdomains. A glob, a URL, a port
+ * suffix or an address is refused rather than emitted, because a
+ * `CiliumNetworkPolicy` carrying one is an object the API server rejects on
+ * apply — or, worse, accepts as a name that resolves to nothing, which reads
+ * from the outside exactly like a policy that is working.
+ *
+ * `stateHostnameGrammar` is the one part of the message a caller can turn
+ * off, because NOT every refusal can make that claim. It is false for the
+ * config-level refusal of a leading-dot entry under `tlsServerNames`, whose
+ * body has just said that the entry reaches the object as a literal
+ * `matchName` admitting nothing with the option on or off: closing that
+ * message with "'.example.com' for that domain and its subdomains" would
+ * re-assert, as implemented, the very grammar whose absence is why the entry
+ * is refused. Every other refusal keeps the sentence, the expanding branch of
+ * the same one included.
+ */
+export declare class KubernetesNetworkPolicyHostError extends Error {
+    readonly host: string;
+    readonly name = "KubernetesNetworkPolicyHostError";
+    constructor(host: string, reason: string, options?: {
+        readonly stateHostnameGrammar?: boolean;
+    });
+}
+/**
+ * Every entry in `narrowing.ports`, `narrowing.hostPorts` and
+ * `narrowing.tlsPorts` is a port the API server will actually accept, none of
+ * those three is an explicitly empty array, and every DNS suffix
+ * `narrowing.dnsNames` names is a non-empty string — checked here,
+ * synchronously, for the same reason {@link assertEgressPolicyIsEnforceable}
+ * checks `exceptCidrs`: a value the API server rejects on apply would leave a
+ * policy that never verifies.
+ */
+/**
+ * Refuse a narrowing the API server would reject on apply, naming the field
+ * that has to change.
+ *
+ * `fieldPath` is how the refusal spells the option's location, because the
+ * same shape is configurable in two places now: `ciliumNarrowing` narrows the
+ * CONFIG-level translated policy, and `perSandbox.narrowing` narrows the
+ * per-sandbox policies a host writes through `setNetworkPolicy`. One
+ * validator, because they are one shape and two would disagree the first time
+ * either grew a field.
+ */
+export declare function assertCiliumNarrowingIsUsable(narrowing: KubernetesCiliumEgressNarrowing, fieldPath?: string): void;
 /**
  * Synchronous, no-I/O precondition: can `policy.kind` be enforced under
- * `engine` at all. Deliberately decided from the KIND alone — a `resolver`
- * policy's `resolve()` is never invoked here, both because calling it just to
- * prove a refusal would be wasted work (and possibly a side effect the host
- * did not expect yet) and because this has to stay callable synchronously
- * from `buildKubernetesBackend`, which contacts nothing.
+ * `engine` at all, and — if `narrowing` is set — does it apply to this
+ * policy/engine combination. Deliberately decided from the KIND alone — a
+ * `resolver` policy's `resolve()` is never invoked here, both because calling
+ * it just to prove a refusal would be wasted work (and possibly a side effect
+ * the host did not expect yet) and because this has to stay callable
+ * synchronously from `buildKubernetesBackend`, which contacts nothing.
+ */
+export declare function assertEgressPolicyIsEnforceable(policy: KubernetesEgressPolicy, engine: KubernetesEgressEngine, narrowing?: KubernetesCiliumEgressNarrowing): void;
+/**
+ * Which translation a host refusal is being spelled for, as ONE value.
+ *
+ * The refusal has two halves that have to agree — the sentence, which follows
+ * from whether the translation expands a leading-dot entry, and the field
+ * path, which follows from which field the caller set — and both are facts
+ * about the SAME thing: the translation the caller is on. Passed as two
+ * arguments they are decided from two inputs, and an expanding caller was
+ * told to repair `config.egress.ciliumNarrowing` with the remedy that belongs
+ * to `config.egress.perSandbox.narrowing` — a message sending a reader to a
+ * field the entry never came from. Neither half means anything without the
+ * other, so they travel together.
+ */
+export interface HostsFitNarrowingContext {
+    /**
+     * The field the refusal sends the reader to, spelled as the caller set it
+     * — the full path, as every other refusal in this module spells one.
+     */
+    readonly fieldPath: string;
+    /**
+     * Whether this translation turns a leading-dot entry into a `matchName`
+     * plus a `matchPattern` — {@link ciliumFqdnEntries}. `true` for the
+     * per-sandbox translation, `false` for the config-level one, whose emitted
+     * bytes are pinned. Decides the refusal's sentence and its closing grammar
+     * as well as the bytes, and all three are the same fact about one entry.
+     */
+    readonly expandsDottedEntries: boolean;
+}
+/**
+ * The refusal context of the PER-SANDBOX translation — the one that expands,
+ * and so the one `expandDomains: true` builds.
+ *
+ * Shared deliberately: the per-sandbox writer refuses a host by this context
+ * before it reads the fence, and {@link buildCiliumEgressManifest} refuses the
+ * same host by the same context on the way through the translation, so the two
+ * cannot name different fields for one entry however the earlier check is
+ * reached or skipped.
+ */
+export declare const PER_SANDBOX_NARROWING_REFUSAL: HostsFitNarrowingContext;
+/**
+ * The refusal context of the config-level translation — `config.egress.policy`
+ * and its `config.egress.ciliumNarrowing`, which expands nothing.
+ */
+export declare const CONFIG_LEVEL_NARROWING_REFUSAL: HostsFitNarrowingContext;
+/**
+ * Refuse the one allowlist entry a narrowing option cannot express.
+ *
+ * `tlsServerNames` puts the entry on the rule as a TLS server name — one
+ * exact SNI value a handshake presents — and a `.domain` entry is a set of
+ * names no single SNI value means. Either way the emitted object would be
+ * admitted by the shipped fence, read back deep-equal to what was sent, and
+ * deny what the caller asked to allow — the failure every other refusal in
+ * this module exists to prevent. Refused rather than translated another way,
+ * because both other ways are guesses: dropping the subdomains silently
+ * narrows what the caller asked for, and a wildcard SNI value is not
+ * something the Cilium versions these manifests are written against are
+ * known here to match — an SNI that matches nothing denies just as
+ * completely, and more quietly.
+ *
+ * The entry is refused for a DIFFERENT reason on each of the two paths, and
+ * the message says which one the caller is on, because the same sentence
+ * cannot be true of both:
+ *
+ *  - `expandDomains` — the per-sandbox writer's translation, which turns
+ *    `.domain` into `matchName: domain` PLUS `matchPattern: '*.domain'`. No
+ *    single SNI value means that pair: `domain` alone denies every subdomain
+ *    the pattern admits, and the entry as written is not a name any handshake
+ *    presents at all.
+ *  - unexpanded — the config-level translation, which expands nothing. There
+ *    the entry reaches the object as the literal `matchName: '.domain'`,
+ *    which no DNS answer carries, so it already admits nothing; `serverNames`
+ *    on top of it is a second, independent denial. Telling this caller to
+ *    "leave tlsServerNames off for a domain list" would name a repair that is
+ *    not one — the config-level `.domain` entry denies the domain and every
+ *    subdomain with or without the option (a pre-existing defect of this
+ *    translation, deferred to its own change) — so it is not offered here.
+ *
+ * `context` is WHICH translation the refusal is being spelled for, as one
+ * value — see {@link HostsFitNarrowingContext}. A reader has to be sent to
+ * the field they actually set, and the sentence they are sent by has to be
+ * true of the translation they are on, and both follow from that one fact:
+ * passed separately, an expanding caller gets the per-sandbox remedy attached
+ * to the config-level field name, a message whose only repair is a field the
+ * entry never came from. Called from BOTH — the translation itself, so every
+ * caller is covered, and the per-sandbox writer, which refuses earlier still,
+ * before it reads the fence.
  */
-export declare function assertEgressPolicyIsEnforceable(policy: EgressPolicy, engine: KubernetesEgressEngine): void;
+export declare function assertHostsFitNarrowing(allowedHosts: readonly string[], narrowing: KubernetesCiliumEgressNarrowing | undefined, context: HostsFitNarrowingContext): void;
+/**
+ * One allowlist entry, expanded to the `toFQDNs` entries it means.
+ *
+ * `SandboxNetworkPolicy.allowedHosts`'s own grammar, which the SDK states and
+ * the docker backend implements: `api.example.com` is that host, and
+ * `.example.com` is the domain AND its subdomains. Cilium's `matchName` is an
+ * exact name and does not match across a `.`, so the domain form needs the
+ * name plus a `matchPattern` — `*.example.com` alone would admit
+ * `a.example.com` and not `example.com` itself.
+ *
+ * Used by the PER-SANDBOX policy only. The config-level translation
+ * (`config.egress.policy`) deliberately does not expand anything: what it
+ * emits for a given config is pinned byte-for-byte, because verification of
+ * the named object is an exact match and a changed translation fails every
+ * `create()` on every deployment that already applied a policy.
+ */
+export declare function ciliumFqdnEntries(entry: string): readonly Readonly<Record<string, string>>[];
+/**
+ * Everything a `CiliumNetworkPolicy` for a hostname allowlist is built from.
+ *
+ * ONE builder, two callers: the config-level translation below, whose
+ * selector is the template (and profile) label and whose emitted bytes are
+ * pinned, and the per-sandbox policy in `per-sandbox-policy.ts`, whose
+ * selector is one per-sandbox label and which additionally carries an
+ * `ownerReferences` entry so the cluster garbage-collects it. A second
+ * builder would be a second answer to what a namzu egress policy looks like,
+ * and the read-back comparator would then be verifying one of them against
+ * the other's shape.
+ */
+export interface CiliumEgressManifestOptions {
+    readonly namespace: string;
+    readonly name: string;
+    /** What `spec.endpointSelector.matchLabels` carries, verbatim. */
+    readonly selectorLabels: Readonly<Record<string, string>>;
+    readonly allowedHosts: readonly string[];
+    /** The CONFIGURED kind this came from, for a refusal's wording. */
+    readonly policyKind: KubernetesEgressPolicy['kind'];
+    readonly narrowing?: KubernetesCiliumEgressNarrowing;
+    /** `metadata.ownerReferences`. Absent ⇒ the metadata is what it always was. */
+    readonly ownerReferences?: readonly KubernetesOwnerReference[];
+    /**
+     * Expand a leading-dot entry into `matchName` plus `matchPattern` — see
+     * {@link ciliumFqdnEntries}. Off by default, because the config-level
+     * translation's emitted bytes are pinned.
+     *
+     * This option IS the translation, not a formatting flag on it: it selects
+     * the emitted bytes, the sentence a refusal carries and the field that
+     * refusal names, all from one value — see
+     * {@link HostsFitNarrowingContext}. There is no way to ask for one without
+     * the others, and none should be added.
+     */
+    readonly expandDomains?: boolean;
+}
+export declare function buildCiliumEgressManifest(options: CiliumEgressManifestOptions): KubernetesTranslatedEgressPolicy;
 /**
  * The pure translation: an {@link EgressPolicy} plus the declared
  * {@link KubernetesEgressEngine} in, the concrete manifest this backend can
@@ -175,7 +1016,7 @@ export declare function assertEgressPolicyIsEnforceable(policy: EgressPolicy, en
  * hosts against, and re-resolving on every `create()` would only produce a
  * value nothing downstream re-applies to the cluster.
  */
-export declare function translateEgressPolicy(policy: EgressPolicy, engine: KubernetesEgressEngine, target: EgressPolicyTarget): Promise<KubernetesTranslatedEgressPolicy>;
+export declare function translateEgressPolicy(policy: KubernetesEgressPolicy, engine: KubernetesEgressEngine, target: EgressPolicyTarget, ciliumNarrowing?: KubernetesCiliumEgressNarrowing): Promise<KubernetesTranslatedEgressPolicy>;
 /**
  * Raised by {@link verifyEgressPolicyApplied} when the named object does not
  * exist at all. This backend never CREATES the policy itself — like the
@@ -211,9 +1052,245 @@ export declare class KubernetesEgressPolicyMismatchError extends Error {
  *  - `NetworkPolicy` additionally declares `policyTypes` including
  *    `'Egress'` — a `NetworkPolicy` with an `egress` array but no `'Egress'`
  *    in `policyTypes` enforces nothing on egress at all;
- *  - the `egress` rule array matches the translation exactly.
+ *  - the `egress` rule array matches the translation exactly;
+ *  - and, ONLY when the translation carries `metadata.ownerReferences` (the
+ *    per-sandbox policies of `per-sandbox-policy.ts`, never the operator's
+ *    own object), that the live object still carries each of them — an owner
+ *    reference dropped between the write and the read is a policy the
+ *    cluster will never collect with the sandbox it belongs to, which is the
+ *    leak the reference exists to prevent, and it is invisible in `spec`.
  *
  * Never mutates and never creates — a 404/410 is refused, not repaired.
  */
 export declare function verifyEgressPolicyApplied(client: KubernetesClient, translated: KubernetesTranslatedEgressPolicy, signal?: AbortSignal): Promise<void>;
+/** A CIDR as a masked base address and a prefix length. */
+export interface ParsedCidr {
+    readonly version: 4 | 6;
+    readonly base: bigint;
+    readonly bits: number;
+}
+/**
+ * A CIDR, or `undefined` when it is not one this check can read. Host bits
+ * are masked off rather than rejected: `10.0.0.1/8` and `10.0.0.0/8` name the
+ * same block, and an operator who wrote the first meant the second.
+ */
+export declare function parseCidr(text: unknown): ParsedCidr | undefined;
+/** One port, or a range of them, on one protocol. `start` absent is every port. */
+interface PortRange {
+    /** `undefined` is EVERY protocol — how Cilium spells `ANY`. Core defaults to TCP. */
+    readonly protocol?: string;
+    readonly start?: number;
+    readonly end?: number;
+}
+/** A destination, as either side of the comparison names it. */
+type PolicyPeer = {
+    readonly kind: 'everything';
+} | {
+    readonly kind: 'cidr';
+    readonly cidr: ParsedCidr;
+    readonly except: readonly ParsedCidr[];
+    readonly text: string;
+} | {
+    readonly kind: 'selector';
+    readonly namespaceSelector?: unknown;
+    readonly podSelector?: unknown;
+    readonly text: string;
+};
+interface AllowedDestination {
+    readonly peer: PolicyPeer;
+    readonly ports: 'all' | readonly PortRange[];
+}
+/** One `toFQDNs` entry the translation allows, with the ports it allows it on. */
+interface AllowedFqdn {
+    readonly host: string;
+    readonly ports: 'all' | readonly PortRange[];
+}
+/**
+ * Everything the configured translation lets out, in the one shape the union
+ * check compares against.
+ *
+ * Built from the manifest {@link translateEgressPolicy} just produced for
+ * every core kind, so there is no second statement anywhere of what
+ * `deny-all` or `public-internet` permit — the emitted object IS the
+ * statement, and a test asserts each translation is within its own
+ * allowance. The Cilium kinds are the one exception and say so: a
+ * `CiliumNetworkPolicy`'s DNS-visibility rule is read into the core-shaped
+ * destination it is equivalent to (UDP/TCP 53 to the resolver's pods), so
+ * that a core `NetworkPolicy` allowing exactly cluster DNS is not reported as
+ * widening a hostname allowlist that already allows it.
+ */
+export interface EgressAllowance {
+    readonly destinations: readonly AllowedDestination[];
+    /**
+     * `toFQDNs` names a `static`/`resolver` translation allows, each with the
+     * ports it allows that name on (`'all'` for the unnarrowed shape, which
+     * puts no `toPorts` on its `toFQDNs` rule at all). Empty for every core
+     * kind. A name can appear more than once — one entry per `toFQDNs` rule
+     * naming it — and it is allowed on a port if ANY entry covers that port,
+     * the same "any matching destination" rule {@link destinationIsAllowed}
+     * applies to CIDR and selector peers.
+     */
+    readonly fqdns: readonly AllowedFqdn[];
+    /**
+     * The exact DNS names a `static`/`resolver` translation's kube-dns rule
+     * restricts LOOKUPS to when `ciliumNarrowing.dnsNames` is set — the
+     * `matchName` list {@link narrowedDnsVisibilityRule} builds. `'all'` for
+     * every translation that does not narrow DNS: every core kind (which
+     * cannot express an L7 DNS restriction at all) and an unnarrowed
+     * `static`/`resolver` (`rules.dns: [{ matchPattern: '*' }]`).
+     *
+     * `destinations` alone cannot carry this: reachability to the resolver's
+     * peer and port is the same whether or not DNS is narrowed, so a peer/port
+     * check reports a plain kube-dns rule as `within` a narrowed translation
+     * exactly as it would an unnarrowed one. {@link reachesResolverAtDnsPort}
+     * is the check that actually reads this field, in both
+     * {@link coreEgressRuleVerdict} and {@link ciliumEgressRuleVerdict}.
+     */
+    readonly dnsNarrowedTo: 'all' | readonly string[];
+    readonly permitsEverything: boolean;
+    readonly permitsNothing: boolean;
+    /** The configured kind, for the refusal message. */
+    readonly policyKind: KubernetesEgressPolicy['kind'];
+}
+/**
+ * The allowance a translated policy expresses. See {@link EgressAllowance}.
+ */
+export declare function egressAllowance(translated: KubernetesTranslatedEgressPolicy): EgressAllowance;
+/** One egress rule, judged against the translation. */
+export interface EgressRuleVerdict {
+    readonly beyond: boolean | 'unknown';
+    readonly detail?: string;
+}
+/** The pod the union check is about. */
+export interface EgressVerificationTarget {
+    readonly namespace: string;
+    /**
+     * The pod's REAL labels — for a directly created Sandbox the labels the
+     * create body stamps (known before the POST, so a refusal leaves no
+     * Sandbox and no PVC behind), for a claimed one the bound pod's own
+     * `metadata.labels`. The same value the ingress check is given, for the
+     * same reason: a name proves an object exists, a label is what a selector
+     * actually matches.
+     */
+    readonly podLabels: Readonly<Record<string, string>>;
+    readonly engine: KubernetesEgressEngine;
+    /** How the refusal names the thing being created, e.g. `Sandbox namzu-ws-demo`. */
+    readonly subject: string;
+}
+/** What one examined policy turned out to be. One line of the refusal. */
+export type EgressPolicyVerdict = 
+/** Selects the pod and lets out nothing the translation does not. */
+'within'
+/** Selects the pod and allows egress the translation does not. */
+ | 'widens-egress'
+/** Its selector does not match the pod's labels. */
+ | 'does-not-select'
+/** Selects the pod but does not enforce egress, so its egress block is inert. */
+ | 'not-egress-scoped'
+/** Contains something this check cannot decide. */
+ | 'not-evaluable';
+/** One policy, as the refusal reports it. */
+export interface ExaminedEgressPolicy {
+    readonly kind: 'NetworkPolicy' | 'CiliumNetworkPolicy';
+    readonly name: string;
+    readonly verdict: EgressPolicyVerdict;
+    /** Why, for every verdict that is not a plain match or non-match. */
+    readonly detail?: string;
+}
+/**
+ * Which of the three refusals this is — three different operator actions, so
+ * they are carried apart rather than folded into one message:
+ *
+ *  - `policy-widens-egress` — narrow or delete the policy that lets more out
+ *    than `config.egress` says.
+ *  - `no-enforcing-policy` — nothing puts this pod in egress default-deny, so
+ *    the translation is not the boundary; apply a policy that selects these
+ *    labels.
+ *  - `not-evaluable` — this check cannot decide; grant the missing verb, fix
+ *    the unreadable policy, or declare `egress.verify: 'named-object-only'`.
+ */
+export type EgressPolicyRefusal = 'policy-widens-egress' | 'no-enforcing-policy' | 'not-evaluable';
+/**
+ * One policy, reduced to the three questions the union rule asks: does it
+ * select this pod, does it put it in egress default-deny, and does anything
+ * it allows fall outside the configured translation.
+ */
+export interface EgressPolicyDocument {
+    readonly kind: 'NetworkPolicy' | 'CiliumNetworkPolicy';
+    readonly name: string;
+    readonly selects: SelectorMatch;
+    /**
+     * Does this policy put the pod into egress DEFAULT-DENY — the only thing
+     * that makes the translation a boundary at all. A core policy whose
+     * `policyTypes` leaves Egress out does not (and the API server ignores its
+     * `egress` block outright), and neither does a Cilium rule carrying
+     * `enableDefaultDeny.egress: false`.
+     */
+    readonly enforcesEgress: boolean;
+    readonly rules: readonly EgressRuleVerdict[];
+    /** Set when the OBJECT could not be read. It decides alone. */
+    readonly unreadable?: string;
+}
+/** Every core `NetworkPolicy` in the list, reduced to {@link EgressPolicyDocument}. */
+export declare function readCoreEgressPolicies(items: readonly unknown[], target: EgressVerificationTarget, allowance: EgressAllowance): EgressPolicyDocument[];
+/** Every `CiliumNetworkPolicy` in the list, reduced the same way. */
+export declare function readCiliumEgressPolicies(items: readonly unknown[], target: EgressVerificationTarget, allowance: EgressAllowance): EgressPolicyDocument[];
+export interface EgressUnionDecision {
+    readonly examined: readonly ExaminedEgressPolicy[];
+    /** Absent when every selecting policy stays inside the translation. */
+    readonly refusal?: {
+        readonly kind: EgressPolicyRefusal;
+        readonly summary: string;
+    };
+}
+/**
+ * The union rule, applied. Pure — no I/O, no client, no clock — so every
+ * shape that has to be refused can be asserted one per test.
+ *
+ * Kubernetes UNIONS every policy selecting a pod: traffic leaves if ANY
+ * selecting policy allows it. So one policy allowing more than the
+ * translation is the finding however many narrower ones sit beside it, and a
+ * pod no policy default-denies has no egress boundary at all whatever the
+ * named object says.
+ */
+export declare function decideEgressUnion(documents: readonly EgressPolicyDocument[], allowance: EgressAllowance): EgressUnionDecision;
+/**
+ * The named refusal. Distinct from {@link KubernetesEgressPolicyMismatchError}
+ * — which is about the ONE named object drifting from the translation — and
+ * from `KubernetesIngressPolicyError`, which is about the agent port being
+ * reachable. An operator debugging a release that ships all three tells them
+ * apart by class and by the first clause of the message.
+ *
+ * It carries the pod's labels and EVERY policy examined, with a verdict each,
+ * because that list is the operator's whole debugging session: "why does my
+ * policy not count?" is answered by the line saying it did not select these
+ * labels.
+ */
+export declare class KubernetesEgressPolicyUnionError extends Error {
+    readonly refusal: EgressPolicyRefusal;
+    readonly subject: string;
+    readonly podLabels: Readonly<Record<string, string>>;
+    readonly policyKind: KubernetesEgressPolicy['kind'];
+    readonly examined: readonly ExaminedEgressPolicy[];
+    /** Empty on every decision made from policies that WERE read. */
+    readonly unread: readonly UnreadPolicySource[];
+    readonly name = "KubernetesEgressPolicyUnionError";
+    constructor(refusal: EgressPolicyRefusal, subject: string, podLabels: Readonly<Record<string, string>>, policyKind: KubernetesEgressPolicy['kind'], examined: readonly ExaminedEgressPolicy[], summary: string, 
+    /** Empty on every decision made from policies that WERE read. */
+    unread?: readonly UnreadPolicySource[]);
+}
+/**
+ * Verify-not-trust, widened from one object to the union: list the
+ * namespace's policies, evaluate every one that selects this pod against the
+ * configured translation, and refuse unless nothing lets out more than
+ * `config.egress` says.
+ *
+ * Runs beside the ingress check on every create path — before the POST for a
+ * directly created Sandbox, where the labels are known and a refusal leaves
+ * nothing behind, and after the bind for a claimed one, where the pool's own
+ * template decides the labels and a refusal releases the claim through the
+ * acquire path's cleanup.
+ */
+export declare function verifyEgressPolicyUnion(client: KubernetesClient, translated: KubernetesTranslatedEgressPolicy, target: EgressVerificationTarget, signal?: AbortSignal): Promise<void>;
+export {};
 //# sourceMappingURL=egress-policy.d.ts.map