@intentius/chant-lexicon-k8s 0.46.0 → 0.49.0

package/src/composites/composites.test.ts

@@ -10,6 +10,7 @@ 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 { CronWorkload } from "./cron-workload";
 import { AutoscaledService } from "./autoscaled-service";
 import { WorkerPool } from "./worker-pool";
@@ -35,6 +36,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 +3475,271 @@ 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");
+  });
 });
 
 describe("package index re-exports (regression guard)", () => {
@@ -3488,4 +3755,10 @@ 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");
+  });
 });

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,7 @@ 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";

package/src/composites/inference-service.ts

@@ -0,0 +1,140 @@
+/**
+ * InferenceService composite — KServe `InferenceService` (v1beta1).
+ *
+ * Spec-true to KServe: the predictor references a `ServingRuntime` by name
+ * (the plug seam KServe itself defines — see #984's VllmServingRuntime) and
+ * a model `storageUri`, plus the real `ComponentExtensionSpec` autoscaling
+ * knobs (`minReplicas`/`maxReplicas`/`scaleTarget`/`scaleMetric`) and
+ * `canaryTrafficPercent`. No chant-flavored runtime abstraction is invented;
+ * `runtime` is just the `ServingRuntime`/`ClusterServingRuntime` name string
+ * KServe's own webhook resolves against `supportedModelFormats`.
+ *
+ * Coupling note (#984/#986 land in parallel in this same lexicon): this
+ * composite does not import either sibling. `runtime` is a plain name
+ * string (whatever `VllmServingRuntime` from #984 names its `ServingRuntime`
+ * object). `model` accepts either a raw `storageUri` string or a
+ * `{ storageUri }`-shaped object — the resolved-value shape `Model` from
+ * #986 is expected to return — matched structurally, not by import.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { InferenceService as InferenceServiceResource } from "../generated";
+
+/** Knative concurrency, or a raw HPA metric (cpu/memory/rps). */
+export type ScaleMetric = "concurrency" | "cpu" | "memory" | "rps";
+
+/**
+ * A resolved model reference. Matches the resolved-value shape the `Model`
+ * composite (#986) is expected to return — structurally, not by import.
+ */
+export interface ModelReference {
+  storageUri: string;
+}
+
+export interface InferenceServiceProps {
+  name: string;
+  namespace: string;
+  /** A raw `storageUri` (e.g. `"gs://bucket/model"`) or a resolved model ref. */
+  model: string | ModelReference;
+  /** `ServingRuntime`/`ClusterServingRuntime` name the predictor pins to. */
+  runtime: string;
+  /**
+   * Model format name for KServe's runtime auto-matching (e.g. `"vLLM"`).
+   * Optional since `runtime` already pins the ServingRuntime explicitly;
+   * set it if the ServingRuntime's `supportedModelFormats` expects it.
+   */
+  modelFormat?: string;
+  /** Minimum predictor replicas. */
+  minReplicas?: number;
+  /** Maximum predictor replicas. */
+  maxReplicas?: number;
+  /** Autoscaling target value (e.g. concurrency-per-replica, or CPU/memory/RPS target). */
+  scaleTarget?: number;
+  /** Which metric `scaleTarget` is measured against. */
+  scaleMetric?: ScaleMetric;
+  /** Percentage of traffic (0-100) routed to this revision as a canary. */
+  canaryTrafficPercent?: number;
+  labels?: Record<string, string>;
+  defaults?: {
+    inferenceService?: Partial<Record<string, unknown>>;
+  };
+}
+
+export type InferenceServiceResult = {
+  inferenceService: InstanceType<typeof InferenceServiceResource>;
+};
+
+function resolveStorageUri(model: string | ModelReference): string {
+  return typeof model === "string" ? model : model.storageUri;
+}
+
+/**
+ * Create an InferenceService composite — a KServe `InferenceService`
+ * predictor referencing a `ServingRuntime` and a model `storageUri`, with
+ * autoscaling bounds and an optional canary traffic split.
+ *
+ * @example
+ * ```ts
+ * import { InferenceService } from "@intentius/chant-lexicon-k8s";
+ *
+ * const svc = 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,
+ * });
+ * ```
+ */
+export const InferenceService = Composite((props: InferenceServiceProps) => {
+  const {
+    name,
+    namespace,
+    model,
+    runtime,
+    modelFormat,
+    minReplicas,
+    maxReplicas,
+    scaleTarget,
+    scaleMetric,
+    canaryTrafficPercent,
+    labels: extraLabels = {},
+    defaults: defs,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    "app.kubernetes.io/component": "inference-service",
+    ...extraLabels,
+  };
+
+  const predictor: Record<string, unknown> = {
+    model: {
+      runtime,
+      storageUri: resolveStorageUri(model),
+      ...(modelFormat !== undefined && { modelFormat: { name: modelFormat } }),
+    },
+    ...(minReplicas !== undefined && { minReplicas }),
+    ...(maxReplicas !== undefined && { maxReplicas }),
+    ...(scaleTarget !== undefined && { scaleTarget }),
+    ...(scaleMetric !== undefined && { scaleMetric }),
+    ...(canaryTrafficPercent !== undefined && { canaryTrafficPercent }),
+  };
+
+  const inferenceService = new InferenceServiceResource(mergeDefaults({
+    metadata: {
+      name,
+      namespace,
+      labels: commonLabels,
+    },
+    spec: { predictor },
+  }, defs?.inferenceService));
+
+  return { inferenceService };
+}, "InferenceService");

package/src/composites/model.ts

@@ -0,0 +1,150 @@
+/**
+ * Model composite — resolves a model artifact reference to a KServe
+ * `storageUri` (+ optional warm-cache PVC), keyed by `(id, version)`.
+ *
+ * This is the FSx-warm-cache equivalent from the Netflix serving yardstick
+ * (see epic #982): a small, spec-true resolver that InferenceService (#985)
+ * consumes for its predictor's model reference. It does not itself emit an
+ * InferenceService or ServingRuntime — those are #984/#985's job.
+ *
+ * `version` is required so every resolved `storageUri` is pinned: the
+ * version is always appended as the trailing path segment, whether the
+ * default `id`-derived path is used or `uri` overrides it. This keeps the
+ * output stable for the unpinned-model lint rule (#988).
+ *
+ * `Model` itself is a plain resolver — a resolved value object, per the
+ * composite conventions — rather than a `Composite`, because its primary
+ * output (`storageUri`) is a string, not a Declarable; a `Composite`
+ * factory's members must all be Declarables. The optional cache PVC is
+ * built through an internal `Composite` so it gets the same bookkeeping
+ * (provenance, defaults-merging) as every other emitted resource.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { PersistentVolumeClaim } from "../generated";
+
+/** Where the model's weights live. Maps to the matching KServe storage-initializer scheme. */
+export type ModelSource = "hf" | "gcs" | "s3" | "pvc";
+
+const STORAGE_SCHEME: Record<ModelSource, string> = {
+  hf: "hf",
+  gcs: "gs",
+  s3: "s3",
+  pvc: "pvc",
+};
+
+export interface ModelProps {
+  /** Model identifier, e.g. "llama-3-8b-instruct". Used to key the resolved storageUri and cache PVC. */
+  id: string;
+  /**
+   * Model version/revision. REQUIRED — feeds the unpinned-model lint rule
+   * (#988). Always appears as the trailing segment of the resolved
+   * `storageUri` so the reference is pinned.
+   */
+  version: string;
+  /** Where the model artifact is hosted; selects the storageUri scheme. */
+  source: ModelSource;
+  /**
+   * Explicit path override (e.g. a bucket/prefix, HF repo id, or PVC name)
+   * in place of the `id`-derived default. `version` is still appended.
+   */
+  uri?: string;
+  /** When set, emits a warm-cache PVC named `${id}-${version}` for the InferenceService (#985) to mount. */
+  cache?: {
+    storageClass: string;
+    size: string;
+  };
+  /** Per-member defaults for fine-grained overrides. */
+  defaults?: {
+    cachePvc?: Partial<Record<string, unknown>>;
+  };
+}
+
+export interface ModelResult {
+  /** Resolved KServe storageUri, pinned to `version`. */
+  storageUri: string;
+  /** Warm-cache PVC, present only when `cache` is set. Named `${id}-${version}`. */
+  cache?: InstanceType<typeof PersistentVolumeClaim>;
+}
+
+/**
+ * Resolve a model artifact's `{ id, version, source, uri }` to a pinned
+ * KServe `storageUri` string.
+ */
+export function resolveModelStorageUri(props: Pick<ModelProps, "id" | "version" | "source" | "uri">): string {
+  const { id, version, source, uri } = props;
+  const scheme = STORAGE_SCHEME[source];
+  const path = uri ?? id;
+  return `${scheme}://${path}/${version}`;
+}
+
+interface ModelCachePvcProps {
+  id: string;
+  version: string;
+  storageClass: string;
+  size: string;
+  defaults?: Partial<Record<string, unknown>>;
+}
+
+const ModelCachePvc = Composite<ModelCachePvcProps, { pvc: InstanceType<typeof PersistentVolumeClaim> }>(
+  (props) => {
+    const { id, version, storageClass, size, defaults } = props;
+
+    const pvc = new PersistentVolumeClaim(mergeDefaults({
+      metadata: {
+        name: `${id}-${version}`,
+        labels: {
+          "app.kubernetes.io/name": id,
+          "app.kubernetes.io/managed-by": "chant",
+          "app.kubernetes.io/component": "model-cache",
+        },
+      },
+      spec: {
+        accessModes: ["ReadWriteMany"],
+        storageClassName: storageClass,
+        resources: { requests: { storage: size } },
+      },
+    }, defaults));
+
+    return { pvc };
+  },
+  "ModelCachePvc",
+);
+
+/**
+ * Resolve a model artifact `{ id, version, source, uri, cache }` to a pinned
+ * `storageUri`, with an optional warm-cache PVC.
+ *
+ * @example
+ * ```ts
+ * import { Model } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { storageUri, cache } = Model({
+ *   id: "llama-3-8b-instruct",
+ *   version: "2024-07-01",
+ *   source: "gcs",
+ *   uri: "my-models-bucket/llama-3-8b-instruct",
+ *   cache: { storageClass: "premium-rwo", size: "200Gi" },
+ * });
+ * ```
+ */
+export function Model(props: ModelProps): ModelResult {
+  const { id, version, cache, defaults } = props;
+
+  const storageUri = resolveModelStorageUri(props);
+
+  const cachePvc = cache
+    ? ModelCachePvc({
+        id,
+        version,
+        storageClass: cache.storageClass,
+        size: cache.size,
+        defaults: defaults?.cachePvc,
+      }).pvc
+    : undefined;
+
+  return {
+    storageUri,
+    ...(cachePvc && { cache: cachePvc }),
+  };
+}