@intentius/chant-lexicon-k8s 0.46.0 → 0.50.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/op/builders.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Typed step-builder wrappers (chant #1288 Stage 2). Two things asserted:
+ *
+ *  - **Backward compat**: for every input core's original untyped builder
+ *    accepted, the new typed twin here produces a byte-identical
+ *    `ActivityStep` (own enumerable fields — `.out` is a non-enumerable
+ *    getter on both, per `builders.ts`'s `activity()`, so `toEqual` never
+ *    sees it). Same construction path (`activity()` + `takeProfileAndId`),
+ *    so this is really asserting the two call sites agree, not re-deriving
+ *    the logic.
+ *  - **Step-output refs compose**: a {@link StepOutputRef} in a typed slot
+ *    type-checks and lands in the step's `args` untouched (chant #1950).
+ *
+ * The `@ts-expect-error` block at the bottom is a compile-time-only check —
+ * never executed, just walked by `npm run typecheck` (tsc), which fails if a
+ * marked line does NOT error (an "unused '@ts-expect-error' directive").
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  kubectlApply as kubectlApplyOld,
+  waitForReady as waitForReadyOld,
+  ensureSecret as ensureSecretOld,
+  stepOutput,
+  type StepOutputRef,
+} from "@intentius/chant/op";
+import { kubectlApply, waitForReady, ensureSecret } from "./builders";
+
+describe("k8s typed step builders (#1288 Stage 2)", () => {
+  test("kubectlApply: identical ActivityStep to core's original for a minimal call", () => {
+    expect(kubectlApply("dist/k8s.yaml")).toEqual(kubectlApplyOld("dist/k8s.yaml"));
+  });
+
+  test("kubectlApply: identical ActivityStep with opts (profile override, force, deleteMode)", () => {
+    const opts = { context: "kind-dev", force: true, deleteMode: "owned-only" as const, profile: "fastIdempotent" as const };
+    expect(kubectlApply("dist/k8s.yaml", opts)).toEqual(kubectlApplyOld("dist/k8s.yaml", opts));
+  });
+
+  test("kubectlApply: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("build-step", "manifestPath");
+    const step = kubectlApply("dist/k8s.yaml", { context: ref });
+    expect(step.args?.context).toBe(ref);
+  });
+
+  test("waitForReady: identical ActivityStep to core's original", () => {
+    const opts = { namespace: "prod", intervalMs: 5000 };
+    expect(waitForReady("certificate", "my-cert", opts)).toEqual(waitForReadyOld("certificate", "my-cert", opts));
+  });
+
+  test("ensureSecret: identical ActivityStep to core's original", () => {
+    const opts = { metadata: { team: "platform" } };
+    expect(ensureSecret("db-creds", ["password"], opts)).toEqual(ensureSecretOld("db-creds", ["password"], opts));
+  });
+
+  test("kubectlApply: .out is reachable when an id is given", () => {
+    const step = kubectlApply("dist/k8s.yaml", { id: "apply" });
+    const ref: StepOutputRef = step.out.fieldManager;
+    expect(ref.step).toBe("apply");
+    expect(ref.path).toBe("fieldManager");
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error — "nameSpace" is not a key of KubectlApplyArgs (the
+  // exact typo class chant #1288 names: helmInstall("api", "./chart", {
+  // nameSpace: "prod" }) silently no-opped before this).
+  kubectlApply("dist/k8s.yaml", { nameSpace: "prod" });
+
+  // @ts-expect-error — deleteMode must be one of ApplyDeleteMode's literals.
+  kubectlApply("dist/k8s.yaml", { deleteMode: "always" });
+
+  // @ts-expect-error — force must be boolean, not a string.
+  kubectlApply("dist/k8s.yaml", { force: "yes" });
+
+  // @ts-expect-error — waitForReady's readiness spec field is misspelled.
+  waitForReady("certificate", "my-cert", { specc: {} });
+
+  // @ts-expect-error — ensureSecret's keys must be string[], not a single string.
+  ensureSecret("db-creds", "password");
+}
+void _typeChecksOnly;

package/src/op/builders.ts

@@ -0,0 +1,95 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities (chant #1288
+ * Stage 2 — "regenerate the step builders as fully typed wrappers"). Core
+ * cannot import a lexicon's `*Args` types (lexicons depend on core, not the
+ * other way around — see `packages/core/src/op/activity-contract.ts`'s module
+ * doc for the same layering constraint on Stage 1's contracts), so a fully
+ * typed `kubectlApply`/`waitForReady`/`ensureSecret` has to live beside the
+ * `*Args` interface it derives from: here, next to `./activities/kubectl.ts`
+ * etc. `opts`'s type in each wrapper below IS the activity's own `*Args`
+ * interface (via `Omit`/`WithStepRefs`) — never a hand-restated mirror — so
+ * `kubectlApply`/`waitForReady`/`ensureSecret`'s full option surface (the
+ * dozen-plus cross-field options on `kubectlApply` that Stage 1's zod
+ * contracts deliberately skipped rather than duplicate) is authoring-time
+ * typed for free, and stays in sync with the implementation by construction.
+ *
+ * Every field also accepts a {@link StepOutputRef} in its place
+ * ({@link WithStepRefs}, chant #1950) — a later step's args can consume an
+ * earlier step's declared output.
+ *
+ * `core`'s own `kubectlApply`/`waitForReady`/`ensureSecret` (in
+ * `@intentius/chant/op`, re-exported from `@intentius/chant-lexicon-temporal`
+ * for lexicon-agnostic single-import convenience) are UNCHANGED and produce
+ * byte-identical `ActivityStep` output for the same inputs — these are purely
+ * additive. Deliberately not swapped into the temporal barrel: that would
+ * make `@intentius/chant-lexicon-temporal` depend on this package (and on
+ * helm, for `helmInstall`) at runtime, which is exactly the "a worker image
+ * needs no kubectl binary" / "temporal stays product-agnostic" property the
+ * `op/activities/index.ts` module docs across this repo call out on purpose
+ * (activities were moved OUT of temporal into per-product lexicons for this
+ * reason; the step-builder layer shouldn't reintroduce the coupling from the
+ * other direction). An author who wants the typed surface imports it from
+ * here — `@intentius/chant-lexicon-k8s` — which a project using `kubectlApply`
+ * already depends on; existing `@intentius/chant-lexicon-temporal` imports
+ * keep working exactly as before, opting in only if the import is changed.
+ */
+
+import {
+  activity,
+  takeProfileAndId,
+  type ActivityStep,
+  type NamedActivityStep,
+  type WithStepRefs,
+} from "@intentius/chant/op";
+import type { KubectlApplyArgs } from "./activities/kubectl";
+import type { WaitForReadyArgs } from "./activities/wait-for-ready";
+import type { EnsureSecretActivityArgs } from "./activities/ensure-secret";
+
+/** Extra opts every wrapper below accepts alongside its activity's own fields. */
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+
+/**
+ * Run `kubectl apply -f <manifest>` — the fully typed twin of core's
+ * `kubectlApply` step-builder shortcut (chant #1288 Stage 2). `opts` is
+ * {@link KubectlApplyArgs} itself (minus the positional `manifest`) — every
+ * field `applyManifest` accepts, including `deleteMode`, `force`,
+ * `fieldManager`, `documents`, is authoring-time typed here, not just the
+ * subset a hand-written zod mirror would bother restating. Defaults to the
+ * `longInfra` profile (override via `opts.profile`).
+ */
+export const kubectlApply = (
+  manifest: string,
+  opts?: WithStepRefs<Omit<KubectlApplyArgs, "manifest">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("kubectlApply", { manifest, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Poll a Kubernetes resource until it reports ready, driven by a data-only
+ * readiness spec (CRD-aware; #365) — the fully typed twin of core's
+ * `waitForReady`. `opts` is {@link WaitForReadyArgs} itself, minus the
+ * positional `kind`/`name`. Defaults to the `k8sWait` profile.
+ */
+export const waitForReady = (
+  kind: string,
+  name: string,
+  opts?: WithStepRefs<Omit<WaitForReadyArgs, "kind" | "name">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("waitForReady", { kind, name, ...args }, { profile: profile ?? "k8sWait", ...(id ? { id } : {}) });
+};
+
+/**
+ * Ensure a `generated-once` secret exists in the target store (#1829) — the
+ * fully typed twin of core's `ensureSecret`. `opts` is
+ * {@link EnsureSecretActivityArgs} itself, minus the positional `name`/`keys`.
+ */
+export const ensureSecret = (
+  name: string,
+  keys: string[],
+  opts?: WithStepRefs<Omit<EnsureSecretActivityArgs, "name" | "keys">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("ensureSecret", { name, keys, ...args }, { profile, ...(id ? { id } : {}) });
+};

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

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;
+}