@intentius/chant-lexicon-k8s 0.124.31 → 0.124.33

package/dist/deep-observe-hooks.js

@@ -0,0 +1,306 @@
+/**
+ * The k8s lexicon's *static* deep-observation noise rules (#1076, epic #1073).
+ *
+ * Split out from `./deep-observe.ts` for one reason: this file must be safe
+ * to import from `plugin.ts` at module load time, because
+ * `LexiconPlugin.deepNormalizationHooks` is plain data core reads to
+ * normalize the *declared* tree — the half of the contract that runs whether
+ * or not a cluster is ever touched (`lifecycle diff` without `--live`,
+ * `chant build`, tests that only exercise normalization). `./deep-observe.ts`
+ * itself imports `@intentius/chant-k8s-client` for the live read, and chant
+ * #1074 made that package's reachability from the build path a structural
+ * property (`examples/k8s-client-boundary.test.ts`) rather than a lint rule —
+ * so nothing this file exports may pull that package in, directly or
+ * transitively. It imports the core contract's own types, and one generated
+ * JSON data file (`./generated/list-map-keys.json`, chant #1441) — data, not a
+ * package, so the boundary property is unchanged.
+ *
+ * What lives here is deliberately the *entityType-keyed, resource-agnostic*
+ * half of the rules: which fields the API server always populates regardless
+ * of what a manager wrote (`status`, `metadata.uid`, …), which fields
+ * Kubernetes defaults when a manifest is silent about them, and which arrays
+ * are sets addressed by a well-known identity (containers by name, ports by
+ * containerPort+protocol). None of that needs a live object in hand.
+ *
+ * What does *not* live here is the managed-fields ownership walk — which
+ * manager owns one specific field on one specific live object. That is
+ * inherently per-object (it depends on *that* object's
+ * `metadata.managedFields`, which the declared tree never carries and which
+ * differs between two Deployments of the same type), so it cannot be
+ * expressed as a fixed rule keyed only by entity type and path — the shape
+ * every other hook in this file takes. `./deep-observe.ts` computes it once
+ * per resource and attaches it to the observation as `fieldOwners`. Since
+ * chant #1191 ownership no longer prunes anything: a foreign-owned field
+ * nobody declared is reported as `undeclared` drift, and the only static
+ * subtraction for foreign writes is `K8S_SYSTEM_METADATA_PRUNE_PATTERNS`
+ * (core's `managed-fields`), applied below.
+ *
+ * The *entity-type-agnostic* half of these rules — which fields every
+ * Kubernetes API object carries regardless of kind, and the well-known
+ * list-map-key ordering conventions (containers/env/volumes/ports) — lives in
+ * `@intentius/chant/managed-fields` (chant #1087), because a GCP Config
+ * Connector custom resource is a Kubernetes object too and needs the exact
+ * same rules without depending on this lexicon's package. What stays here is
+ * only what's genuinely k8s-*lexicon*-specific: {@link K8S_SERVICE_DEFAULTS},
+ * keyed by chant's own k8s entityType catalog.
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS, K8S_SYSTEM_METADATA_PRUNE_PATTERNS, k8sListMapOrderKey, } from "@intentius/chant/managed-fields";
+import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { GENERATED_ONCE_LABEL_KEY } from "./secret-labels.js";
+/**
+ * Kubernetes-defaulted fields, per entity type, as index-erased property
+ * paths. Subtracted only where source never declared the property
+ * (`side === "live" && counterpart === "absent"`) — cdk-real-drift's default
+ * subtraction, same convention as the AWS and Azure tables
+ * (`AWS_SERVICE_DEFAULTS`, `AZURE_SERVICE_DEFAULTS`).
+ *
+ * Sparse and evidence-based rather than derived from the generated schema:
+ * the k8s OpenAPI spec this lexicon's codegen consumes
+ * (`lexicons/k8s/src/spec/parse.ts`) does not carry a `default` value for
+ * these fields the way ARM's schema sometimes does, so "per discovery" is not
+ * actually expressible today. Widening this table is additive and needs no
+ * contract change.
+ *
+ * `spec.strategy` is listed whole rather than as `spec.strategy.type`, because
+ * pruning only the leaf would still recurse into the object, and a nested default the
+ * table does not separately name (`rollingUpdate.maxSurge`/`maxUnavailable`,
+ * both `"25%"` when `spec.strategy` is omitted entirely) would leave behind an
+ * empty `strategy: {}` — a value distinct from no `strategy` key at all, and
+ * itself a spurious "undeclared" finding. Matching the whole node first, before
+ * its children are ever visited, drops the wrapper outright when every field
+ * under it is exactly at its default.
+ */
+export const K8S_SERVICE_DEFAULTS = {
+    "K8s::Apps::Deployment": {
+        "spec.strategy": { type: "RollingUpdate", rollingUpdate: { maxSurge: "25%", maxUnavailable: "25%" } },
+        "spec.revisionHistoryLimit": 10,
+        "spec.progressDeadlineSeconds": 600,
+        "spec.template.spec.dnsPolicy": "ClusterFirst",
+        "spec.template.spec.restartPolicy": "Always",
+        "spec.template.spec.terminationGracePeriodSeconds": 30,
+        "spec.template.spec.schedulerName": "default-scheduler",
+        // Widened on the CC canonical estate (#1214): a container declaring an
+        // httpGet probe, a named port, or nothing about termination gets exactly
+        // these from the API server. SSA attributes a server-defaulted field to no
+        // manager, so the managed-fields prune deliberately leaves them diffable
+        // (see ./deep-observe.ts) — this table is where they subtract.
+        "spec.template.spec.containers[].livenessProbe.failureThreshold": 3,
+        "spec.template.spec.containers[].livenessProbe.periodSeconds": 10,
+        "spec.template.spec.containers[].livenessProbe.successThreshold": 1,
+        "spec.template.spec.containers[].livenessProbe.timeoutSeconds": 1,
+        "spec.template.spec.containers[].livenessProbe.httpGet.scheme": "HTTP",
+        "spec.template.spec.containers[].readinessProbe.failureThreshold": 3,
+        "spec.template.spec.containers[].readinessProbe.periodSeconds": 10,
+        "spec.template.spec.containers[].readinessProbe.successThreshold": 1,
+        "spec.template.spec.containers[].readinessProbe.timeoutSeconds": 1,
+        "spec.template.spec.containers[].readinessProbe.httpGet.scheme": "HTTP",
+        "spec.template.spec.containers[].ports[].protocol": "TCP",
+        "spec.template.spec.containers[].terminationMessagePath": "/dev/termination-log",
+        "spec.template.spec.containers[].terminationMessagePolicy": "File",
+        "spec.template.spec.securityContext": {},
+    },
+    "K8s::Core::Service": {
+        "spec.sessionAffinity": "None",
+        "spec.type": "ClusterIP",
+        "spec.internalTrafficPolicy": "Cluster",
+        "spec.ipFamilyPolicy": "SingleStack",
+        "spec.ports[].protocol": "TCP",
+    },
+    "K8s::Core::Secret": {
+        // The API server defaults an untyped Secret to Opaque (#1830).
+        "type": "Opaque",
+    },
+};
+/**
+ * Server-ASSIGNED fields — populated by the API server with a value that
+ * varies per object (an allocated ClusterIP, the resolved IP family list), so
+ * unlike {@link K8S_SERVICE_DEFAULTS} there is no fixed value to compare
+ * against. Counterpart-gated like the defaults table: a declared `clusterIP`
+ * is still compared, only the purely server-filled appearance is noise.
+ */
+export const K8S_SERVER_ASSIGNED_PATTERNS = {
+    "K8s::Core::Service": new Set(["spec.clusterIP", "spec.clusterIPs", "spec.ipFamilies"]),
+};
+/**
+ * chant's own ownership marker, as label paths (#1214 — the k8s edition of
+ * azure's #1213 rule). The build stamps `app.kubernetes.io/managed-by` +
+ * `chant.intentius.io/{stack,env}` into every manifest it emits, so a managed
+ * object always carries them live while the declared *source* the diff
+ * compares does not — chant reading its own signature back as drift. The
+ * managed-fields prune cannot subtract them: they are in the applied config,
+ * so chant's field manager owns them, and chant-owned is always diffable.
+ * Counterpart-gated at the call site; managed-by is additionally gated on the
+ * value `"chant"`, so `managed-by: helm` appearing out of band still surfaces.
+ */
+const K8S_OWNERSHIP_LABEL_PATTERNS = new Set([
+    `metadata.labels.${LABEL_OWNERSHIP_KEYS.stack}`,
+    `metadata.labels.${LABEL_OWNERSHIP_KEYS.env}`,
+    // The generated-once marker (#1830) is stamped by the secret store at
+    // mint time, never by a serializer — chant's own signature, not drift.
+    `metadata.labels.${GENERATED_ONCE_LABEL_KEY}`,
+]);
+const K8S_MANAGED_BY_LABEL_PATTERN = `metadata.labels.${LABEL_OWNERSHIP_KEYS.managedBy}`;
+/** Stable JSON with sorted keys — the fallback ordering key for a set-like array without a natural identity field. */
+function canonicalJson(value) {
+    return (JSON.stringify(value, (_k, v) => v && typeof v === "object" && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : v) ?? "");
+}
+let cachedListMapKeys;
+/**
+ * Where the generated table lives: next to this module, resolved from
+ * `import.meta.url`. This module ships as ESM (tsx strips types from src/
+ * directly), where a bare `require` is not defined — the #1441 regression
+ * crashed `lifecycle diff --live` with `require is not defined` on every
+ * estate with a Deployment, and azure's apiVersion registry hit the same
+ * class of bug in #1581. A plain fs read has no module-system dependency.
+ */
+export function listMapKeyTablePath() {
+    return join(moduleSourceDir(import.meta.url), "generated", "list-map-keys.json");
+}
+/**
+ * Load the spec-derived table once. A missing or unreadable file degrades to
+ * an EMPTY table, which routes every list through `k8sListMapOrderKey`'s
+ * hand-written conventions — the same fallback an unlisted property already
+ * takes. The empty table is cached by the caller too, so an absent artifact
+ * costs one failed read and one warning, not one per array element
+ * (chant #1476).
+ *
+ * Degrading is the right call here, unlike azure's apiVersion registry
+ * (#1581) where a silent fallback bypasses correctness-bearing pins. Without
+ * the table, drift detection narrows back to the six hardcoded properties:
+ * less coverage, never wrong answers. The warning names the regen command so
+ * the narrowing is not silent.
+ */
+export function loadListMapKeyTable(path = listMapKeyTablePath()) {
+    if (!existsSync(path)) {
+        warnMissingTable(path, "not found");
+        return {};
+    }
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        warnMissingTable(path, `unreadable: ${err instanceof Error ? err.message : String(err)}`);
+        return {};
+    }
+}
+function warnMissingTable(path, reason) {
+    console.warn(`k8s: list-map-keys table ${reason} (${path}); list identity falls back to the ` +
+        "hand-written conventions in @intentius/chant/managed-fields. Run `npm run generate` " +
+        "in lexicons/k8s (dev checkout) or reinstall @intentius/chant-lexicon-k8s.");
+}
+function listMapKeyTable() {
+    cachedListMapKeys ?? (cachedListMapKeys = loadListMapKeyTable());
+    return cachedListMapKeys;
+}
+/** Test hook: replace (or drop) the cached table so the next lookup reloads it. */
+export function resetListMapKeyTableCache(table) {
+    cachedListMapKeys = table;
+}
+/** Last dotted segment of an index-erased path: `spec.template.spec.containers` → `containers`. */
+function lastSegment(pattern) {
+    const at = pattern.lastIndexOf(".");
+    return at === -1 ? pattern : pattern.slice(at + 1);
+}
+/**
+ * Render one key field's value into a sort key fragment. Numbers are
+ * zero-padded so the key orders numerically rather than lexicographically —
+ * `"443"` would otherwise sort before `"80"`. Cosmetic, since either order
+ * canonicalizes the two sides identically, but a human-sensible order is free
+ * to have here (the same reasoning `k8sListMapOrderKey` applies to ports).
+ */
+function keyFragment(value) {
+    if (typeof value === "number")
+        return String(value).padStart(5, "0");
+    return typeof value === "string" ? value : canonicalJson(value);
+}
+/**
+ * Join a key set's values the way `k8sListMapOrderKey` already does: the bare
+ * values, `/`-separated, with no field names.
+ *
+ * This is not only a sort key. Core renders it as the element's ADDRESS in
+ * drift output — `spec.template.spec.containers[#app].image` — so the format
+ * is user-visible and load-bearing. Emitting `name=app` here would rewrite
+ * every existing drift path. Bare values keep the six properties that were
+ * hardcoded byte-identical, and extend to the rest for free: a container port
+ * reads `[#08080/TCP]` exactly as before, a condition reads `[#Ready]`.
+ */
+function joinKeyValues(el, keys) {
+    return keys.map((k) => keyFragment(el[k])).join("/");
+}
+/**
+ * Order an associative list's element by the identity the SPEC declares for it
+ * (chant #1441), falling back to `@intentius/chant/managed-fields`'s hand-written
+ * conventions for anything the generated table does not cover.
+ *
+ * The fallback is not vestigial. The table is built from the properties this
+ * lexicon's codegen parsed, so it covers core Kubernetes and any CRD that
+ * declares the extensions — but a CRD that declares an associative list
+ * WITHOUT `x-kubernetes-list-map-keys`, or a Config Connector resource read
+ * through GCP's hooks, still lands on the by-name conventions. Keeping both
+ * means widening the spec-derived table can never narrow what was already
+ * identified.
+ */
+export function schemaListMapOrderKey(element) {
+    const candidates = listMapKeyTable()[lastSegment(element.pattern)];
+    const el = element.element;
+    if (candidates && isRecordLike(el)) {
+        for (const keys of candidates) {
+            if (!keys.every((k) => el[k] !== undefined))
+                continue;
+            return joinKeyValues(el, keys);
+        }
+    }
+    return k8sListMapOrderKey(element);
+}
+function isRecordLike(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The paths on a `K8s::Core::Secret` whose values are secret material —
+ * `data.<key>` (live and declared base64) and `stringData.<key>` (declared
+ * plaintext). Masked on BOTH sides by core's normalization pass, so presence
+ * and key names still classify as drift while no value (or value-derived
+ * comparison) ever reaches a diff row — #1365 decision 6, the contract #1830's
+ * generated-once secrets rely on. Key-name masking alone cannot do this:
+ * Secret keys are arbitrary (`app.conf`), not name-shaped.
+ */
+const K8S_SECRET_ENTITY_TYPE = "K8s::Core::Secret";
+const K8S_SECRET_VALUE_PATTERN = /^(?:data|stringData)\./;
+export const k8sDeepNormalizationHooks = {
+    mask(node) {
+        return node.entityType === K8S_SECRET_ENTITY_TYPE && K8S_SECRET_VALUE_PATTERN.test(node.pattern);
+    },
+    prune(node) {
+        if (K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS.has(node.pattern))
+            return true;
+        if (node.side !== "live" || node.counterpart !== "absent")
+            return false;
+        // What Kubernetes' own controllers stamp on every object of a kind
+        // (rollout counters, selector hashes, client-side-apply bookkeeping) is
+        // not drift. This is the static allowlist that stands in for the
+        // managed-fields prune since #1191: any *other* foreign-owned field
+        // nobody declared — a `kubectl label` from the console — now reaches the
+        // diff and reports as `undeclared`, with the accepted baseline as the
+        // valve for the ones an estate has decided to live with.
+        if (K8S_SYSTEM_METADATA_PRUNE_PATTERNS.has(node.pattern))
+            return true;
+        // chant's own ownership marker is not drift (see the sets' docs).
+        if (K8S_OWNERSHIP_LABEL_PATTERNS.has(node.pattern))
+            return true;
+        if (node.pattern === K8S_MANAGED_BY_LABEL_PATTERN && node.value === OWNERSHIP_MANAGED_BY_VALUE)
+            return true;
+        // A server-assigned value nobody declared is allocation, not drift.
+        if (K8S_SERVER_ASSIGNED_PATTERNS[node.entityType]?.has(node.pattern))
+            return true;
+        const defaults = K8S_SERVICE_DEFAULTS[node.entityType];
+        if (!defaults || !Object.prototype.hasOwnProperty.call(defaults, node.pattern))
+            return false;
+        return canonicalJson(defaults[node.pattern]) === canonicalJson(node.value);
+    },
+    orderKey: schemaListMapOrderKey,
+};

package/dist/deep-observe.js

@@ -0,0 +1,234 @@
+/**
+ * Kubernetes deep observation (#1076) — the k8s row of the deep-observe
+ * contract (#1014), and the epic's (#1073) thesis made real: chant compiled
+ * the manifest, so it knows which fields it authored; the API server records,
+ * per field, which manager last wrote it (`metadata.managedFields`, chant
+ * #1075/#1178). Intersecting those two makes Kubernetes drift *derived*
+ * rather than the hand-maintained `ignoreDifferences` list every Argo user
+ * keeps.
+ *
+ * ## What managedFields decides, and what it does not
+ *
+ * The AWS and Azure rows both prune by a **static, entityType-keyed** table
+ * (`AWS_SERVICE_DEFAULTS`, `AZURE_SERVICE_DEFAULTS`): an ARN always looks like
+ * an ARN, `provisioningState` is always server-populated. Neither needs the
+ * specific live object in hand — it is exactly
+ * what `./deep-observe-hooks.ts`'s `k8sDeepNormalizationHooks` is, and it
+ * covers Kubernetes' *equivalent* static noise (`status`,
+ * `metadata.{uid,resourceVersion,generation,creationTimestamp}`, a handful of
+ * server-defaulted pod-spec fields, and the annotations and labels
+ * Kubernetes' own controllers stamp on every object of a kind —
+ * `K8S_SYSTEM_METADATA_PRUNE_PATTERNS` in `@intentius/chant/managed-fields`).
+ *
+ * managedFields is a different kind of fact. Which manager owns
+ * `spec.replicas` on *this* Deployment differs between two Deployments of
+ * the same type, and the declared tree never carries it at all (chant's
+ * source has no `managedFields` key to normalize). It has to be resolved once
+ * per resource, here, against the object in hand.
+ *
+ * Until chant #1191 that resolution *pruned*: a foreign-owned path nobody
+ * declared was dropped before the tree reached core, on the theory that it
+ * was controller noise. It silenced exactly the case the deep read exists
+ * for — `kubectl label deploy web team=platform` is foreign-owned
+ * (`kubectl-edit`) and undeclared, and never appeared in fieldDrift. The
+ * policy now (recorded on #1202, refined by #2160) is:
+ *
+ * 1. **Chant-owned** (`chant`, `chant:<stack>` — chant #1075, matched on the
+ *    family so a stack rename does not stop recognizing its own history) is
+ *    always diffable.
+ * 2. **Declared, whoever owns it live** (a contested field) is always
+ *    diffable: chant's source is a statement of intent independent of which
+ *    write currently holds the field, and a foreign write that overrides a
+ *    value chant's manifest asks for is the thing `lifecycle diff --live`
+ *    exists to surface. It reports as `changed`.
+ * 3. **Undeclared** — a path outside the declaration's claimed-field set
+ *    (`@intentius/chant/claimed-fields`) — is reported as unclaimed and
+ *    is not drift at all. Before #2160 it was `undeclared` drift that the
+ *    accepted baseline had to absorb one path at a time; the declaration
+ *    answers on the first read instead, so an HPA that owns `spec.replicas`
+ *    on a Deployment whose source is silent about replicas is quiet with
+ *    nothing recorded anywhere.
+ *
+ * So ownership decides nothing about *whether* a path is compared, and since
+ * #2160 it no longer decides the verdict either — the declaration does. What
+ * it contributes is `fieldOwners` (#1189), and that is worth more here than
+ * anywhere else: on every other substrate a held field can only be reported
+ * as "not chant's", while here it is reported as `hpa-controller`'s or
+ * `kubectl-edit`'s by name, which is the difference between a controller
+ * doing its job and somebody bypassing the pipeline. Core takes the manager
+ * where this reader supplies one and falls back to the claim where it does
+ * not (a path inside a key-addressed list, which no `fieldsV1` entry names in
+ * that form). The only fields subtracted because a foreign manager wrote them
+ * are the well-known system ones on the static allowlist.
+ *
+ * ## Resolving a managedFields entry against a live array
+ *
+ * `metadata.managedFields[].fieldsV1` encodes a list item three ways —
+ * `k:{"name":"web"}` (by key), `v:"blue"` (by value), `i:3` (by index) — and
+ * chant #1178's `managed-fields.ts` renders all three to a path *string*
+ * (`.spec.containers[name="web"]`) for display. Parsing that string back
+ * would be ambiguous in general (a label key may itself contain `.`, e.g.
+ * `app.kubernetes.io/name`, indistinguishable in the rendered form from
+ * nested fields), so this reader does not parse strings at all: it walks the
+ * *structured* `fieldsV1` tree directly (`walkOwnership`, below), matching
+ * each `k:`/`v:` entry against the actual live array to find the concrete
+ * index, and against the actual declared array (by the same key or value) to
+ * answer question 3 for that element specifically — a declared container
+ * named `app` at index 0 is still "declared" if a sidecar gets injected in
+ * front of it and shifts it to live index 1.
+ *
+ * ## What is deliberately not modeled
+ *
+ * A manager's `.` entry (SSA's "I own this element's presence") on a
+ * container that also sets no scalar sub-fields (unusual — a real apply
+ * setting a container almost always sets `image`/`name` too) would not confer
+ * ownership onto a sibling field nobody's `fieldsV1` entry lists explicitly.
+ * A path absent from every manager's fields simply has no `owner` on its
+ * drift line; it is compared like any other.
+ *
+ * ## `buildOwnershipSets` lives in core now
+ *
+ * The ownership walk itself (`walkOwnership`, resolving a `fieldsV1` tree
+ * against the live and declared trees) has nothing k8s-*lexicon*-specific
+ * about it — it is generic Kubernetes SSA machinery. Chant #1087 (GCP's row,
+ * reusing this one, since a Config Connector CR is a Kubernetes object too)
+ * moved it to `@intentius/chant/managed-fields` rather than have gcp depend
+ * on this lexicon's package, the same reason chant #1100's
+ * `resolveClusterTarget` lives in core. This module re-exports
+ * `buildOwnershipSets`/`OwnershipSets` from there so nothing here changes for
+ * an existing importer of this file.
+ */
+import { deepObservation, normalizeDeepProperties } from "@intentius/chant/deep-observation";
+import { unobservedAll } from "@intentius/chant/observation";
+import { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { buildOwnershipSets } from "@intentius/chant/managed-fields";
+import { defaultK8sConnector } from "./api/connect.js";
+import { classifyApiFailure, isMissingClientPackage, isWholeLexiconFailure, MISSING_CLIENT_DETAIL, } from "./api/classify.js";
+import { operationFor } from "./api/operation-surface.js";
+import { k8sDeepNormalizationHooks } from "./deep-observe-hooks.js";
+import { observeReceiptRowsDeep, receiptRowsFor } from "./receipt-store.js";
+// Re-exported so a dynamic importer of this module (plugin.ts's
+// `observeResourcesDeep`, a test) can get the reader and its hooks from one
+// place, the same shape the AWS and Azure deep-observe.ts modules offer.
+// `plugin.ts`'s own `deepNormalizationHooks` field imports the hooks
+// separately, directly from `./deep-observe-hooks` — that file has no
+// dependency on `@intentius/chant-k8s-client`, so it is safe to import
+// statically; this module is not (see the module doc).
+export { k8sDeepNormalizationHooks, buildOwnershipSets };
+/** The live object minus the envelope fields that live outside `properties` on {@link DeepResourceObservation} (mirrors `type`/`physicalId`). */
+function propertiesTreeOf(obj) {
+    const { apiVersion: _apiVersion, kind: _kind, ...rest } = obj;
+    return rest;
+}
+/**
+ * Read the live property tree for each declared entity, pruning by
+ * `metadata.managedFields` (see the module doc). Reuses the same connector,
+ * discovery/caching client and tri-state failure classification as the thin
+ * read (`./describe-resources.ts`) — the binding check (chant #1100/#1155)
+ * still refuses before any resource is touched, and a connect failure still
+ * becomes NOT-OBSERVED for every declared entity rather than an empty result.
+ */
+export async function observeResourcesDeepK8s(options, connect = defaultK8sConnector) {
+    const { managedFieldsOf, isChantFieldManager } = await import("@intentius/chant-k8s-client");
+    // Effect receipts (#2074) are read by their own leg at the end: they carry
+    // no declared props, so every live path would be an unclaimed field (#2160)
+    // and their staleness is an `effect` row from the plan (#1832), never
+    // property drift. Reading them here keeps the deep read from calling a
+    // declared entity a hole; contributing an empty tree keeps it from calling
+    // one drift.
+    const receiptRows = receiptRowsFor(options.entityNames, options.buildOutput);
+    const declared = [...options.entities]
+        .filter(([entityName]) => !receiptRows.has(entityName))
+        .map(([entityName, entity]) => ({
+        entityName,
+        entityType: entity.entityType,
+        props: entity.props,
+    }));
+    const everyName = [...declared.map((d) => d.entityName), ...receiptRows.keys()];
+    let client;
+    try {
+        ({ client } = await connect({ environment: options.environment, cwd: options.cwd }));
+    }
+    catch (err) {
+        if (isMissingClientPackage(err)) {
+            return deepObservation({}, unobservedAll(everyName, "read-failed", MISSING_CLIENT_DETAIL, options.entities));
+        }
+        if (isWholeLexiconFailure(err)) {
+            const outcome = classifyApiFailure(err);
+            return deepObservation({}, unobservedAll(everyName, outcome.kind === "unobserved" ? outcome.reason : "read-failed", outcome.kind === "unobserved" ? outcome.detail : undefined, options.entities));
+        }
+        // A cluster-binding mismatch (chant #1100) — refuse loudly, same as the
+        // thin path; core turns the throw into NOT-OBSERVED for every entity.
+        throw err;
+    }
+    const resources = {};
+    const unobserved = {};
+    await client.concurrently(declared, async ({ entityName, entityType, props }) => {
+        const operation = operationFor(entityType);
+        if (!operation) {
+            unobserved[entityName] = {
+                type: entityType,
+                reason: "unsupported-kind",
+                detail: `no generated operation surface for ${entityType} — run \`chant generate\` in the k8s lexicon, or declare the CRD as a codegen source`,
+            };
+            return;
+        }
+        const metadata = props.metadata;
+        const name = metadata?.name;
+        if (!name) {
+            unobserved[entityName] = {
+                type: entityType,
+                reason: "read-failed",
+                detail: "declared entity has no metadata.name to query by",
+            };
+            return;
+        }
+        try {
+            const obj = await client.read({
+                apiVersion: operation.apiVersion,
+                kind: operation.kind,
+                name,
+                ...(metadata?.namespace ? { namespace: metadata.namespace } : {}),
+            });
+            if (options.owned && !hasOwnershipMarker(obj.metadata?.labels, LABEL_OWNERSHIP_KEYS)) {
+                unobserved[entityName] = {
+                    type: entityType,
+                    reason: "filtered",
+                    detail: "live object carries no chant ownership marker and --owned was requested",
+                };
+                return;
+            }
+            const liveRoot = propertiesTreeOf(obj);
+            const sets = buildOwnershipSets(managedFieldsOf(obj), liveRoot, props, isChantFieldManager);
+            resources[entityName] = {
+                type: entityType,
+                physicalId: obj.metadata?.uid,
+                properties: normalizeDeepProperties(liveRoot, {
+                    entityType,
+                    side: "live",
+                    hooks: k8sDeepNormalizationHooks,
+                }),
+                // Who owns each path (#1189). Nothing is pruned by ownership any more
+                // (#1191), so a foreign-owned undeclared field still reaches the diff
+                // — as a held field since #2160 — and naming the manager is the whole
+                // question there: an operator needs to tell `hpa-controller` doing its
+                // job from somebody running `kubectl edit`.
+                ...(sets.owners.size > 0 ? { fieldOwners: Object.fromEntries(sets.owners) } : {}),
+            };
+        }
+        catch (err) {
+            const outcome = classifyApiFailure(err);
+            if (outcome.kind === "unobserved") {
+                unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+            }
+            // `absent` records nothing — the thin read already reports the
+            // non-existence; restating it here would turn one finding into two.
+        }
+    });
+    if (receiptRows.size > 0) {
+        const receiptObs = await observeReceiptRowsDeep(client, receiptRows);
+        Object.assign(resources, receiptObs.resources);
+        Object.assign(unobserved, receiptObs.unobserved);
+    }
+    return deepObservation(resources, unobserved);
+}

package/dist/default-labels.js

@@ -0,0 +1,87 @@
+/**
+ * Default Labels & Annotations — declares project-wide labels/annotations
+ * for all Kubernetes resources.
+ *
+ * When a project exports a `defaultLabels(...)` or `defaultAnnotations(...)`
+ * declaration, the serializer automatically injects them into every resource's
+ * metadata at synthesis time. Explicit labels/annotations on individual
+ * resources take precedence.
+ */
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+/**
+ * Marker symbol for default labels identification.
+ */
+export const DEFAULT_LABELS_MARKER = Symbol.for("chant.k8s.defaultLabels");
+/**
+ * Marker symbol for default annotations identification.
+ */
+export const DEFAULT_ANNOTATIONS_MARKER = Symbol.for("chant.k8s.defaultAnnotations");
+/**
+ * Type guard for DefaultLabels.
+ */
+export function isDefaultLabels(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        DEFAULT_LABELS_MARKER in value &&
+        value[DEFAULT_LABELS_MARKER] === true);
+}
+/**
+ * Type guard for DefaultAnnotations.
+ */
+export function isDefaultAnnotations(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        DEFAULT_ANNOTATIONS_MARKER in value &&
+        value[DEFAULT_ANNOTATIONS_MARKER] === true);
+}
+/**
+ * Declare project-wide default labels for all Kubernetes resources.
+ *
+ * Labels are injected at synthesis time into every resource's
+ * `metadata.labels`. If a resource has an explicit label with the
+ * same key, the explicit value wins.
+ *
+ * @example
+ * ```ts
+ * import { defaultLabels } from "@intentius/chant-lexicon-k8s";
+ *
+ * export const labels = defaultLabels({
+ *   "app.kubernetes.io/managed-by": "chant",
+ *   "app.kubernetes.io/part-of": "my-app",
+ * });
+ * ```
+ */
+export function defaultLabels(labels) {
+    return {
+        [DEFAULT_LABELS_MARKER]: true,
+        [DECLARABLE_MARKER]: true,
+        lexicon: "k8s",
+        entityType: "chant:k8s:defaultLabels",
+        labels,
+    };
+}
+/**
+ * Declare project-wide default annotations for all Kubernetes resources.
+ *
+ * Annotations are injected at synthesis time into every resource's
+ * `metadata.annotations`. If a resource has an explicit annotation with
+ * the same key, the explicit value wins.
+ *
+ * @example
+ * ```ts
+ * import { defaultAnnotations } from "@intentius/chant-lexicon-k8s";
+ *
+ * export const annotations = defaultAnnotations({
+ *   "app.kubernetes.io/managed-by": "chant",
+ * });
+ * ```
+ */
+export function defaultAnnotations(annotations) {
+    return {
+        [DEFAULT_ANNOTATIONS_MARKER]: true,
+        [DECLARABLE_MARKER]: true,
+        lexicon: "k8s",
+        entityType: "chant:k8s:defaultAnnotations",
+        annotations,
+    };
+}