@intentius/chant-lexicon-cpln 0.53.0

package/dist/rules/cpl029-link-targets.ts

@@ -0,0 +1,155 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf, readString } from "../../entity-props";
+import type { Declarable } from "@intentius/chant/declarable";
+import { KINDS, kindByTypeName } from "../../kinds";
+import { GVC, WORKLOAD, entitiesOfType, parseLink } from "./helpers";
+
+/**
+ * Every string anywhere in a value, so links are found wherever they were
+ * written. Depth-bounded — a spec is deep but finite, and a cycle would not be.
+ */
+function* strings(value: unknown, depth = 0): Generator<string> {
+  if (depth > 12) return;
+  if (typeof value === "string") {
+    yield value;
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) yield* strings(item, depth + 1);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const nested of Object.values(propsOf(value))) yield* strings(nested, depth + 1);
+  }
+}
+
+/**
+ * A workload's identity must live in the workload's own GVC.
+ *
+ * Identities cannot be shared across GVCs — the documented remedy is to
+ * recreate the identity with the same spec in each GVC that needs it. A
+ * cross-GVC `identityLink` is therefore never right, however reasonable it
+ * reads.
+ */
+function identityGvcCheck(entities: Map<string, Declarable>): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [name, entity] of entitiesOfType(entities, WORKLOAD)) {
+    const workloadGvc = readString(entity, "gvc");
+    const identityLink = readString(entity, "spec", "identityLink");
+    if (!workloadGvc || !identityLink) continue;
+
+    const link = parseLink(identityLink);
+    if (!link || link.kind !== "identity" || !link.gvc) continue;
+    if (link.gvc === workloadGvc) continue;
+
+    diagnostics.push({
+      checkId: "CPL029",
+      severity: "error",
+      message:
+        `Workload "${name}" is in GVC "${workloadGvc}" but its identityLink names GVC "${link.gvc}". ` +
+        `Identities cannot be shared across GVCs — declare an identity with the same spec in ` +
+        `"${workloadGvc}".`,
+      entity: name,
+      lexicon: "cpln",
+    });
+  }
+
+  return diagnostics;
+}
+
+export const linkTargetsCheck: PostSynthCheck = {
+  id: "CPL029",
+  description: "Control Plane links must resolve to a declared resource of the right kind and GVC",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Declared resources by kind → name → its GVC (undefined for org-scoped).
+    const declared = new Map<string, Map<string, string | undefined>>();
+    const declaredKinds = new Set<string>();
+
+    for (const [entityName, entity] of ctx.entities) {
+      const kind = kindByTypeName(entity.entityType);
+      if (!kind) continue;
+      declaredKinds.add(kind.kind);
+      const byName = declared.get(kind.kind) ?? new Map<string, string | undefined>();
+      byName.set(readString(entity, "name") ?? entityName, readString(entity, "gvc"));
+      declared.set(kind.kind, byName);
+    }
+
+    const knownKinds = new Set(KINDS.map((k) => k.kind));
+
+    for (const [entityName, entity] of ctx.entities) {
+      const kind = kindByTypeName(entity.entityType);
+      if (!kind) continue;
+      const ownGvc = readString(entity, "gvc");
+
+      for (const value of strings(propsOf(entity))) {
+        const link = parseLink(value);
+        if (!link || !knownKinds.has(link.kind)) continue;
+
+        // Only assert against kinds this stack actually declares. Referencing a
+        // secret managed by another team is ordinary, not a defect.
+        if (!declaredKinds.has(link.kind)) continue;
+
+        const byName = declared.get(link.kind)!;
+        if (!byName.has(link.name)) {
+          diagnostics.push({
+            checkId: "CPL029",
+            severity: "warning",
+            message:
+              `${kind.kind} "${entityName}" links to "${value}", but no ${link.kind} named "${link.name}" ` +
+              `is declared in this stack. Control Plane accepts a dangling link without error.`,
+            entity: entityName,
+            lexicon: "cpln",
+          });
+          continue;
+        }
+
+        const targetGvc = byName.get(link.name);
+        if (link.gvc && targetGvc && link.gvc !== targetGvc) {
+          diagnostics.push({
+            checkId: "CPL029",
+            severity: "error",
+            message:
+              `${kind.kind} "${entityName}" links to "${value}", but ${link.kind} "${link.name}" is ` +
+              `declared in GVC "${targetGvc}".`,
+            entity: entityName,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    // A GVC-scoped resource whose GVC is declared here must name one that exists.
+    if (declaredKinds.has("gvc")) {
+      const gvcNames = new Set<string>();
+      for (const [entityName, entity] of entitiesOfType(ctx.entities, GVC)) {
+        gvcNames.add(readString(entity, "name") ?? entityName);
+      }
+
+      for (const [entityName, entity] of ctx.entities) {
+        const kind = kindByTypeName(entity.entityType);
+        if (!kind?.gvcScoped) continue;
+        const gvc = readString(entity, "gvc");
+        if (!gvc || gvcNames.has(gvc)) continue;
+
+        diagnostics.push({
+          checkId: "CPL029",
+          severity: "warning",
+          message:
+            `${kind.kind} "${entityName}" is placed in GVC "${gvc}", which this stack does not declare. ` +
+            `If the GVC is managed elsewhere this is fine; if it is a typo, the apply fails with a ` +
+            `not-found on the parent.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    diagnostics.push(...identityGvcCheck(ctx.entities));
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl030-domain-routing.ts

@@ -0,0 +1,137 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readPath, readString } from "../../entity-props";
+import { DOMAIN, GVC, WORKLOAD, entitiesOfType, parseLink } from "./helpers";
+
+/** An apex domain has exactly two labels: `example.com`, not `api.example.com`. */
+function isApex(name: string): boolean {
+  return name.split(".").filter(Boolean).length === 2;
+}
+
+export const domainRoutingCheck: PostSynthCheck = {
+  id: "CPL030",
+  description: "Domain DNS mode, certificate challenge, and routing target must be a valid combination",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Workload types, so a `workloadLink` route can be checked for the stateful
+    // requirement that replica-direct routing carries.
+    const workloadTypes = new Map<string, string>();
+    for (const [entityName, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      workloadTypes.set(readString(entity, "name") ?? entityName, readString(entity, "spec", "type") ?? "serverless");
+    }
+
+    for (const [entityName, entity] of entitiesOfType(ctx.entities, DOMAIN)) {
+      const name = readString(entity, "name") ?? entityName;
+      const dnsMode = readString(entity, "spec", "dnsMode") ?? "cname";
+      const challenge = readString(entity, "spec", "certChallengeType");
+      const gvcLink = readString(entity, "spec", "gvcLink");
+      const workloadLink = readString(entity, "spec", "workloadLink");
+      const ports = readArray(entity, "spec", "ports");
+      const routed = ports.some((port) => readArray(port, "routes").length > 0);
+
+      if (dnsMode === "ns" && isApex(name)) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message:
+            `Domain "${name}" is an apex domain with dnsMode "ns". NS mode does not support apex domains — ` +
+            `use "cname".`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      if (dnsMode === "ns" && challenge === "http01") {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message:
+            `Domain "${name}" uses dnsMode "ns" with certChallengeType "http01", which is rejected. ` +
+            `NS mode requires "dns01".`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      const targets = [gvcLink && "gvcLink", workloadLink && "workloadLink", routed && "ports[].routes"].filter(
+        Boolean,
+      ) as string[];
+
+      if (targets.length > 1) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message:
+            `Domain "${name}" sets ${targets.join(" and ")}. These are mutually exclusive ways of saying ` +
+            `where traffic goes — keep exactly one.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      if (targets.length === 0) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "warning",
+          message:
+            `Domain "${name}" names no routing target. Set one of gvcLink, workloadLink, or ports[].routes, ` +
+            `or the domain resolves to nothing.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      // `workloadLink` is replica-direct routing, which only stateful supports.
+      if (workloadLink) {
+        const link = parseLink(workloadLink);
+        const type = link && workloadTypes.get(link.name);
+        if (type && type !== "stateful") {
+          diagnostics.push({
+            checkId: "CPL030",
+            severity: "error",
+            message:
+              `Domain "${name}" routes via workloadLink to "${link!.name}", which is type "${type}". ` +
+              `workloadLink is replica-direct routing and is supported on stateful workloads only.`,
+            entity: entityName,
+            lexicon: "cpln",
+          });
+        }
+      }
+
+      // Every route in a domain must target workloads in one GVC.
+      const routeGvcs = new Set<string>();
+      for (const port of ports) {
+        for (const route of readArray(port, "routes")) {
+          const target = readString(route, "workloadLink");
+          const link = target ? parseLink(target) : undefined;
+          if (link?.gvc) routeGvcs.add(link.gvc);
+        }
+      }
+
+      if (routeGvcs.size > 1) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message:
+            `Domain "${name}" routes to workloads in ${routeGvcs.size} GVCs (${[...routeGvcs].sort().join(", ")}). ` +
+            `All routes in a domain must target workloads in the same GVC.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      if (readPath(entity, "spec", "acceptAllHosts") === true && readPath(entity, "spec", "acceptAllSubdomains") === true) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message: `Domain "${name}" sets both acceptAllHosts and acceptAllSubdomains; they are mutually exclusive.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl040-pinned-image.ts

@@ -0,0 +1,48 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType, imageTag } from "./helpers";
+
+/** A digest pin — `@sha256:…` — is reproducible regardless of tag. */
+const DIGEST = /@sha\d+:[0-9a-f]+$/i;
+
+/**
+ * CPL040: an image reference that is not pinned.
+ *
+ * `:latest`, or no tag at all (which *means* `:latest`), makes what runs a
+ * function of when the workload last happened to pull. On a serverless
+ * workload that scales to zero and cold-starts, that can be several times a
+ * day, so two replicas of "the same" deploy can be different builds.
+ */
+export const pinnedImageCheck: PostSynthCheck = {
+  id: "CPL040",
+  description: "Container images should be pinned to a specific tag or digest",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+        const image = readString(container, "image");
+        if (!image || DIGEST.test(image)) continue;
+
+        const tag = imageTag(image);
+        if (tag && tag !== "latest") continue;
+
+        diagnostics.push({
+          checkId: "CPL040",
+          severity: "warning",
+          message:
+            `Workload "${name}" container "${containerName}" uses image "${image}", which is ` +
+            (tag === "latest" ? `tagged \`latest\`` : `untagged (implicitly \`latest\`)`) +
+            `. Pin a version or a digest — a scale-from-zero cold start re-pulls, so what runs can change ` +
+            `without a deploy.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl041-image-reference-form.ts

@@ -0,0 +1,60 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType } from "./helpers";
+
+/**
+ * CPL041: registry prefixes Control Plane does not want in a workload spec.
+ *
+ * Two documented traps. `docker.io/` must never be added to a public image —
+ * the exact string `nginx:latest` works and `docker.io/library/nginx:latest`
+ * does not. And `<org>.registry.cpln.io/…` is the hostname for `docker login`
+ * and `docker push` only; inside a workload spec the org's own images are
+ * addressed as `//image/NAME:TAG`.
+ */
+export const imageReferenceFormCheck: PostSynthCheck = {
+  id: "CPL041",
+  description: "Image references must not use docker.io/ or the registry hostname form",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+        const image = readString(container, "image");
+        if (!image) continue;
+
+        if (image.startsWith("docker.io/")) {
+          const bare = image.replace(/^docker\.io\/(library\/)?/, "");
+          diagnostics.push({
+            checkId: "CPL041",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" uses image "${image}". Control Plane rejects ` +
+              `the docker.io/ prefix on public images — use "${bare}".`,
+            entity: name,
+            lexicon: "cpln",
+          });
+          continue;
+        }
+
+        const selfHosted = /^([a-z0-9-]+)\.registry\.cpln\.io\/(.+)$/.exec(image);
+        if (selfHosted) {
+          diagnostics.push({
+            checkId: "CPL041",
+            severity: "warning",
+            message:
+              `Workload "${name}" container "${containerName}" uses image "${image}". The ` +
+              `<org>.registry.cpln.io hostname is for \`docker login\` and \`docker push\`; in a workload ` +
+              `spec, an image in this org is "//image/${selfHosted[2]}". (A cross-org pull does use the ` +
+              `hostname form — ignore this if "${selfHosted[1]}" is another org.)`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/cpl042-gvc-placement.ts

@@ -0,0 +1,57 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readPath, readString } from "../../entity-props";
+import { GVC, entitiesOfType } from "./helpers";
+
+/** Location links look like `/org/ORG/location/aws-us-east-1` or `//location/aws-us-east-1`. */
+const LOCATION_LINK = /\/location\/((aws|gcp|azure)-[a-z0-9-]+|[a-z0-9-]+)$/;
+
+/**
+ * CPL042: a GVC with nowhere to run.
+ *
+ * Placement is a GVC-level decision, and a GVC with neither `locationLinks` nor
+ * a `locationQuery` accepts workloads and schedules them nowhere. The workloads
+ * apply cleanly and never become ready.
+ */
+export const gvcPlacementCheck: PostSynthCheck = {
+  id: "CPL042",
+  description: "A GVC must declare where its workloads run",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [entityName, entity] of entitiesOfType(ctx.entities, GVC)) {
+      const name = readString(entity, "name") ?? entityName;
+      const links = readArray(entity, "spec", "staticPlacement", "locationLinks");
+      const query = readPath(entity, "spec", "staticPlacement", "locationQuery");
+
+      if (links.length === 0 && query === undefined) {
+        diagnostics.push({
+          checkId: "CPL042",
+          severity: "error",
+          message:
+            `GVC "${name}" declares no placement. Set spec.staticPlacement.locationLinks (or a ` +
+            `locationQuery) — without one, its workloads apply cleanly and are scheduled nowhere.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+        continue;
+      }
+
+      for (const link of links) {
+        if (typeof link !== "string") continue;
+        if (LOCATION_LINK.test(link)) continue;
+        diagnostics.push({
+          checkId: "CPL042",
+          severity: "warning",
+          message:
+            `GVC "${name}" has location link "${link}", which does not look like a location. Expected ` +
+            `/org/<org>/location/<provider>-<region>, e.g. /org/acme/location/aws-us-east-1.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/helpers.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared reading and parsing for the CPL post-synth checks.
+ *
+ * Each check lives in its own file named for its id, so `CPL027` is greppable
+ * to one place. What they have in common lands here rather than being repeated
+ * or, worse, drifting: the workload-type default, the port enumeration that has
+ * to span both `port` and `ports`, and the quantity parsers.
+ *
+ * Named `helpers.ts` deliberately — the completeness checker's post-synth count
+ * excludes that filename, so a support module is not miscounted as a check.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { readArray, readNumber, readPath, readString } from "../../entity-props";
+import { kindByName } from "../../kinds";
+
+export const WORKLOAD = kindByName("workload")!.typeName;
+export const GVC = kindByName("gvc")!.typeName;
+export const POLICY = kindByName("policy")!.typeName;
+export const DOMAIN = kindByName("domain")!.typeName;
+export const VOLUMESET = kindByName("volumeset")!.typeName;
+
+/** Control Plane defaults an unset workload type to `serverless`. */
+export function workloadType(entity: unknown): string {
+  return readString(entity, "spec", "type") ?? "serverless";
+}
+
+/** The autoscaling block from `defaultOptions`. */
+export function autoscalingOf(entity: unknown): unknown {
+  return readPath(entity, "spec", "defaultOptions", "autoscaling");
+}
+
+/** Every port a workload's containers expose, across both `port` and `ports`. */
+export function exposedPorts(entity: unknown): number[] {
+  const ports: number[] = [];
+  for (const container of readArray(entity, "spec", "containers")) {
+    const single = readNumber(container, "port");
+    if (single !== undefined) ports.push(single);
+    for (const port of readArray(container, "ports")) {
+      const number = readNumber(port, "number");
+      if (number !== undefined) ports.push(number);
+    }
+  }
+  return ports;
+}
+
+/** Parse a CPU quantity (`"50m"`, `"1"`, `"1.5"`) to millicores. */
+export function parseCpuMillicores(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const match = /^(\d+(?:\.\d+)?)(m?)$/.exec(value.trim());
+  if (!match) return undefined;
+  const amount = Number(match[1]);
+  return match[2] === "m" ? amount : amount * 1000;
+}
+
+/** Parse a memory quantity (`"128Mi"`, `"1Gi"`, `"512M"`) to MiB. */
+export function parseMemoryMib(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const match = /^(\d+(?:\.\d+)?)(Ki|Mi|Gi|Ti|K|M|G|T)?$/.exec(value.trim());
+  if (!match) return undefined;
+  const amount = Number(match[1]);
+  const factors: Record<string, number> = {
+    Ki: 1 / 1024,
+    Mi: 1,
+    Gi: 1024,
+    Ti: 1024 * 1024,
+    // Decimal suffixes, converted to MiB so one comparison covers both families.
+    K: 1000 / (1024 * 1024),
+    M: 1_000_000 / (1024 * 1024),
+    G: 1_000_000_000 / (1024 * 1024),
+    T: 1_000_000_000_000 / (1024 * 1024),
+  };
+  const suffix = match[2];
+  if (!suffix) return amount / (1024 * 1024); // bare bytes
+  return amount * factors[suffix];
+}
+
+/**
+ * The tag of an image reference, or undefined when untagged.
+ *
+ * A colon in a registry host's port (`registry:5000/app`) is not a tag, so only
+ * a colon after the last slash counts.
+ */
+export function imageTag(image: string): string | undefined {
+  const lastSlash = image.lastIndexOf("/");
+  const colon = image.indexOf(":", lastSlash + 1);
+  return colon === -1 ? undefined : image.slice(colon + 1);
+}
+
+export interface ParsedLink {
+  kind: string;
+  name: string;
+  gvc?: string;
+}
+
+/** `//gvc/prod/identity/api` → kind `identity`, name `api`, gvc `prod`. */
+const GVC_SCOPED_LINK = /^\/\/gvc\/([^/]+)\/([a-z]+)\/([^/]+)$/;
+/** `//secret/db-password` → kind `secret`, name `db-password`. */
+const ORG_SCOPED_LINK = /^\/\/([a-z]+)\/([^/]+)$/;
+
+/** Parse a Control Plane link, or return undefined if it is not one. */
+export function parseLink(value: string): ParsedLink | undefined {
+  const scoped = GVC_SCOPED_LINK.exec(value);
+  if (scoped) return { gvc: scoped[1], kind: scoped[2], name: scoped[3] };
+
+  const org = ORG_SCOPED_LINK.exec(value);
+  if (org) return { kind: org[1], name: org[2] };
+
+  return undefined;
+}
+
+/** Iterate entities of one type. Re-exported so checks import one module. */
+export { entitiesOfType } from "../../entity-props";
+export type { Declarable };

package/dist/serializer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * cpln serializer — emits the multi-document YAML that `cpln apply --file`
+ * consumes.
+ *
+ * Each declared resource becomes one document:
+ *
+ *   kind: workload
+ *   name: my-app
+ *   gvc: my-gvc
+ *   tags:
+ *     chant.intentius.io/managed-by: chant
+ *   spec:
+ *     containers:
+ *       - name: main
+ *         image: nginx:1.27
+ *
+ * Three things this file is careful about.
+ *
+ * **Only authoring surface is emitted.** Control Plane's own guidance is to
+ * export with `-o yaml-slim` rather than `-o yaml` before re-applying, because
+ * the server-side fields (`status`, `id`, `created`, `lastModified`, `links`)
+ * break `cpln apply`. Those are attributes in this lexicon rather than
+ * properties, so they never reach a document in the first place — the shape a
+ * user can declare is already the slim shape.
+ *
+ * **References become links, not names.** Control Plane addresses resources by
+ * link (`//gvc/prod/identity/api`, `//secret/db-password`), and the GVC-scoped
+ * forms have to carry the GVC. Passing a declared resource where a link is
+ * expected resolves to the right link for its kind, which is the difference
+ * between a reference that survives a rename and a hand-spelled string that
+ * does not. The identity form matters especially: the bare `//identity/NAME`
+ * that reads perfectly plausibly is *silently ignored* by Control Plane's
+ * policy engine, and is documented as a common silent failure.
+ *
+ * **Document order is stable and dependency-first.** `cpln apply` resolves
+ * ordering itself for a multi-doc file, so this is not needed for correctness —
+ * it is so the emitted file diffs cleanly between builds and reads in the order
+ * a person would write it.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SerializeContext } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { type CplnKind } from "./kinds.js";
+/**
+ * `satisfies` rather than a type annotation: `Serializer.serialize` returns
+ * `string | SerializerResult`, and cpln always emits a single YAML string.
+ * Annotating widens the export to the union and every caller — the tests
+ * included — has to narrow it back with a cast that asserts something the
+ * implementation already guarantees. `satisfies` checks the shape against the
+ * interface and keeps the narrower return type.
+ */
+export declare const cplnSerializer: {
+    name: string;
+    rulePrefix: string;
+    serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[], context?: SerializeContext): string;
+};
+/**
+ * Build the Control Plane link for a declared resource.
+ *
+ * GVC-scoped kinds nest under their GVC. For identities in particular the
+ * nested form is not cosmetic: a policy binding written against the bare
+ * `//identity/NAME` is accepted and then ignored.
+ */
+export declare function cplnLink(kind: CplnKind, name: string, gvc?: unknown): string;
+/** Kind order used for document sorting, exported for the serializer tests. */
+export declare const DOCUMENT_KIND_ORDER: readonly string[];
+/** Every modelled kind, re-exported so consumers need not reach into `kinds`. */
+export declare const SERIALIZED_KINDS: CplnKind[];
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAIrE,OAAO,EAAyB,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAmB/D;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;wBAIL,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,aAAa,aAAa,EAAE,YAAY,gBAAgB,GAAG,MAAM;CA4CxF,CAAC;AA+BvB;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,MAAM,CAa5E;AA2ED,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAe,CAAC;AAEjE,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,YAAQ,CAAC"}