@intentius/chant-lexicon-k8s 0.45.0 → 0.49.0

package/src/lint/post-synth/wk8505.ts

@@ -0,0 +1,63 @@
+/**
+ * WK8505: committed-encrypted secret with no Flux decryption wiring
+ *
+ * Flux is the thing that actually decrypts a committed-encrypted secret's
+ * sidecar, via `spec.decryption` on the reconciling `Kustomization`
+ * (`FluxAppFor`'s `decryption` option). Nothing forces the two calls to be
+ * wired together: `declareSecret({ provenance: "committed-encrypted" })` and
+ * `FluxAppFor(...)` are independent, so it is easy to add the ciphertext
+ * without adding the wiring — the build succeeds, WK8504 passes because the
+ * file resolves cleanly, and Flux still applies the sidecar as raw
+ * `ENC[...]` bytes because nothing told it to decrypt first.
+ *
+ * Warning, not error. The reference project shape (`examples/flux-apps`)
+ * runs the workload build and the Flux build as separate `chant build`
+ * invocations, so "no Kustomization in THIS build sets spec.decryption" can
+ * mean "wired up in the other build" as easily as "forgotten" — the design
+ * doc's §4 explains why no path-to-build-target join exists to tell those
+ * apart. Promote to error if that join ever becomes available.
+ *
+ * Fires only on claims that actually resolved (`problems.length === 0`, via
+ * `resolveEncryptedSecretClaims`), not on every raw declaration. An
+ * unresolved declaration is already WK8504's job at error severity; firing
+ * this warning on top of it would report a Flux wiring gap for a Secret the
+ * build has not confirmed exists.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { allManifests, manifestsOfKind } from "./argo-helpers";
+import type { K8sManifest } from "./k8s-helpers";
+import { resolveEncryptedSecretClaims } from "./sops-helpers";
+
+/** Flux Kustomizations only — the kustomize.config.k8s.io kind shares the name. */
+function fluxKustomizations(manifests: K8sManifest[]): K8sManifest[] {
+  return manifestsOfKind(manifests, "Kustomization").filter((m) => {
+    const apiVersion = m.apiVersion;
+    return typeof apiVersion !== "string" || apiVersion.startsWith("kustomize.toolkit.fluxcd.io/");
+  });
+}
+
+export const wk8505: PostSynthCheck = {
+  id: "WK8505",
+  description:
+    "committed-encrypted secret with no Flux decryption wiring — add decryption: 'sops' to the FluxAppFor reconciling the path that carries it",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const kustomizations = fluxKustomizations(allManifests(ctx));
+    if (kustomizations.length === 0) return [];
+    if (kustomizations.some((k) => k.spec?.decryption !== undefined)) return [];
+
+    const resolved = resolveEncryptedSecretClaims(ctx).filter((claim) => claim.problems.length === 0);
+
+    return resolved.map((claim) => ({
+      checkId: "WK8505",
+      severity: "warning",
+      message:
+        `declareSecret("${claim.declaration.name}") is committed-encrypted, but no Flux Kustomization ` +
+        `in this build sets spec.decryption — Flux will apply "${claim.filename}" without decrypting it. ` +
+        `Add decryption: "sops" to the FluxAppFor reconciling the path that carries it, or ignore if that ` +
+        `Kustomization is declared in a different build.`,
+      entity: claim.declaration.name,
+      lexicon: "k8s",
+    }));
+  },
+};

package/src/op/activities/ensure-secret.ts

@@ -0,0 +1,71 @@
+/**
+ * `ensureSecret` — the activity behind core's `ensureSecret(...)` op step
+ * builder (#1829), provided by the store's lexicon as that builder promises
+ * (#1830). Registered by name through the activity registry when a project's
+ * `chant.config.ts` lists the `k8s` lexicon, exactly like `kubectlApply`.
+ *
+ * All it does is connect (the same environment→cluster binding every k8s
+ * path uses), build the namespace-scoped store adapter, and run core's one
+ * materialization engine over it. The contract — present means done, never
+ * mint over an existing value, mismatches fail naming key names only, no
+ * output carries material — lives in core (`secret-materialization.ts`) and
+ * in the adapter (../../secret-store.ts), not here.
+ */
+
+import {
+  ensureSecretMaterialization,
+  type EnsureSecretOutcome,
+} from "@intentius/chant/secret-materialization";
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import { defaultK8sConnector, type K8sConnector } from "../../api/connect";
+import { k8sSecretStore } from "../../secret-store";
+
+export interface EnsureSecretActivityArgs {
+  /** The Secret's `metadata.name`. */
+  name: string;
+  /** The declared key-set. Creation mints one value per key; verification compares names only. */
+  keys: string[];
+  /** Declared metadata (labels/annotations) an existing Secret must carry. Mismatches name the KEY. */
+  metadata?: Record<string, string>;
+  /** Target namespace. Omitted uses the connected context's default namespace. */
+  namespace?: string;
+  /** chant environment, resolved through `k8s.profiles.<env>.context`. */
+  environment?: string;
+  /** Explicit kubectl context — same precedence as `kubectlApply`. */
+  context?: string;
+  /** Project directory whose `chant.config.ts` carries the k8s profiles. */
+  cwd?: string;
+  /** Ownership stack to stamp on a minted Secret (with `env`, the full marker). */
+  stack?: string;
+  /** Ownership env to stamp alongside `stack`. */
+  env?: string;
+}
+
+/**
+ * Ensure a `generated-once` Secret exists in the target cluster. Returns
+ * names only — see core's `EnsureSecretOutcome`.
+ */
+export async function ensureSecret(
+  args: EnsureSecretActivityArgs,
+  _signal?: AbortSignal,
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<EnsureSecretOutcome> {
+  const { client } = await connect({
+    ...(args.environment !== undefined ? { environment: args.environment } : {}),
+    ...(args.context !== undefined ? { context: args.context } : {}),
+    ...(args.cwd !== undefined ? { cwd: args.cwd } : {}),
+  });
+
+  const marker: OwnershipMarker | undefined = args.stack
+    ? { stack: args.stack, ...(args.env ? { env: args.env } : {}) }
+    : undefined;
+
+  const store = k8sSecretStore(args.namespace ?? client.defaultNamespace, client, {
+    ...(marker ? { marker } : {}),
+  });
+  return ensureSecretMaterialization(store, {
+    name: args.name,
+    keys: args.keys,
+    ...(args.metadata ? { metadata: args.metadata } : {}),
+  });
+}

package/src/op/activities/index.ts

@@ -20,6 +20,13 @@
 export { kubectlApply, applyManifest, readManifestDocuments } from "./kubectl";
 export type { KubectlApplyArgs, ApplyManifestResult, AppliedRef, ApplyDeleteMode } from "./kubectl";
 
+// Generated-once secret materialization (#1830) — the activity behind core's
+// `ensureSecret(...)` step builder (#1829). Read-then-write over the
+// namespace-scoped store adapter in ../../secret-store.ts; no output carries
+// secret material.
+export { ensureSecret } from "./ensure-secret";
+export type { EnsureSecretActivityArgs } from "./ensure-secret";
+
 export { waitForArgoSync, defaultArgoStatusFetcher, ArgoSyncFailedError } from "./argo";
 export type { WaitForArgoSyncArgs, ArgoAppStatus, ArgoStatusFetcher } from "./argo";
 

package/src/op/activities/kubectl.test.ts

@@ -461,6 +461,38 @@ describe("the ownership-scoped prune (chant #1075)", () => {
     expect(result.pruned.map((p) => p.name)).toEqual(["old"]);
   });
 
+  test("a generated-once secret is excluded from the prunable set and reported retained; a plain owned secret still prunes (#1830)", async () => {
+    const cluster = fakeCluster({
+      respond: echoApplies,
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: ownedObject("apps/v1", "Deployment", "web", "prod"),
+        [objectKey("v1", "Secret", "master-key", "prod")]: ownedObject("v1", "Secret", "master-key", "prod", {
+          metadata: {
+            labels: {
+              "app.kubernetes.io/managed-by": "chant",
+              "chant.intentius.io/generated-once": "true",
+            },
+          },
+        }),
+        [objectKey("v1", "Secret", "stale-config", "prod")]: ownedObject("v1", "Secret", "stale-config", "prod"),
+      },
+    });
+    const result = await applyManifest(
+      { manifest: manifest(), deleteMode: "owned-only" },
+      undefined,
+      cluster.connector,
+    );
+
+    expect(result.retained).toEqual([
+      { apiVersion: "v1", kind: "Secret", name: "master-key", namespace: "prod" },
+    ]);
+    expect(result.pruned).toEqual([
+      { apiVersion: "v1", kind: "Secret", name: "stale-config", namespace: "prod" },
+    ]);
+    const deletes = cluster.layer.requests.filter((r) => r.method === "DELETE").map((r) => r.path);
+    expect(deletes).toEqual(["/api/v1/namespaces/prod/secrets/stale-config"]);
+  });
+
   test("an object without chant's marker is never a candidate", async () => {
     const cluster = clusterWithOrphans();
     await applyManifest({ manifest: manifest(), deleteMode: "owned-only" }, undefined, cluster.connector);

package/src/op/activities/kubectl.ts

@@ -45,6 +45,7 @@ import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
 import { defaultK8sConnector, type K8sConnector } from "../../api/connect";
 import { operationFor } from "../../api/operation-surface";
 import { DEFAULT_IMPORT_TYPES } from "../../api/sweep-types";
+import { isGeneratedOnce } from "../../secret-labels";
 
 /**
  * How the apply treats chant-owned objects that are no longer declared. The
@@ -133,6 +134,15 @@ export interface ApplyManifestResult {
   applied: AppliedRef[];
   /** Objects deleted because they carried chant's marker and are no longer declared. */
   pruned: AppliedRef[];
+  /**
+   * Owned, no longer declared, and deliberately KEPT (#1830, epic #1365
+   * decision 5): Secrets carrying the `chant.intentius.io/generated-once`
+   * label never enter the prunable set — the stored bytes are the only copy
+   * of material chant never held. Reported loudly here and on the console;
+   * deletion is an explicit act (`kubectl delete`, or a future gated op),
+   * never a prune's. Present whenever the prune ran.
+   */
+  retained?: AppliedRef[];
 }
 
 /** Read a manifest path — one file, or every YAML/JSON file in a directory. */
@@ -351,15 +361,15 @@ export async function applyManifest(
     }
 
     const deleteMode = args.deleteMode ?? "never";
-    const pruned =
+    const { pruned, retained } =
       deleteMode === "never" || args.dryRun
-        ? []
+        ? { pruned: [], retained: [] }
         : await pruneOrphans(client, applied, {
             ...(stack !== undefined ? { stack } : {}),
             signal,
           });
 
-    return { fieldManager, applied, pruned };
+    return { fieldManager, applied, pruned, retained };
   } finally {
     clearInterval(heartbeatInterval);
   }
@@ -407,7 +417,7 @@ async function pruneOrphans(
   client: K8sClient,
   applied: readonly AppliedRef[],
   options: { stack?: string; signal?: AbortSignal },
-): Promise<AppliedRef[]> {
+): Promise<{ pruned: AppliedRef[]; retained: AppliedRef[] }> {
   const stack = options.stack;
   const selector = [
     `${LABEL_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE}`,
@@ -476,6 +486,7 @@ async function pruneOrphans(
   });
 
   const candidates: AppliedRef[] = [];
+  const retained: AppliedRef[] = [];
   const seen = new Set<string>();
   for (const { target, item } of found.flat()) {
     const name = item.metadata?.name;
@@ -494,6 +505,18 @@ async function pruneOrphans(
     const key = refKey(ref);
     if (declared.has(key) || seen.has(key)) continue;
     seen.add(key);
+    // A generated-once Secret never enters the prunable set (#1830, epic
+    // #1365 decision 5): its bytes are the only copy of material chant never
+    // held, so no sweep may destroy them. Kept, and said loudly — deletion is
+    // an explicit act (`kubectl delete`, or a future gated op).
+    if (target.kind === "Secret" && isGeneratedOnce(item.metadata?.labels)) {
+      retained.push(ref);
+      console.log(
+        `${ref.apiVersion} ${ref.kind}/${ref.name} retained (generated-once — owned and no longer declared, ` +
+          `but never pruned; delete it explicitly if you mean to)`,
+      );
+      continue;
+    }
     candidates.push(ref);
   }
 
@@ -504,7 +527,7 @@ async function pruneOrphans(
     safeHeartbeat({ step: "prune", pruned: `${ref.kind}/${ref.name}` });
     console.log(`${ref.apiVersion} ${ref.kind}/${ref.name} pruned (chant-owned, no longer declared)`);
   }
-  return pruned;
+  return { pruned, retained };
 }
 
 function refKey(ref: AppliedRef): string {

package/src/op/activities/wait-for-ready.test.ts

@@ -76,6 +76,40 @@ describe("readiness model", () => {
     expect(firstTerminal(ready([{ type: "Ready", status: "False", reason: "AuthenticationFailed" } as never]), git)).toBeDefined();
   });
 
+  test("CNRM overrides fail fast on Ready=False wedge reasons, DependencyNotReady is not terminal (#1725)", () => {
+    // ContainerCluster and ContainerNodePool back examples/cockroachdb-multi-region-gke's
+    // `longInfra` waits — a cluster wedged at UpdateFailed used to poll out
+    // the whole timeout instead of failing fast.
+    const cluster = readinessFor("container.cnrm.cloud.google.com", "ContainerCluster");
+    expect(cluster).not.toBe(DEFAULT_READINESS);
+    expect(isReady(ready([{ type: "Ready", status: "True" }]), cluster)).toBe(true);
+
+    const updateFailed = ready([{ type: "Ready", status: "False", reason: "UpdateFailed" } as never]);
+    expect(isReady(updateFailed, cluster)).toBe(false);
+    expect(firstTerminal(updateFailed, cluster)).toBeDefined();
+
+    const managementConflict = ready([{ type: "Ready", status: "False", reason: "ManagementConflict" } as never]);
+    expect(firstTerminal(managementConflict, cluster)).toBeDefined();
+
+    // DependencyNotReady is the ordinary "still waiting on another CNRM
+    // resource" state (e.g. a cluster waiting on its network) — not a wedge.
+    const dependencyNotReady = ready([{ type: "Ready", status: "False", reason: "DependencyNotReady" } as never]);
+    expect(firstTerminal(dependencyNotReady, cluster)).toBeUndefined();
+
+    // In-progress reconciles are not terminal either.
+    const updating = ready([{ type: "Ready", status: "False", reason: "Updating" } as never]);
+    expect(firstTerminal(updating, cluster)).toBeUndefined();
+
+    const nodePool = readinessFor("container.cnrm.cloud.google.com", "ContainerNodePool");
+    expect(nodePool).not.toBe(DEFAULT_READINESS);
+    expect(
+      firstTerminal(ready([{ type: "Ready", status: "False", reason: "UpdateFailed" } as never]), nodePool),
+    ).toBeDefined();
+    expect(
+      firstTerminal(ready([{ type: "Ready", status: "False", reason: "DependencyNotReady" } as never]), nodePool),
+    ).toBeUndefined();
+  });
+
   test("Argo override uses health/sync, not a Ready condition", () => {
     const spec = readinessFor("argoproj.io", "Application");
     expect(spec).not.toBe(DEFAULT_READINESS);

package/src/op/activities/wait-for-ready.ts

@@ -98,6 +98,30 @@ const FLUX_TERMINAL = (reasons: string[]): ReadinessSpec => ({
   observedGeneration: true,
 });
 
+/**
+ * Config Connector (CNRM) wedge reasons (#1725): CNRM is kstatus-conformant —
+ * `Ready=True` + `observedGeneration` is the correct ready predicate, same as
+ * `DEFAULT_READINESS` — so, like `FLUX_TERMINAL`, the value added here is
+ * failing fast on a `Ready=False` reason that will not heal by waiting.
+ * `UpdateFailed` is CNRM giving up on a reconcile (bad spec, quota, API
+ * error); `ManagementConflict` is two controllers fighting over the same GCP
+ * resource. Neither resolves on its own.
+ *
+ * `DependencyNotReady` is deliberately excluded: it is the normal state while
+ * a resource waits on another one it depends on (e.g. a `ContainerCluster`
+ * waiting on its network) — exactly the "still being created" case this spec
+ * has to distinguish from a real wedge, not fold into it.
+ *
+ * One entry per kind, matching `FLUX_TERMINAL`'s convention, rather than a
+ * group-level key: CNRM's kinds don't share a single apiGroup (`ContainerCluster`
+ * and `ContainerNodePool` are `container.cnrm.cloud.google.com`; `SQLInstance`
+ * would be `sql.cnrm.cloud.google.com`, etc.), so a group-level key would need
+ * prefix matching against `*.cnrm.cloud.google.com` — a real change to
+ * `readinessFor`'s exact-match lookup for a handful of entries. Not worth it
+ * until more CNRM kinds actually need the override.
+ */
+const CNRM_TERMINAL = (): ReadinessSpec => FLUX_TERMINAL(["UpdateFailed", "ManagementConflict"]);
+
 export const READINESS_OVERRIDES: Record<string, ReadinessSpec> = {
   "argoproj.io/Application": {
     ready: [
@@ -139,6 +163,8 @@ export const READINESS_OVERRIDES: Record<string, ReadinessSpec> = {
     "ChartPackageError",
     "StorageOperationFailed",
   ]),
+  "container.cnrm.cloud.google.com/ContainerCluster": CNRM_TERMINAL(),
+  "container.cnrm.cloud.google.com/ContainerNodePool": CNRM_TERMINAL(),
 };
 
 /** Resolve the readiness spec for a resource: registry override, else default. */

package/src/plugin.ts

@@ -31,6 +31,8 @@ import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
 import { k8sConfigSchema } from "./config-schema";
 import type { K8sChantConfig } from "./config";
 import { renderKustomizeRoots } from "./kustomize/root";
+import { encryptedSecretBuildRoot } from "./sops/encrypted-secret-file";
+import type { Declarable } from "@intentius/chant/declarable";
 
 export const k8sPlugin: LexiconPlugin = {
   name: "k8s",
@@ -79,10 +81,27 @@ export const k8sPlugin: LexiconPlugin = {
   // fallback) and the documents join the build as verbatim manifest entities:
   // serialized with ownership stamping, checked post-synth, observed by
   // `lifecycle diff --live`. See ./kustomize/root.ts.
+  //
+  // The same hook also resolves committed-encrypted `declareSecret()`
+  // declarations: it reads the ciphertext each one names and contributes it
+  // as a verbatim sidecar entity (see ./sops/encrypted-secret-file.ts). Both
+  // halves are one filesystem read at the one sanctioned impure seam.
   async buildRoots(ctx) {
+    const entities = new Map<string, Declarable>();
+    const warnings: string[] = [];
+
     const roots = (ctx.config as { k8s?: K8sChantConfig }).k8s?.kustomize?.roots ?? [];
-    if (roots.length === 0) return { entities: new Map() };
-    return renderKustomizeRoots({ projectRoot: ctx.projectRoot, roots });
+    if (roots.length > 0) {
+      const rendered = await renderKustomizeRoots({ projectRoot: ctx.projectRoot, roots });
+      for (const [name, entity] of rendered.entities) entities.set(name, entity);
+      warnings.push(...rendered.warnings);
+    }
+
+    const encrypted = await encryptedSecretBuildRoot(ctx);
+    for (const [name, entity] of encrypted.entities) entities.set(name, entity);
+    warnings.push(...(encrypted.warnings ?? []));
+
+    return { entities, warnings };
   },
 
   // K8s YAML has no template interpolation functions like CloudFormation's
@@ -678,6 +697,19 @@ const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService
     return describeResources(options);
   },
 
+  // Env teardown (#1222): enumeration + execution over the marker label
+  // selector (managed-by + stack + env), through the same typed client the
+  // prune uses. Execution deletes namespaces last. See ./teardown.ts.
+  async teardownOwned(options) {
+    const { teardownOwned } = await import("./teardown");
+    return teardownOwned(options);
+  },
+
+  async executeTeardown(options) {
+    const { executeTeardown } = await import("./teardown");
+    return executeTeardown(options);
+  },
+
   /**
    * Deploy-unit presence + health for `chant components status --live`
    * (#1495 piece 3): a Kubernetes deploy unit is the label selector chant's

package/src/secret-labels.ts

@@ -0,0 +1,36 @@
+/**
+ * The `generated-once` marker label (chant #1830, epic #1365 decision 5).
+ *
+ * `k8sSecretStore` (./secret-store.ts) stamps this label onto every Secret it
+ * mints, next to the ownership marker. Both k8s prune paths key on it:
+ *
+ * - the apply-path prune (`applyManifest`'s owned-only sweep,
+ *   op/activities/kubectl.ts) excludes a labeled Secret from the prunable set
+ *   and reports it `retained` instead of deleting it;
+ * - env teardown (./teardown.ts `executeTeardown`) reports the same `retained`
+ *   outcome for it, loudly, and never deletes it.
+ *
+ * The rationale is the materialization contract: the stored bytes are the ONLY
+ * copy of material chant never held, so no sweep may destroy them. Deletion is
+ * an explicit human act — `kubectl delete secret <name>`, or a future gated
+ * op — never a side effect of "no longer declared".
+ *
+ * Dependency-light on purpose: no client import, so the constants are usable
+ * from the build path, the prune paths, and the docs/tests alike.
+ */
+
+/** The label key a generated-once Secret carries. */
+export const GENERATED_ONCE_LABEL_KEY = "chant.intentius.io/generated-once";
+
+/** The label value `k8sSecretStore` stamps. */
+export const GENERATED_ONCE_LABEL_VALUE = "true";
+
+/**
+ * True when a live object's labels mark it generated-once. Any non-empty
+ * value counts: the label's presence is the claim, and a sweep must err on
+ * the side of keeping.
+ */
+export function isGeneratedOnce(labels: Record<string, unknown> | undefined): boolean {
+  const value = labels?.[GENERATED_ONCE_LABEL_KEY];
+  return typeof value === "string" && value.length > 0;
+}

package/src/secret-store.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The k8s SecretStoreAdapter (chant #1830) over the fake cluster — a real
+ * `@intentius/chant-k8s-client` with only the HTTP send replaced, the same
+ * harness the teardown and prune suites use.
+ *
+ * What is asserted is the constitutional line as much as the behavior: no
+ * return value and no log line of the read half ever carries a `data` value,
+ * and the write half consumes each key's material exactly once, at the write,
+ * with the ownership marker and the generated-once label stamped on.
+ */
+
+import { describe, test, expect, vi, afterEach } from "vitest";
+import {
+  SecretMaterial,
+  consumeSecretMaterial,
+  ensureSecretMaterialization,
+  SecretContractMismatchError,
+} from "@intentius/chant/secret-materialization";
+import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
+import type { RecordedRequest } from "@intentius/chant-k8s-client/testing";
+import { fakeCluster, objectKey } from "./api/fake-cluster";
+import { k8sSecretStore } from "./secret-store";
+import { GENERATED_ONCE_LABEL_KEY, GENERATED_ONCE_LABEL_VALUE } from "./secret-labels";
+
+const PLAINTEXT_A = "plain-material-alpha";
+const PLAINTEXT_B = "plain-material-bravo";
+const LIVE_VALUE_1 = Buffer.from("live-master-bytes", "utf-8").toString("base64");
+const LIVE_VALUE_2 = Buffer.from("live-conf-bytes", "utf-8").toString("base64");
+
+/** Every string no read-path return or log may ever contain. */
+const FORBIDDEN = [PLAINTEXT_A, PLAINTEXT_B, LIVE_VALUE_1, LIVE_VALUE_2, "live-master-bytes", "live-conf-bytes"];
+
+function liveSecret(): K8sObject {
+  return {
+    apiVersion: "v1",
+    kind: "Secret",
+    metadata: {
+      name: "master-key",
+      namespace: "prod",
+      uid: "uid-master-key",
+      labels: {
+        [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+        [GENERATED_ONCE_LABEL_KEY]: GENERATED_ONCE_LABEL_VALUE,
+      },
+      annotations: { "example.com/note": "hand-written" },
+    },
+    type: "Opaque",
+    data: { MASTER_KEY: LIVE_VALUE_1, "app.conf": LIVE_VALUE_2 },
+  };
+}
+
+function clusterWithSecret() {
+  return fakeCluster({
+    objects: { [objectKey("v1", "Secret", "master-key", "prod")]: liveSecret() },
+    respond: (req: RecordedRequest) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+  });
+}
+
+async function clientOf(cluster: ReturnType<typeof fakeCluster>): Promise<K8sClient> {
+  return (await cluster.connector({})).client;
+}
+
+/** Spies on every console channel; returns everything logged as one string. */
+function spyConsole(): { flush: () => string } {
+  const calls: unknown[][] = [];
+  for (const level of ["log", "info", "warn", "error", "debug"] as const) {
+    vi.spyOn(console, level).mockImplementation((...args: unknown[]) => {
+      calls.push(args);
+    });
+  }
+  return { flush: () => calls.flat().map(String).join("\n") };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("k8sSecretStore — the read half never returns or logs a value", () => {
+  test("exists answers presence and nothing else", async () => {
+    const cluster = clusterWithSecret();
+    const store = k8sSecretStore("prod", await clientOf(cluster));
+    await expect(store.exists("master-key")).resolves.toBe(true);
+    await expect(store.exists("absent")).resolves.toBe(false);
+  });
+
+  test("describe projects key NAMES and labels/annotations, never data values", async () => {
+    const cluster = clusterWithSecret();
+    const spy = spyConsole();
+    const store = k8sSecretStore("prod", await clientOf(cluster));
+
+    const description = await store.describe("master-key");
+
+    expect(description.keys).toEqual(["MASTER_KEY", "app.conf"]);
+    expect(description.metadata?.[GENERATED_ONCE_LABEL_KEY]).toBe(GENERATED_ONCE_LABEL_VALUE);
+    expect(description.metadata?.["example.com/note"]).toBe("hand-written");
+    // The claim that matters: nothing value-shaped in the return, under any
+    // key — the description carries exactly `keys` and `metadata`, and no
+    // byte of the stored values appears anywhere in its serialization.
+    expect(Object.keys(description).sort()).toEqual(["keys", "metadata"]);
+    const serialized = JSON.stringify(description);
+    for (const forbidden of FORBIDDEN) expect(serialized).not.toContain(forbidden);
+    for (const forbidden of FORBIDDEN) expect(spy.flush()).not.toContain(forbidden);
+  });
+
+  test("ensureSecretMaterialization over the adapter: present-and-matching writes nothing", async () => {
+    const cluster = clusterWithSecret();
+    const store = k8sSecretStore("prod", await clientOf(cluster));
+    const outcome = await ensureSecretMaterialization(store, {
+      name: "master-key",
+      keys: ["MASTER_KEY", "app.conf"],
+    });
+    expect(outcome).toEqual({ outcome: "present", name: "master-key", keys: ["MASTER_KEY", "app.conf"] });
+    expect(cluster.layer.requests.filter((r) => r.method === "PATCH")).toEqual([]);
+  });
+
+  test("a key-set mismatch fails loudly naming key names, never values", async () => {
+    const cluster = clusterWithSecret();
+    const store = k8sSecretStore("prod", await clientOf(cluster));
+    const err = await ensureSecretMaterialization(store, {
+      name: "master-key",
+      keys: ["MASTER_KEY", "MISSING_KEY"],
+    }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(SecretContractMismatchError);
+    const message = String((err as Error).message);
+    expect(message).toContain("MISSING_KEY");
+    expect(message).toContain("app.conf");
+    for (const forbidden of FORBIDDEN) expect(message).not.toContain(forbidden);
+  });
+});
+
+describe("k8sSecretStore — create consumes material at the write and stamps the markers", () => {
+  test("mints one value per key, consumes each handle exactly once, stamps ownership + generated-once", async () => {
+    const cluster = fakeCluster({
+      respond: (req: RecordedRequest) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+    });
+    const minted: SecretMaterial[] = [];
+    const generate = vi.fn((key: string) => {
+      const handle = SecretMaterial.mint(key === "MASTER_KEY" ? PLAINTEXT_A : PLAINTEXT_B);
+      minted.push(handle);
+      return handle;
+    });
+
+    const store = k8sSecretStore("prod", await clientOf(cluster), {
+      marker: { stack: "shop", env: "dev" },
+    });
+    const outcome = await ensureSecretMaterialization(
+      store,
+      { name: "master-key", keys: ["MASTER_KEY", "SECOND_KEY"] },
+      generate,
+    );
+    expect(outcome).toEqual({ outcome: "created", name: "master-key", keys: ["MASTER_KEY", "SECOND_KEY"] });
+
+    // One mint per declared key, and every handle burned at the write: a
+    // second consume of any of them throws.
+    expect(generate).toHaveBeenCalledTimes(2);
+    for (const handle of minted) {
+      expect(() => consumeSecretMaterial(handle)).toThrow(/already consumed/);
+    }
+
+    const patch = cluster.layer.requests.find((r) => r.method === "PATCH");
+    expect(patch).toBeDefined();
+    expect(patch!.path).toBe("/api/v1/namespaces/prod/secrets/master-key");
+    expect(patch!.query.fieldManager).toBe("chant:shop");
+    const body = JSON.parse(String(patch!.body)) as K8sObject;
+    expect(body.metadata?.labels).toEqual({
+      [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+      [LABEL_OWNERSHIP_KEYS.stack]: "shop",
+      [LABEL_OWNERSHIP_KEYS.env]: "dev",
+      [GENERATED_ONCE_LABEL_KEY]: GENERATED_ONCE_LABEL_VALUE,
+    });
+    expect(body.data).toEqual({
+      MASTER_KEY: Buffer.from(PLAINTEXT_A, "utf-8").toString("base64"),
+      SECOND_KEY: Buffer.from(PLAINTEXT_B, "utf-8").toString("base64"),
+    });
+  });
+
+  test("the handle itself never leaks material: stringify/inspect show only the redaction marker", () => {
+    const handle = SecretMaterial.mint(PLAINTEXT_A);
+    expect(String(handle)).not.toContain(PLAINTEXT_A);
+    expect(JSON.stringify({ handle })).not.toContain(PLAINTEXT_A);
+    consumeSecretMaterial(handle); // leave no live handle behind
+  });
+});