@intentius/chant-lexicon-cpln 0.124.31 → 0.124.32

package/dist/composites/public-domain.js

@@ -0,0 +1,70 @@
+/**
+ * PublicDomain — a custom domain routed to workloads in one GVC.
+ *
+ * Domains carry several rules that are easy to violate by picking the
+ * combination that reads best rather than the one that works:
+ *
+ * - An **apex domain must use `cname` mode**. NS mode does not support apex,
+ *   and there is no partial-credit failure — the domain simply will not
+ *   validate.
+ * - **NS mode requires the `dns01` certificate challenge**; `http01` is
+ *   rejected outright.
+ * - `gvcLink`, `workloadLink` and `ports[].routes` are **mutually exclusive**
+ *   ways of saying where traffic goes; exactly one may be set.
+ * - Every route in a domain must target workloads in the **same GVC**.
+ *
+ * This composite takes a GVC and a route table, derives the mode when it can,
+ * and refuses the combinations above at build time.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Domain } from "../generated/index.js";
+/** An apex domain has exactly one dot: `example.com`, not `api.example.com`. */
+export function isApexDomain(name) {
+    return name.split(".").filter(Boolean).length === 2;
+}
+export const PublicDomain = Composite((props) => {
+    const { name, gvc, routes, dnsMode = "cname", certChallengeType = dnsMode === "ns" ? "dns01" : "http01", port = 443, protocol = "http2", tags, defaults: defs, } = props;
+    if (dnsMode === "ns" && isApexDomain(name)) {
+        throw new Error(`PublicDomain "${name}": an apex domain must use dnsMode "cname". NS mode does not support apex domains.`);
+    }
+    if (dnsMode === "ns" && certChallengeType !== "dns01") {
+        throw new Error(`PublicDomain "${name}": dnsMode "ns" requires certChallengeType "dns01"; "${certChallengeType}" is rejected.`);
+    }
+    for (const route of routes ?? []) {
+        if (!route.prefix && !route.regex) {
+            throw new Error(`PublicDomain "${name}": every route needs a \`prefix\` or a \`regex\`.`);
+        }
+        if (route.prefix && route.regex) {
+            throw new Error(`PublicDomain "${name}": route for workload "${route.workload}" sets both \`prefix\` and \`regex\`; ` +
+                `only one may be provided.`);
+        }
+    }
+    const domain = new Domain(mergeDefaults({
+        name,
+        ...(tags && { tags }),
+        spec: {
+            dnsMode,
+            certChallengeType,
+            // `gvcLink` and `ports[].routes` are mutually exclusive: a domain
+            // with explicit routes must not also carry a GVC link.
+            ...(routes && routes.length > 0
+                ? {
+                    ports: [
+                        {
+                            number: port,
+                            protocol,
+                            routes: routes.map((route) => ({
+                                ...(route.prefix && { prefix: route.prefix }),
+                                ...(route.regex && { regex: route.regex }),
+                                ...(route.replacePrefix && { replacePrefix: route.replacePrefix }),
+                                port: route.port ?? 8080,
+                                workloadLink: `//gvc/${gvc}/workload/${route.workload}`,
+                            })),
+                        },
+                    ],
+                }
+                : { gvcLink: `//gvc/${gvc}` }),
+        },
+    }, defs?.domain));
+    return { domain };
+}, "PublicDomain");

package/dist/composites/secret-access.js

@@ -0,0 +1,82 @@
+/**
+ * SecretAccess — the identity and policy a workload needs to read a secret.
+ *
+ * Control Plane's own documentation calls a partial version of this its number
+ * one support issue: reading a secret at runtime takes three separate steps,
+ * and **missing any one of them fails silently at runtime** rather than at
+ * apply time.
+ *
+ *   1. An identity exists, and the workload's `spec.identityLink` points at it.
+ *   2. A policy grants that identity `reveal` on the secret, with the identity
+ *      named as a principal in a binding.
+ *   3. The workload references the secret in the field-qualified form —
+ *      `cpln://secret/NAME.payload`, not `cpln://secret/NAME`.
+ *
+ * This composite owns steps 1 and 2, and {@link secretRef} exists for step 3 so
+ * the field qualifier is hard to forget.
+ *
+ * The principal link is the part most worth automating. A binding written
+ * against `//identity/NAME` — which reads perfectly naturally, and is what
+ * you would guess — is accepted by the API and then **silently ignored**. Only
+ * the GVC-qualified `//gvc/GVC/identity/NAME` form works. This composite only
+ * emits the qualified form.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Identity, Policy } from "../generated/index.js";
+export const SecretAccess = Composite((props) => {
+    const { name, gvc, secrets, policyName = `${name}-secret-access`, permissions = ["reveal"], tags, defaults: defs, } = props;
+    if (secrets.length === 0) {
+        throw new Error(`SecretAccess "${name}": no secrets listed. A policy with no target links grants nothing, ` +
+            `and the workload would fail to read its secrets at runtime with no apply-time error.`);
+    }
+    const identity = new Identity(mergeDefaults({
+        name,
+        gvc,
+        ...(tags && { tags }),
+    }, defs?.identity));
+    const policy = new Policy(mergeDefaults({
+        name: policyName,
+        ...(tags && { tags }),
+        targetKind: "secret",
+        targetLinks: [...secrets].sort().map((secret) => `//secret/${secret}`),
+        bindings: [
+            {
+                // Sorted and deduplicated: Control Plane requires permissions in a
+                // binding to be both.
+                permissions: [...new Set(permissions)].sort(),
+                // The GVC-qualified form. The bare `//identity/NAME` is silently
+                // ignored — see the module comment.
+                principalLinks: [identityLink(gvc, name)],
+            },
+        ],
+    }, defs?.policy));
+    return { identity, policy };
+}, "SecretAccess");
+/**
+ * The GVC-qualified principal link for an identity.
+ *
+ * Exported because this is the form policies must use, and the unqualified one
+ * fails silently.
+ */
+export function identityLink(gvc, name) {
+    return `//gvc/${gvc}/identity/${name}`;
+}
+/**
+ * A field-qualified secret reference for use in a container's env or volumes.
+ *
+ * The field name is required. `cpln://secret/db.password` resolves; the
+ * unqualified `cpln://secret/db` does not, except for `gcp` secrets mounted as
+ * a file. The field differs by secret type:
+ *
+ * | Type | Field |
+ * |---|---|
+ * | `opaque` | `payload` |
+ * | `dictionary` | any key |
+ * | `userpass` | `username`, `password` |
+ * | `tls` | `cert`, `key` |
+ * | `keypair` | `publicKey`, `privateKey` |
+ * | `aws` | `accessKey`, `secretKey`, `roleArn` |
+ */
+export function secretRef(name, field) {
+    return `cpln://secret/${name}.${field}`;
+}

package/dist/composites/serverless-service.js

@@ -0,0 +1,58 @@
+/**
+ * ServerlessService — a serverless workload with the port, probe and firewall
+ * settings a public HTTP service actually needs.
+ *
+ * Serverless is the Control Plane workload type with the most rules attached to
+ * it, and most of them are easy to get wrong by omission rather than by writing
+ * something incorrect:
+ *
+ * - It must expose *exactly one* HTTP port. Zero or two is rejected.
+ * - The external firewall's inbound is closed by default, so a workload that
+ *   looks completely correct serves nothing until a CIDR is added.
+ * - `concurrency` and `rps` are the only strategies that scale to zero, and
+ *   only on this workload type.
+ *
+ * The defaults here are Control Plane's own, restated so they are visible at
+ * the call site rather than implied.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Workload } from "../generated/index.js";
+export const ServerlessService = Composite((props) => {
+    const { name, gvc, image, port = 8080, protocol = "http", containerName = "main", cpu = "50m", memory = "128Mi", env, inboundAllowCidr = [], outboundAllowCidr = [], minScale = 1, maxScale = 5, autoscalingMetric = "concurrency", autoscalingTarget = 95, identityLink, tags, defaults: defs, } = props;
+    const workload = new Workload(mergeDefaults({
+        name,
+        gvc,
+        ...(tags && { tags }),
+        spec: {
+            type: "serverless",
+            ...(identityLink && { identityLink }),
+            containers: [
+                {
+                    name: containerName,
+                    image,
+                    cpu,
+                    memory,
+                    ports: [{ number: port, protocol }],
+                    ...(env && {
+                        env: Object.entries(env).map(([envName, value]) => ({ name: envName, value })),
+                    }),
+                },
+            ],
+            firewallConfig: {
+                external: {
+                    inboundAllowCIDR: inboundAllowCidr,
+                    outboundAllowCIDR: outboundAllowCidr,
+                },
+            },
+            defaultOptions: {
+                autoscaling: {
+                    metric: autoscalingMetric,
+                    target: autoscalingTarget,
+                    minScale,
+                    maxScale,
+                },
+            },
+        },
+    }, defs?.workload));
+    return { workload };
+}, "ServerlessService");

package/dist/composites/stateful-service.js

@@ -0,0 +1,87 @@
+/**
+ * StatefulService — a stateful workload with its volume set, mounted.
+ *
+ * Persistent storage on Control Plane is two resources that have to agree, and
+ * the ways they can disagree are all expensive:
+ *
+ * - `ext4` and `xfs` volume sets bind to exactly one *stateful* workload.
+ *   Mounting one from a serverless or standard workload is not a degraded
+ *   mode, it is rejected.
+ * - `fileSystemType` and `performanceClass` are both immutable. Changing
+ *   either later means delete and recreate, which means data loss.
+ * - `high-throughput-ssd` has a 200 GB floor, not the 10 GB floor the other
+ *   classes have, so an initial capacity that is fine for one class is invalid
+ *   for another.
+ * - A volume set is GVC-scoped and only mountable from its own GVC.
+ *
+ * This composite pairs them so the mount URI, the GVC and the workload type
+ * cannot drift apart, and validates the capacity floor at build time rather
+ * than at apply time.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Workload, VolumeSet } from "../generated/index.js";
+/** Minimum initial capacity in GB, by performance class. */
+const MIN_CAPACITY_GB = {
+    "general-purpose-ssd": 10,
+    "high-throughput-ssd": 200,
+    shared: 10,
+};
+export const StatefulService = Composite((props) => {
+    const { name, gvc, image, mountPath, capacityGb, volumeSetName = `${name}-data`, fileSystemType = "ext4", performanceClass = "general-purpose-ssd", recoveryPolicy = "retain", ports = [], containerName = "main", cpu = "50m", memory = "128Mi", env, inboundAllowCidr = [], outboundAllowCidr = [], minScale = 1, maxScale = 1, identityLink, tags, defaults: defs, } = props;
+    const floor = MIN_CAPACITY_GB[performanceClass];
+    if (floor !== undefined && capacityGb < floor) {
+        throw new Error(`StatefulService "${name}": capacityGb ${capacityGb} is below the ${floor} GB minimum for ` +
+            `performanceClass "${performanceClass}". Both fileSystemType and performanceClass are immutable ` +
+            `after creation, so this is worth getting right before the first apply.`);
+    }
+    const volumeSet = new VolumeSet(mergeDefaults({
+        name: volumeSetName,
+        gvc,
+        ...(tags && { tags }),
+        spec: {
+            initialCapacity: capacityGb,
+            fileSystemType,
+            // Control Plane forces `shared` for a shared filesystem; setting it
+            // explicitly keeps the emitted manifest equal to what comes back.
+            performanceClass: fileSystemType === "shared" ? "shared" : performanceClass,
+            snapshots: { createFinalSnapshot: true },
+        },
+    }, defs?.volumeSet));
+    const workload = new Workload(mergeDefaults({
+        name,
+        gvc,
+        ...(tags && { tags }),
+        spec: {
+            type: "stateful",
+            ...(identityLink && { identityLink }),
+            containers: [
+                {
+                    name: containerName,
+                    image,
+                    cpu,
+                    memory,
+                    ...(ports.length > 0 && {
+                        ports: ports.map((p) => ({ number: p.number, protocol: p.protocol ?? "http" })),
+                    }),
+                    ...(env && {
+                        env: Object.entries(env).map(([envName, value]) => ({ name: envName, value })),
+                    }),
+                    volumes: [
+                        {
+                            uri: `cpln://volumeset/${volumeSetName}`,
+                            path: mountPath,
+                            recoveryPolicy,
+                        },
+                    ],
+                },
+            ],
+            firewallConfig: {
+                external: { inboundAllowCIDR: inboundAllowCidr, outboundAllowCIDR: outboundAllowCidr },
+            },
+            defaultOptions: {
+                autoscaling: { minScale, maxScale },
+            },
+        },
+    }, defs?.workload));
+    return { workload, volumeSet };
+}, "StatefulService");

package/dist/coverage.js

@@ -0,0 +1,104 @@
+/**
+ * Coverage analysis for the cpln lexicon.
+ *
+ * The shared `computeCoverage` measures CloudFormation-shaped dimensions
+ * (lifecycle flags, return attributes, extension constraints) that an
+ * eight-kind OpenAPI lexicon has no analog for — it would report 0% on
+ * everything and mean nothing. What cpln needs to know is two different things:
+ *
+ *   1. **Kind coverage** — which of the API's kinds are modelled as declarables
+ *      and which are deliberately not, with the reason, so an unmodelled kind
+ *      is a decision on record rather than an omission nobody noticed.
+ *   2. **Property coverage** — for each modelled kind, how much of its writable
+ *      surface is typed rather than loosened to `Record<string, unknown>`. A
+ *      drop here means upstream reshaped something and the parser quietly
+ *      stopped following it.
+ *
+ * Both are measured against the spec the generator actually reads, so running
+ * this after `just generate` compares like with like.
+ */
+import { fetchSchemas, SPEC_KEY } from "./spec/fetch.js";
+import { parseCplnOpenAPI } from "./spec/parse.js";
+import { KINDS } from "./kinds.js";
+/**
+ * Kinds the API exposes that this lexicon does not model, and why.
+ *
+ * "First pass" is a real reason, not a placeholder: each of these is a row in
+ * `kinds.ts` away, and listing them keeps the gap visible instead of leaving a
+ * reader to infer it from the absence.
+ */
+export const UNMODELLED_KINDS = {
+    agent: "first pass — org infrastructure, not the workload surface",
+    auditctx: "first pass — governance",
+    cloudaccount: "first pass — org infrastructure",
+    group: "first pass — principals",
+    serviceaccount: "first pass — principals",
+    user: "first pass — principals; membership is invite-driven, not declarative",
+    image: "read-mostly — images are produced by `cpln image build`, not declared",
+    location: "read-mostly — locations are platform-provided; only `patch` is writable",
+    org: "not declarable — an org is immutable and cannot be deleted",
+    quota: "read-only",
+    mk8s: "first pass — a very large nested spec that deserves its own pass",
+    task: "read-only — an operation record, not estate",
+    deployment: "read-only — a workload's runtime status",
+};
+const LOOSE = /^Record<string, (unknown|any)>/;
+/** Compute coverage from the spec the generator reads. */
+export async function computeCplnCoverage(options) {
+    const schemas = await fetchSchemas({ force: options?.force });
+    const raw = schemas.get(SPEC_KEY);
+    if (!raw)
+        throw new Error(`spec fetch returned no ${SPEC_KEY} entry`);
+    const results = parseCplnOpenAPI(raw);
+    const resources = results.filter((r) => !r.isProperty);
+    const propertyTypes = results.filter((r) => r.isProperty);
+    const kinds = [];
+    let typed = 0;
+    let total = 0;
+    for (const kind of KINDS) {
+        const resource = resources.find((r) => r.resource.typeName === kind.typeName);
+        if (!resource)
+            continue;
+        const properties = resource.resource.properties;
+        const loose = properties.filter((p) => LOOSE.test(p.tsType)).length;
+        // Property types whose name is derived from this kind's class name.
+        const owned = propertyTypes.filter((p) => p.resource.typeName.split("::").pop().startsWith(kind.className)).length;
+        kinds.push({ kind: kind.kind, properties: properties.length, propertyTypes: owned, loose });
+        typed += properties.length - loose;
+        total += properties.length;
+    }
+    return {
+        modelled: resources.length,
+        unmodelled: Object.keys(UNMODELLED_KINDS).length,
+        propertyTypes: propertyTypes.length,
+        kinds,
+        typedRatio: total === 0 ? 0 : typed / total,
+    };
+}
+/**
+ * Print the coverage report. Exits non-zero when `minOverall` is set and the
+ * typed ratio falls below it, so CI can gate on the surface not silently
+ * loosening.
+ */
+export async function analyzeCplnCoverage(options) {
+    const coverage = await computeCplnCoverage({ force: options?.force });
+    console.error(`cpln coverage: ${coverage.modelled} kinds modelled, ${coverage.unmodelled} not, ` +
+        `${coverage.propertyTypes} property types, ${(coverage.typedRatio * 100).toFixed(0)}% of writable ` +
+        `properties typed`);
+    for (const kind of coverage.kinds) {
+        const detail = kind.loose > 0 ? ` (${kind.loose} loose)` : "";
+        console.error(`  ${kind.kind.padEnd(11)} ${String(kind.properties).padStart(2)} properties, ` +
+            `${String(kind.propertyTypes).padStart(3)} property types${detail}`);
+    }
+    if (options?.verbose) {
+        console.error("\nNot modelled:");
+        for (const [kind, reason] of Object.entries(UNMODELLED_KINDS)) {
+            console.error(`  ${kind.padEnd(15)} ${reason}`);
+        }
+    }
+    if (options?.minOverall !== undefined && coverage.typedRatio * 100 < options.minOverall) {
+        console.error(`\nTyped ratio ${(coverage.typedRatio * 100).toFixed(0)}% is below the ${options.minOverall}% minimum.`);
+        process.exitCode = 1;
+    }
+    return coverage;
+}

package/dist/describe-resources.js

@@ -0,0 +1,264 @@
+/**
+ * Live introspection of cpln resources — the read-back seam for chant's
+ * plan/drift machinery.
+ *
+ * Drives core's observer harness (`observeEntities`) rather than re-deriving
+ * its control flow: bind-or-not-observe-all with a typed reason, per-entity
+ * tri-state routing, and a read throw degrading to `read-failed` rather than a
+ * silent absence — which would classify as a spurious `create` and, on the
+ * delete path, as an orphan.
+ *
+ * The read is a lookup, not a fetch. Control Plane has a by-name endpoint for
+ * every kind, but it also has an **org-wide rollup** for the GVC-scoped ones
+ * (`/org/{org}/workload` alongside `/org/{org}/gvc/{gvc}/workload`), so listing
+ * each declared kind once and indexing it costs one request per kind instead of
+ * one per resource — or, for GVC-scoped kinds, one per GVC. The list promise is
+ * cached per kind, so concurrent reads share a request and a failed list marks
+ * only that kind's entities read-failed.
+ *
+ * Ownership is unusually clean here. Every kind carries a free-form `tags` map
+ * and every read path returns it, so the marker resolves on the thin read —
+ * which is not true of aws, where `describe-stack-resources` returns no tags
+ * and an `owned: true` thin read can only answer `unknown`. `describeResources`
+ * is therefore declared on the ownership channel.
+ *
+ * No secret value is ever read: the `-reveal` endpoint is not called from this
+ * path, and a `secret`'s `data` is not part of what is compared.
+ */
+import { observeEntities, } from "@intentius/chant/observation";
+import { hasOwnershipMarker } from "@intentius/chant/ownership";
+import { CplnCredentialsError, defaultCplnHttp, listKind, resolveConfig, } from "./api.js";
+import { kindByTypeName } from "./kinds.js";
+import { CPLN_TAG_OWNERSHIP_KEYS } from "./ownership.js";
+/**
+ * Observe every declared cpln resource against the live org.
+ */
+export async function describeResources(options) {
+    const declared = [];
+    for (const name of options.entityNames) {
+        const entity = options.entities.get(name);
+        if (!entity)
+            continue;
+        declared.push({ name, type: entity.entityType, props: entity.props });
+    }
+    return observeEntities(declared, adapter(options));
+}
+function adapter(options) {
+    return {
+        async bind() {
+            const config = resolveConfig(options.config);
+            return { config, http: options.http ?? defaultCplnHttp(config), lists: new Map() };
+        },
+        classifyBindFailure(err) {
+            if (err instanceof CplnCredentialsError) {
+                return { reason: "no-credentials", detail: err.message };
+            }
+            return { reason: "read-failed", detail: err instanceof Error ? err.message : String(err) };
+        },
+        async read(client, entity) {
+            const kind = kindByTypeName(entity.type);
+            if (!kind) {
+                return { unobserved: { reason: "unsupported-kind", detail: `${entity.type} is not a modelled cpln kind` } };
+            }
+            const index = await listFor(client, kind);
+            const declaredName = typeof entity.props.name === "string" ? entity.props.name : entity.name;
+            const live = index.get(declaredName);
+            if (!live)
+                return { absent: true };
+            // A GVC-scoped kind is listed org-wide, so two GVCs may hold resources of
+            // the same name. Compare the live resource's own GVC before calling it a
+            // match — otherwise a workload in `staging` would be reported as the
+            // observed state of the one declared in `prod`.
+            if (kind.gvcScoped) {
+                const declaredGvc = typeof entity.props.gvc === "string" ? entity.props.gvc : undefined;
+                const liveGvc = gvcOf(live);
+                if (declaredGvc && liveGvc && declaredGvc !== liveGvc)
+                    return { absent: true };
+            }
+            const owned = hasOwnershipMarker(live.tags, CPLN_TAG_OWNERSHIP_KEYS);
+            // `owned: true` filters rather than hides: a foreign resource becomes a
+            // typed NOT-OBSERVED, so the caller can tell "not chant's" from "not
+            // there" — the latter would read as a create.
+            if (options.owned && !owned) {
+                return {
+                    unobserved: {
+                        reason: "filtered",
+                        detail: `live ${kind.kind} "${declaredName}" carries no ${CPLN_TAG_OWNERSHIP_KEYS.managedBy} tag`,
+                    },
+                };
+            }
+            return { present: toMetadata(kind, live, owned) };
+        },
+    };
+}
+/** List a kind once per observation, sharing the promise across entities. */
+function listFor(client, kind) {
+    const cached = client.lists.get(kind.kind);
+    if (cached)
+        return cached;
+    const pending = listKind(client.http, client.config, kind);
+    client.lists.set(kind.kind, pending);
+    return pending;
+}
+/**
+ * The GVC a live resource belongs to.
+ *
+ * The org-wide rollups do not repeat the GVC as a field; it is in the `links`
+ * array as a `gvc` relation (`/org/acme/gvc/prod`). `volumeset` and `identity`
+ * additionally carry a `gvc` of their own, in two different shapes, so those
+ * are read as a fallback.
+ */
+export function gvcOf(resource) {
+    for (const link of resource.links ?? []) {
+        if (link.rel !== "gvc" || typeof link.href !== "string")
+            continue;
+        const name = link.href.split("/").filter(Boolean).pop();
+        if (name)
+            return name;
+    }
+    const own = resource.gvc;
+    if (typeof own === "string" && own.length > 0)
+        return own.split("/").filter(Boolean).pop();
+    if (own && typeof own === "object") {
+        const name = own.name;
+        if (typeof name === "string")
+            return name;
+    }
+    return undefined;
+}
+/**
+ * Map a live resource onto chant's `ResourceMetadata`.
+ *
+ * `status` is a string in chant's model and an object in Control Plane's, so it
+ * is summarized rather than stringified: a workload's readiness where there is
+ * one, `"active"` otherwise. The full object stays available under `attributes`
+ * for anything that wants to look closer.
+ */
+function toMetadata(kind, live, owned) {
+    return {
+        type: kind.typeName,
+        physicalId: live.id,
+        status: statusOf(live),
+        lastUpdated: live.lastModified,
+        ownership: owned ? "owned" : "foreign",
+        attributes: {
+            name: live.name,
+            version: live.version,
+            refs: referenceAttributes(kind, live),
+            ...(live.tags ? { tags: live.tags } : {}),
+            ...(kind.gvcScoped ? { gvc: gvcOf(live) } : {}),
+            ...(live.status ? { status: live.status } : {}),
+        },
+    };
+}
+/**
+ * Resolve this resource's outbound links down to the bare names they point at.
+ *
+ * Edge reconstruction matches identifiers exactly, and a Control Plane link
+ * (`//gvc/prod/identity/api`) never equals the `name` it references. Resolving
+ * here — where the whole live resource is in hand — means `reference-catalog.ts`
+ * is a plain table of paths rather than a table of paths plus extractors, and
+ * means no second enrichment pass over the observed set.
+ *
+ * Keys are stable regardless of kind; an absent relation is simply missing.
+ */
+export function referenceAttributes(kind, live) {
+    const refs = {};
+    const spec = (live.spec ?? {});
+    if (kind.gvcScoped) {
+        const gvc = gvcOf(live);
+        if (gvc)
+            refs.gvc = gvc;
+    }
+    const identity = linkName(spec.identityLink);
+    if (identity)
+        refs.identity = identity;
+    const pullSecrets = linkNames(spec.pullSecretLinks);
+    if (pullSecrets.length > 0)
+        refs.pullSecrets = pullSecrets;
+    // A domain's GVC is a link rather than a scoping relation, so it is read from
+    // the spec even though the kind is org-scoped.
+    if (kind.kind === "domain") {
+        const gvc = linkName(spec.gvcLink);
+        if (gvc)
+            refs.gvc = gvc;
+    }
+    const workloads = [
+        ...linkNames(spec.workloadLink),
+        ...linkNames(spec.link),
+        ...routeWorkloads(spec),
+    ].filter((name, index, all) => all.indexOf(name) === index);
+    if (workloads.length > 0)
+        refs.workloads = workloads;
+    const targets = linkNames(live.targetLinks);
+    if (targets.length > 0)
+        refs.targets = targets;
+    const volumeSets = mountedVolumeSets(spec);
+    if (volumeSets.length > 0)
+        refs.volumeSets = volumeSets;
+    return refs;
+}
+/** The last path segment of a link (`//gvc/prod/identity/api` → `api`). */
+function linkName(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return undefined;
+    if (!value.startsWith("//") && !value.startsWith("/org/") && !value.startsWith("cpln://"))
+        return undefined;
+    // A `cpln://secret/name.field` reference names a field after the resource.
+    const last = value.split("/").filter(Boolean).pop();
+    return last?.split(".")[0];
+}
+/** Resolve a link or a list of links to names, dropping anything unparseable. */
+function linkNames(value) {
+    const values = Array.isArray(value) ? value : [value];
+    return values.map(linkName).filter((name) => !!name);
+}
+/** Workloads named by a domain's per-port routes. */
+function routeWorkloads(spec) {
+    const names = [];
+    const ports = Array.isArray(spec.ports) ? spec.ports : [];
+    for (const port of ports) {
+        const routes = port.routes;
+        if (!Array.isArray(routes))
+            continue;
+        for (const route of routes) {
+            const name = linkName(route.workloadLink);
+            if (name)
+                names.push(name);
+        }
+    }
+    return names;
+}
+/** Volume sets a workload's containers mount, from their `cpln://volumeset/…` URIs. */
+function mountedVolumeSets(spec) {
+    const names = [];
+    const containers = Array.isArray(spec.containers) ? spec.containers : [];
+    for (const container of containers) {
+        const volumes = container.volumes;
+        if (!Array.isArray(volumes))
+            continue;
+        for (const volume of volumes) {
+            const uri = volume.uri;
+            if (typeof uri !== "string" || !uri.startsWith("cpln://volumeset/"))
+                continue;
+            names.push(uri.slice("cpln://volumeset/".length));
+        }
+    }
+    return names;
+}
+/** A one-word status for a live resource. */
+function statusOf(live) {
+    const health = live.health;
+    if (health && typeof health === "object") {
+        const readiness = health.readiness;
+        if (typeof readiness === "string" && readiness.length > 0)
+            return readiness;
+    }
+    const status = live.status;
+    if (status && typeof status === "object") {
+        const ready = status.ready;
+        if (typeof ready === "boolean")
+            return ready ? "ready" : "not-ready";
+    }
+    return "active";
+}