@intentius/chant-lexicon-k8s 0.46.0 → 0.50.0

package/src/composites/composites.test.ts

@@ -10,6 +10,9 @@ function p(member: unknown): Record<string, unknown> {
 import { StatefulApp } from "./stateful-app";
 import { ArgoAppFor, ArgoAppSetForRegions, registerArgoCluster } from "./argo-app";
 import { FluxGitSource, FluxAppFor } from "./flux-app";
+import { Model, resolveModelStorageUri } from "./model";
+import { OperatorStack, deriveHostVerbClass } from "./operator-stack";
+import type { OpConfig } from "@intentius/chant/op";
 import { CronWorkload } from "./cron-workload";
 import { AutoscaledService } from "./autoscaled-service";
 import { WorkerPool } from "./worker-pool";
@@ -35,6 +38,7 @@ import { GcePdStorageClass } from "./gce-pd-storage-class";
 import { FilestoreStorageClass } from "./filestore-storage-class";
 import { GkeGateway } from "./gke-gateway";
 import { ConfigConnectorContext } from "./config-connector-context";
+import { InferenceService } from "./inference-service";
 
 // ── WebApp ──────────────────────────────────────────────────────────
 
@@ -3473,6 +3477,546 @@ describe("FluxAppFor", () => {
     expect(spec.timeout).toBe("3m");
     expect(spec.serviceAccountName).toBe("flux-applier");
   });
+
+  test("omits decryption when the option is not set", () => {
+    const spec = p(FluxAppFor("hello", { source: "flux-system", path: "./k8s" }).kustomization).spec as any;
+    expect(spec.decryption).toBeUndefined();
+  });
+
+  test('decryption: "sops" defaults the secretRef to sops-age', () => {
+    const spec = p(
+      FluxAppFor("hello", { source: "flux-system", path: "./k8s", decryption: "sops" }).kustomization,
+    ).spec as any;
+    expect(spec.decryption).toEqual({ provider: "sops", secretRef: { name: "sops-age" } });
+  });
+
+  test("decryption object form names a custom secretRef", () => {
+    const spec = p(
+      FluxAppFor("hello", {
+        source: "flux-system",
+        path: "./k8s",
+        decryption: { provider: "sops", secretRef: "my-age-identity" },
+      }).kustomization,
+    ).spec as any;
+    expect(spec.decryption).toEqual({ provider: "sops", secretRef: { name: "my-age-identity" } });
+  });
+
+  test("decryption object form with no secretRef still defaults to sops-age", () => {
+    const spec = p(
+      FluxAppFor("hello", { source: "flux-system", path: "./k8s", decryption: { provider: "sops" } }).kustomization,
+    ).spec as any;
+    expect(spec.decryption).toEqual({ provider: "sops", secretRef: { name: "sops-age" } });
+  });
+});
+
+// ── InferenceService ─────────────────────────────────────────────────
+
+describe("InferenceService", () => {
+  test("emits a valid InferenceService referencing the runtime and storageUri", () => {
+    const result = InferenceService({
+      name: "llama-3-8b",
+      namespace: "serving",
+      model: "gs://my-models/llama-3-8b/v1",
+      runtime: "vllm-runtime",
+    });
+    expect(result.inferenceService).toBeDefined();
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.model.runtime).toBe("vllm-runtime");
+    expect(spec.predictor.model.storageUri).toBe("gs://my-models/llama-3-8b/v1");
+  });
+
+  test("accepts a resolved model ref ({ storageUri }) in place of a raw string", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: { storageUri: "s3://bucket/model/v2" },
+      runtime: "vllm-runtime",
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.model.storageUri).toBe("s3://bucket/model/v2");
+  });
+
+  test("modelFormat is omitted unless explicitly set", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.model.modelFormat).toBeUndefined();
+  });
+
+  test("modelFormat.name flows through when set", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+      modelFormat: "vLLM",
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.model.modelFormat).toEqual({ name: "vLLM" });
+  });
+
+  test("autoscaling bounds (minReplicas/maxReplicas/scaleTarget/scaleMetric) are expressible and present", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+      minReplicas: 1,
+      maxReplicas: 4,
+      scaleTarget: 8,
+      scaleMetric: "concurrency",
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.minReplicas).toBe(1);
+    expect(spec.predictor.maxReplicas).toBe(4);
+    expect(spec.predictor.scaleTarget).toBe(8);
+    expect(spec.predictor.scaleMetric).toBe("concurrency");
+  });
+
+  test("raw-HPA scaleMetric values (cpu/memory/rps) pass through", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+      scaleMetric: "cpu",
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.scaleMetric).toBe("cpu");
+  });
+
+  test("autoscaling fields are absent when not set", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.minReplicas).toBeUndefined();
+    expect(spec.predictor.maxReplicas).toBeUndefined();
+    expect(spec.predictor.scaleTarget).toBeUndefined();
+    expect(spec.predictor.scaleMetric).toBeUndefined();
+  });
+
+  test("canary traffic split is expressible and present", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+      canaryTrafficPercent: 10,
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.canaryTrafficPercent).toBe(10);
+  });
+
+  test("canary traffic split is absent when not set", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.canaryTrafficPercent).toBeUndefined();
+  });
+
+  test("includes common labels and metadata", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+      labels: { team: "ml-platform" },
+    });
+    const meta = p(result.inferenceService).metadata as any;
+    expect(meta.name).toBe("svc");
+    expect(meta.namespace).toBe("ns");
+    expect(meta.labels["app.kubernetes.io/name"]).toBe("svc");
+    expect(meta.labels["app.kubernetes.io/managed-by"]).toBe("chant");
+    expect(meta.labels.team).toBe("ml-platform");
+  });
+
+  test("golden: full spec shape with predictor, model, autoscaling, and canary", () => {
+    const result = InferenceService({
+      name: "llama-3-8b",
+      namespace: "serving",
+      model: "gs://my-models/llama-3-8b/v1",
+      runtime: "vllm-runtime",
+      modelFormat: "vLLM",
+      minReplicas: 1,
+      maxReplicas: 4,
+      scaleTarget: 8,
+      scaleMetric: "concurrency",
+      canaryTrafficPercent: 10,
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec).toEqual({
+      predictor: {
+        model: {
+          runtime: "vllm-runtime",
+          storageUri: "gs://my-models/llama-3-8b/v1",
+          modelFormat: { name: "vLLM" },
+        },
+        minReplicas: 1,
+        maxReplicas: 4,
+        scaleTarget: 8,
+        scaleMetric: "concurrency",
+        canaryTrafficPercent: 10,
+      },
+    });
+  });
+
+  test("defaults passthrough merges into the InferenceService", () => {
+    const result = InferenceService({
+      name: "svc",
+      namespace: "ns",
+      model: "gs://bucket/model",
+      runtime: "vllm-runtime",
+      defaults: {
+        inferenceService: { spec: { predictor: { model: { protocolVersion: "v2" } } } },
+      },
+    });
+    const spec = p(result.inferenceService).spec as any;
+    expect(spec.predictor.model.protocolVersion).toBe("v2");
+    expect(spec.predictor.model.runtime).toBe("vllm-runtime");
+  });
+});
+
+// ── Model ─────────────────────────────────────────────────────────
+
+describe("Model", () => {
+  test("resolves a gcs source to a gs:// storageUri pinned to version", () => {
+    const result = Model({ id: "llama-3-8b", version: "2024-07-01", source: "gcs" });
+    expect(result.storageUri).toBe("gs://llama-3-8b/2024-07-01");
+  });
+
+  test("resolves an s3 source to an s3:// storageUri pinned to version", () => {
+    const result = Model({ id: "llama-3-8b", version: "2024-07-01", source: "s3" });
+    expect(result.storageUri).toBe("s3://llama-3-8b/2024-07-01");
+  });
+
+  test("resolves a pvc source to a pvc:// storageUri pinned to version", () => {
+    const result = Model({ id: "llama-3-8b", version: "2024-07-01", source: "pvc" });
+    expect(result.storageUri).toBe("pvc://llama-3-8b/2024-07-01");
+  });
+
+  test("resolves an hf source to an hf:// storageUri pinned to version", () => {
+    const result = Model({ id: "llama-3-8b", version: "2024-07-01", source: "hf" });
+    expect(result.storageUri).toBe("hf://llama-3-8b/2024-07-01");
+  });
+
+  test("an explicit uri overrides the id-derived path but version is still appended", () => {
+    const result = Model({
+      id: "llama-3-8b",
+      version: "2024-07-01",
+      source: "gcs",
+      uri: "my-models-bucket/llama-3-8b-instruct",
+    });
+    expect(result.storageUri).toBe("gs://my-models-bucket/llama-3-8b-instruct/2024-07-01");
+  });
+
+  test("no cache PVC by default", () => {
+    const result = Model({ id: "llama-3-8b", version: "2024-07-01", source: "gcs" });
+    expect(result.cache).toBeUndefined();
+  });
+
+  test("emits a cache PVC named `${id}-${version}` when cache is set", () => {
+    const result = Model({
+      id: "llama-3-8b",
+      version: "2024-07-01",
+      source: "gcs",
+      cache: { storageClass: "premium-rwo", size: "200Gi" },
+    });
+    expect(result.cache).toBeDefined();
+    expect((p(result.cache) as any).metadata.name).toBe("llama-3-8b-2024-07-01");
+    expect((p(result.cache) as any).spec.storageClassName).toBe("premium-rwo");
+    expect((p(result.cache) as any).spec.resources.requests.storage).toBe("200Gi");
+  });
+
+  test("resolveModelStorageUri is the same resolution the composite uses", () => {
+    expect(resolveModelStorageUri({ id: "m", version: "v1", source: "s3" })).toBe("s3://m/v1");
+  });
+});
+
+// ── OperatorStack ────────────────────────────────────────────────────────
+
+const READ_ONLY_OP: Pick<OpConfig, "phases" | "onFailure"> = {
+  phases: [{ name: "check", steps: [{ kind: "activity", fn: "lifecycleDiff" }] }],
+};
+const MUTATING_OP: Pick<OpConfig, "phases" | "onFailure"> = {
+  phases: [{ name: "apply", steps: [{ kind: "activity", fn: "kubectlApply" }] }],
+};
+const DESTRUCTIVE_OP: Pick<OpConfig, "phases" | "onFailure"> = {
+  phases: [{ name: "teardown", steps: [{ kind: "activity", fn: "envTeardown" }] }],
+};
+
+describe("OperatorStack", () => {
+  test("returns a namespace and one CronJob/ServiceAccount/Role/RoleBinding per hosted ConvergeOp", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [
+        { name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" },
+        { name: "fountain-apply", schedule: "*/10 * * * *", env: "staging", dial: "apply", dispatchTargets: [MUTATING_OP] },
+      ],
+    });
+    expect(result.namespace).toBeDefined();
+    expect(result["cronJob_fountain-observe"]).toBeDefined();
+    expect(result["cronJob_fountain-apply"]).toBeDefined();
+    expect(result["serviceAccount_fountain-observe"]).toBeDefined();
+    expect(result["serviceAccount_fountain-apply"]).toBeDefined();
+    expect(result["role_fountain-observe"]).toBeDefined();
+    expect(result["role_fountain-apply"]).toBeDefined();
+    expect(result["roleBinding_fountain-observe"]).toBeDefined();
+    expect(result["roleBinding_fountain-apply"]).toBeDefined();
+  });
+
+  test("namespace name defaults to the stack name", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" }],
+    });
+    expect((p(result.namespace).metadata as any).name).toBe("chant-operator");
+  });
+
+  test("namespace name is overridable", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      namespace: "chant-ops",
+      image: "chant:latest",
+      converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" }],
+    });
+    expect((p(result.namespace).metadata as any).name).toBe("chant-ops");
+    expect((p(result["cronJob_fountain-observe"]).metadata as any).namespace).toBe("chant-ops");
+  });
+
+  test("CronJob schedule passes through from the hosted ConvergeOp", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-observe", schedule: "17 * * * *", env: "staging" }],
+    });
+    expect((p(result["cronJob_fountain-observe"]).spec as any).schedule).toBe("17 * * * *");
+  });
+
+  test("CronJob uses concurrencyPolicy Forbid — never queue a tick behind one in flight", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" }],
+    });
+    expect((p(result["cronJob_fountain-observe"]).spec as any).concurrencyPolicy).toBe("Forbid");
+  });
+
+  test("CronJob container command defaults to `chant run <name>`", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" }],
+    });
+    const container = (p(result["cronJob_fountain-observe"]).spec as any).jobTemplate.spec.template.spec.containers[0];
+    expect(container.image).toBe("chant:latest");
+    expect(container.command).toEqual(["chant", "run", "fountain-observe"]);
+    expect(container.env).toEqual([
+      { name: "CHANT_CONVERGE_ENV", value: "staging" },
+      { name: "CHANT_CONVERGE_DIAL", value: "observe" },
+    ]);
+  });
+
+  test("CronJob container command is overridable per host", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging", command: ["chant", "operator", "tick", "fountain-observe"] }],
+    });
+    const container = (p(result["cronJob_fountain-observe"]).spec as any).jobTemplate.spec.template.spec.containers[0];
+    expect(container.command).toEqual(["chant", "operator", "tick", "fountain-observe"]);
+  });
+
+  test("ServiceAccount is bound to the CronJob's pod spec", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" }],
+    });
+    const podSpec = (p(result["cronJob_fountain-observe"]).spec as any).jobTemplate.spec.template.spec;
+    expect(podSpec.serviceAccountName).toBe("fountain-observe-sa");
+    expect((p(result["serviceAccount_fountain-observe"]).metadata as any).name).toBe("fountain-observe-sa");
+    const binding = p(result["roleBinding_fountain-observe"]) as any;
+    expect(binding.subjects[0]).toEqual({ kind: "ServiceAccount", name: "fountain-observe-sa", namespace: "chant-operator" });
+    expect(binding.roleRef).toEqual({ apiGroup: "rbac.authorization.k8s.io", kind: "Role", name: "fountain-observe-role" });
+  });
+
+  // ── RBAC derivation ──────────────────────────────────────────────────
+
+  test("a ConvergeOp with no dispatch targets gets read-only RBAC", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" }],
+    });
+    const role = p(result["role_fountain-observe"]) as any;
+    for (const rule of role.rules) {
+      expect(rule.verbs).toEqual(["get", "list", "watch"]);
+    }
+  });
+
+  test("observe-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — observe never dispatches, per TMP014/convergeTick", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-watch", schedule: "*/10 * * * *", env: "staging", dial: "observe", dispatchTargets: [MUTATING_OP] }],
+    });
+    const role = p(result["role_fountain-watch"]) as any;
+    for (const rule of role.rules) {
+      expect(rule.verbs).toEqual(["get", "list", "watch"]);
+    }
+  });
+
+  test("reconcile-dial ConvergeOp with a mutating dispatch target still gets read-only RBAC — TMP014 only lets apply free-run a mutating dispatch", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-reconcile", schedule: "*/10 * * * *", env: "staging", dial: "reconcile", dispatchTargets: [MUTATING_OP] }],
+    });
+    const role = p(result["role_fountain-reconcile"]) as any;
+    for (const rule of role.rules) {
+      expect(rule.verbs).toEqual(["get", "list", "watch"]);
+    }
+  });
+
+  test("apply-dial ConvergeOp with a mutating dispatch target gets create/update/patch, never delete or wildcard", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-apply", schedule: "*/10 * * * *", env: "staging", dial: "apply", dispatchTargets: [MUTATING_OP] }],
+    });
+    const role = p(result["role_fountain-apply"]) as any;
+    expect(role.rules.length).toBeGreaterThan(0);
+    for (const rule of role.rules) {
+      expect(rule.verbs).toEqual(["get", "list", "watch", "create", "update", "patch"]);
+      expect(rule.verbs).not.toContain("delete");
+      expect(rule.verbs).not.toContain("deletecollection");
+      expect(rule.verbs).not.toContain("*");
+      expect(rule.resources).not.toContain("*");
+      expect(rule.apiGroups).not.toContain("*");
+    }
+  });
+
+  test("apply-dial ConvergeOp with only a read-only dispatch target stays read-only — least privilege, not dial-implied ceiling", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{ name: "fountain-verify", schedule: "*/10 * * * *", env: "staging", dial: "apply", dispatchTargets: [READ_ONLY_OP] }],
+    });
+    const role = p(result["role_fountain-verify"]) as any;
+    for (const rule of role.rules) {
+      expect(rule.verbs).toEqual(["get", "list", "watch"]);
+    }
+  });
+
+  test("a destructive dispatch target is refused at construction, even under dial apply", () => {
+    expect(() =>
+      OperatorStack({
+        name: "chant-operator",
+        image: "chant:latest",
+        converge: [{ name: "fountain-teardown", schedule: "*/10 * * * *", env: "staging", dial: "apply", dispatchTargets: [DESTRUCTIVE_OP] }],
+      }),
+    ).toThrow(/destructive/);
+  });
+
+  test("two hosts in the same stack get independently scoped RBAC — never the union", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [
+        { name: "fountain-observe", schedule: "*/10 * * * *", env: "staging", dial: "observe" },
+        { name: "fountain-apply", schedule: "*/10 * * * *", env: "staging", dial: "apply", dispatchTargets: [MUTATING_OP] },
+      ],
+    });
+    expect((p(result["role_fountain-observe"]) as any).rules[0].verbs).toEqual(["get", "list", "watch"]);
+    expect((p(result["role_fountain-apply"]) as any).rules[0].verbs).toEqual(["get", "list", "watch", "create", "update", "patch"]);
+  });
+
+  test("custom resource rules are used instead of the default set", () => {
+    const result: any = OperatorStack({
+      name: "chant-operator",
+      image: "chant:latest",
+      converge: [{
+        name: "fountain-secrets",
+        schedule: "*/10 * * * *",
+        env: "staging",
+        resources: [{ apiGroups: [""], resources: ["secrets"] }],
+      }],
+    });
+    const role = p(result["role_fountain-secrets"]) as any;
+    expect(role.rules).toEqual([{ apiGroups: [""], resources: ["secrets"], verbs: ["get", "list", "watch"] }]);
+  });
+
+  // ── deriveHostVerbClass (unit) ───────────────────────────────────────
+
+  test("deriveHostVerbClass: reconcile dial with a mutating target stays read-only", () => {
+    expect(deriveHostVerbClass("x", "reconcile", [MUTATING_OP])).toBe("read-only");
+  });
+
+  test("deriveHostVerbClass: apply dial with a mutating target elevates to mutating", () => {
+    expect(deriveHostVerbClass("x", "apply", [MUTATING_OP])).toBe("mutating");
+  });
+
+  test("deriveHostVerbClass: apply dial with only read-only targets stays read-only", () => {
+    expect(deriveHostVerbClass("x", "apply", [READ_ONLY_OP])).toBe("read-only");
+  });
+
+  test("deriveHostVerbClass: a destructive target throws under any dial", () => {
+    expect(() => deriveHostVerbClass("x", "apply", [DESTRUCTIVE_OP])).toThrow(/destructive/);
+    expect(() => deriveHostVerbClass("x", "observe", [DESTRUCTIVE_OP])).toThrow(/destructive/);
+  });
+
+  // ── Build-time refusals ──────────────────────────────────────────────
+
+  test("refuses an empty converge array", () => {
+    expect(() => OperatorStack({ name: "chant-operator", image: "chant:latest", converge: [] })).toThrow(/at least one/);
+  });
+
+  test("refuses duplicate hosted ConvergeOp names", () => {
+    expect(() =>
+      OperatorStack({
+        name: "chant-operator",
+        image: "chant:latest",
+        converge: [
+          { name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" },
+          { name: "fountain-observe", schedule: "*/5 * * * *", env: "staging" },
+        ],
+      }),
+    ).toThrow(/duplicate/);
+  });
+
+  test("refuses a host with a blank schedule", () => {
+    expect(() =>
+      OperatorStack({
+        name: "chant-operator",
+        image: "chant:latest",
+        converge: [{ name: "fountain-observe", schedule: "", env: "staging" }],
+      }),
+    ).toThrow(/schedule/);
+  });
+
+  test("refuses a blank image", () => {
+    expect(() =>
+      OperatorStack({
+        name: "chant-operator",
+        image: "",
+        converge: [{ name: "fountain-observe", schedule: "*/10 * * * *", env: "staging" }],
+      }),
+    ).toThrow(/image/);
+  });
 });
 
 describe("package index re-exports (regression guard)", () => {
@@ -3488,4 +4032,16 @@ describe("package index re-exports (regression guard)", () => {
     expect(typeof pkg.FluxGitSource).toBe("function");
     expect(typeof pkg.FluxAppFor).toBe("function");
   });
+
+  test("Model is reachable from the package entry", async () => {
+    const pkg: any = await import("../index");
+    expect(typeof pkg.Model).toBe("function");
+    expect(typeof pkg.resolveModelStorageUri).toBe("function");
+  });
+
+  test("OperatorStack is reachable from the package entry", async () => {
+    const pkg: any = await import("../index");
+    expect(typeof pkg.OperatorStack).toBe("function");
+    expect(typeof pkg.deriveHostVerbClass).toBe("function");
+  });
 });

package/src/composites/flux-app.ts

@@ -29,6 +29,10 @@ import {
 /** The namespace the Flux controllers run in and watch by default. */
 const FLUX_NAMESPACE = "flux-system";
 
+/** knr-ops's name for the bootstrap-injected age identity Secret, and the
+ * name `flux bootstrap` documentation uses. */
+const SOPS_AGE_SECRET_NAME = "sops-age";
+
 /** Source kinds a Kustomization can reconcile from. */
 export type FluxSourceKind = "GitRepository" | "OCIRepository" | "Bucket";
 
@@ -154,6 +158,15 @@ export interface FluxAppForOptions {
   suspend?: boolean;
   /** ServiceAccount the kustomize-controller impersonates for this app. */
   serviceAccountName?: string;
+  /**
+   * SOPS decryption for the reconciled path. `"sops"` is shorthand for the
+   * default age Secret name (`sops-age`); pass an object to name a different
+   * one. Never inferred — the path this Kustomization reconciles is usually
+   * the output of a *different* `chant build`, so the composite cannot know
+   * whether it contains SOPS ciphertext. See WK8505 for the build-time check
+   * that catches a committed-encrypted secret with no wiring here.
+   */
+  decryption?: "sops" | { provider: "sops"; secretRef?: string };
   /** Namespace the Kustomization object itself lives in (default "flux-system"). */
   fluxNamespace?: string;
   /** Extra labels applied to the Kustomization. */
@@ -210,12 +223,21 @@ const FluxKustomization = Composite<{ target: string } & FluxAppForOptions, Flux
       timeout,
       suspend,
       serviceAccountName,
+      decryption,
       fluxNamespace = FLUX_NAMESPACE,
       labels = {},
       defaults,
     } = props;
 
     const sourceRef = resolveSourceRef(target, source);
+    const decryptionSpec = decryption === undefined
+      ? undefined
+      : {
+        provider: "sops",
+        secretRef: {
+          name: typeof decryption === "string" ? SOPS_AGE_SECRET_NAME : decryption.secretRef ?? SOPS_AGE_SECRET_NAME,
+        },
+      };
 
     // The Kustomization's namespace also scopes the sourceRef: an in-spec
     // sourceRef without a namespace resolves in the Kustomization's own.
@@ -240,6 +262,7 @@ const FluxKustomization = Composite<{ target: string } & FluxAppForOptions, Flux
         ...(timeout !== undefined && { timeout }),
         ...(suspend !== undefined && { suspend }),
         ...(serviceAccountName !== undefined && { serviceAccountName }),
+        ...(decryptionSpec !== undefined && { decryption: decryptionSpec }),
       },
     }, defaults?.kustomization));
 

package/src/composites/index.ts

@@ -81,6 +81,13 @@ export { RayJob } from "./ray-job";
 export type { RayJobProps, RayJobResult } from "./ray-job";
 export { RayService } from "./ray-service";
 export type { RayServiceProps, RayServiceResult } from "./ray-service";
+export { InferenceService } from "./inference-service";
+export type {
+  InferenceServiceProps,
+  InferenceServiceResult,
+  ModelReference,
+  ScaleMetric,
+} from "./inference-service";
 export { ArgoAppFor, ArgoAppSetForRegions, registerArgoCluster } from "./argo-app";
 export type {
   ArgoDestination,
@@ -102,3 +109,11 @@ export type {
   FluxAppForOptions,
   FluxAppForResult,
 } from "./flux-app";
+export { VllmServingRuntime } from "./vllm-serving-runtime";
+export type { VllmServingRuntimeProps, VllmServingRuntimeResult, VllmResourceSpec } from "./vllm-serving-runtime";
+export { Model, resolveModelStorageUri } from "./model";
+export type { ModelSource, ModelProps, ModelResult } from "./model";
+export { OperatorStack, deriveHostVerbClass, DEFAULT_RESOURCE_RULES } from "./operator-stack";
+export type {
+  OperatorDial, OperatorRbacResourceRule, OperatorStackConvergeHost, OperatorStackConfig, OperatorStackResult,
+} from "./operator-stack";