@intentius/chant-lexicon-gcp 0.30.0 → 0.32.0

package/dist/deep-observe-hooks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The gcp lexicon's *static* deep-observation noise rules (#1087, epic #1073).
+ *
+ * Split out from `./deep-observe.ts` for the same reason chant #1076 split
+ * the k8s lexicon's rules into `lexicons/k8s/src/deep-observe-hooks.ts`: 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`
+ * imports `./describe-resources.ts` for the live kubectl transport, which
+ * pulls in `node:child_process`; nothing this file exports may pull that in,
+ * directly or transitively, so `chant build` never resolves a process-
+ * spawning module just to normalize a declared tree.
+ *
+ * What lives here is entirely reused from `@intentius/chant/managed-fields`
+ * (chant #1087's module doc explains why that lives in core rather than the
+ * k8s lexicon) plus GCP/Config-Connector-specific annotation noise. Nothing
+ * here needs a live object in hand — the per-resource managed-fields prune
+ * (which does) is computed in `./deep-observe.ts` and layered on top.
+ */
+import type { DeepNormalizationHooks } from "@intentius/chant/lexicon";
+/**
+ * GCP's static deep-observation noise rules — the entity-agnostic half,
+ * applied to the *declared* tree by core (`gcpPlugin.deepNormalizationHooks`)
+ * exactly like the other three rows, and layered under the per-resource
+ * managed-fields prune in `./deep-observe.ts` for the live tree.
+ *
+ * A Config Connector custom resource *is* a Kubernetes object (see
+ * `./deep-observe.ts`'s module doc), so the generic envelope
+ * (`K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS`) and Kubernetes' own list-map-key
+ * ordering conventions (`k8sListMapOrderKey` — needed because some CNRM kinds
+ * embed genuinely k8s-shaped substructures, e.g. Cloud Run's `RunService`)
+ * are reused verbatim from `@intentius/chant/managed-fields` rather than
+ * restated. The one GCP-specific rule is CNRM's own observed-state
+ * annotation noise.
+ */
+export declare const gcpDeepNormalizationHooks: DeepNormalizationHooks;
+//# sourceMappingURL=deep-observe-hooks.d.ts.map

package/dist/deep-observe-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-observe-hooks.d.ts","sourceRoot":"","sources":["../src/deep-observe-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAY,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAmCjF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,EAAE,sBAMvC,CAAC"}

package/dist/deep-observe.d.ts

@@ -0,0 +1,141 @@
+/**
+ * GCP deep observation (#1087) — the GCP row of the deep-observe contract
+ * (#1014), reusing the k8s row (#1076) rather than writing a second one, per
+ * the issue and #1173's own per-row checklist: "A Config Connector resource
+ * *is* a Kubernetes object, so it carries managed-fields for the same
+ * reason. Share the hooks rather than writing a second implementation."
+ *
+ * ## A Config Connector CR is a Kubernetes object
+ *
+ * `kubectl get <kind>.<group> -o json` against a Config Connector-enabled
+ * cluster (`./describe-resources.ts`'s own transport, reused here) returns a
+ * real Kubernetes API object: `metadata.managedFields`, `status`,
+ * `metadata.{uid,resourceVersion,generation,creationTimestamp}` are all
+ * present for the identical reason they're present on a Deployment — the API
+ * server that served the read is the same kind of API server. The epic's own
+ * table lists `metadata.managedFields` under GCP's "field noise" to prune; it
+ * is the opposite of noise, and it is available here for exactly the reason
+ * chant #1076 reads it on the k8s row.
+ *
+ * So this reader reuses, unchanged, from `@intentius/chant/managed-fields`:
+ *
+ * - `K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS` — the generic Kubernetes object
+ *   envelope (`status`, `metadata.{uid,resourceVersion,generation,
+ *   creationTimestamp,managedFields,selfLink}`).
+ * - `k8sListMapOrderKey` — Kubernetes' own list-map-key conventions, needed
+ *   because some CNRM kinds embed genuinely k8s-shaped substructures (Cloud
+ *   Run's `RunService` wraps a Knative pod spec with
+ *   `containers`/`env`/`ports`, keyed the same way a Deployment's are).
+ * - `buildOwnershipSets`/`pruneByOwnership` — the managed-fields ownership
+ *   walk itself: chant #1076's actual contribution, and the piece this row
+ *   exists to reuse rather than reimplement.
+ *
+ * These live in core, not in the k8s lexicon, specifically so this file can
+ * reuse them without adding a dependency on the k8s lexicon package or (never,
+ * per the issue) on `@intentius/chant-k8s-client` — this reader shells
+ * `kubectl` exactly like `./describe-resources.ts` already does. Chant
+ * #1177/#1180 kept GCP off the typed client deliberately ("a separate
+ * lexicon and a separate decision"); this row does not revisit that.
+ *
+ * ## The GCP twist: who is "chant" on this path?
+ *
+ * Chant #1076's rule treats a field as always-diffable when *any* chant field
+ * manager (`chant`, `chant:<stack>` — chant #1075's SSA identity) owns it.
+ * That identity is only ever set by the k8s lexicon's typed client, applying
+ * with an explicit `--field-manager`. GCP has no equivalent apply activity:
+ * every gcp example's own deploy script (e.g.
+ * `examples/cockroachdb-multi-region-gke/scripts/deploy.sh`) runs plain
+ * `kubectl apply -f dist/*.yaml` — classic client-side apply, no
+ * `--server-side`, no `--field-manager`. kubectl's own hardcoded default
+ * field manager for that command is `kubectl-client-side-apply`, identical
+ * to what a human's `kubectl apply -f their-own-file.yaml` would record.
+ * **There is no field-manager name on GCP's real deploy path that
+ * distinguishes "chant applied this" from "a person applied this".**
+ * (Config Connector's own controller is distinguishable — its reconciler
+ * records itself as `cnrm-controller-manager`, per the k8s-config-connector
+ * source's own `ControllerManagedFieldManager` constant — just chant isn't,
+ * on this path.)
+ *
+ * That sounds like it breaks question 1 of the three-question rule
+ * (`isChantManager`) below. It doesn't, because question 3 already covers
+ * it: chant's own kubectl apply always applies the *exact* built manifest, so
+ * any field chant's own most recent apply set is, by construction, also in
+ * `declaredRoot` (`props`) on the very next read — chant never authors a
+ * field it does not also declare. Working through what that means per field:
+ *
+ * - A field only chant's own applies have ever touched: not recognized as
+ *   `chantOwned` (its manager is `kubectl-client-side-apply`, not `chant`),
+ *   but foreign-owned *and* declared → contested → kept diffable anyway.
+ *   Same outcome as being chant-owned would have been.
+ * - A field CNRM's controller sets and chant never declares: foreign-owned,
+ *   undeclared → pruned. Correct regardless of whether "chant" is recognized.
+ * - A field a human sets by hand (`kubectl edit`, or their own `kubectl apply
+ *   -f`) that chant *does* declare: foreign-owned (manager is `kubectl-edit`
+ *   or `kubectl-client-side-apply`) and declared → contested → surfaces as
+ *   drift. This is #1087's acceptance criterion 1.
+ *
+ * `isGcpChantFieldManager` below still checks the `chant`/`chant:<stack>`
+ * family, so a future GCP apply path that *does* route through server-side
+ * apply with an explicit chant field manager (matching the k8s lexicon's own
+ * path) is recognized with no change needed here. On today's plain-apply
+ * path it is inert — proven inert by this module's own test suite (the
+ * "managers-specific case") — and the contested-field rule (question 3) is
+ * what actually keeps GCP's drift semantics correct without it.
+ *
+ * ## What's genuinely GCP-specific
+ *
+ * - No typed operation surface (chant #1177's `operationFor` is a k8s
+ *   lexicon/typed-client concept, generated from cluster discovery this
+ *   reader never touches) — `./describe-resources.ts`'s `deriveGVK` stands in.
+ * - CNRM's own observed-state annotations (`./deep-observe-hooks.ts`'s
+ *   `gcpDeepNormalizationHooks`) — bookkeeping the controller writes into
+ *   `metadata.annotations` for GCP-side properties the CRD schema has no
+ *   field for. See that module's doc for why the list is narrow.
+ *
+ * ## Deliberately out of scope
+ *
+ * `status.conditions` staleness as its own signal — the issue's own
+ * "Proposed" section floats this as worth *deciding*, not worth doing here.
+ * `status` is pruned outright (matching k8s, and the acceptance criteria),
+ * and a CNRM projection lagging real GCP state is a genuine gap, but
+ * detecting it means reading the actual GCP API, not the CR — a different
+ * read than this contract's "normalize what Kubernetes reports" scope.
+ * Flagged, not papered over.
+ *
+ * ## The build-path boundary
+ *
+ * This module imports `./describe-resources.ts` for the live kubectl
+ * transport, which imports `node:child_process`. `gcpPlugin.ts` reaches this
+ * file only via `await import("./deep-observe.js")` inside
+ * `observeResourcesDeep` — never statically — the same way it already
+ * dynamic-imports `describeResources`/`exportResources`, so `chant build`
+ * never resolves a process-spawning module just to synthesize a template.
+ * `deepNormalizationHooks` is plain data with no such dependency
+ * (`./deep-observe-hooks.ts`) and is imported statically from `plugin.ts`,
+ * because core normalizes the *declared* tree with it whether or not a
+ * cluster read ever happens.
+ */
+import type { DeepObservationResult } from "@intentius/chant/lexicon";
+import { gcpDeepNormalizationHooks } from "./deep-observe-hooks.js";
+export { gcpDeepNormalizationHooks };
+export interface GcpDeepObserveOptions {
+    environment: string;
+    buildOutput?: string;
+    entityNames: string[];
+    entities: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    stack?: string;
+    owned?: boolean;
+}
+/**
+ * Read the live property tree for each declared entity via `kubectl get
+ * <kind>.<group> -o json`, pruning by `metadata.managedFields` (see the
+ * module doc). Reuses `./describe-resources.ts`'s exact cluster-binding
+ * resolution and kubectl mechanics — the binding check (chant #1100) 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 declare function observeResourcesDeepGcp(options: GcpDeepObserveOptions): Promise<DeepObservationResult>;
+//# sourceMappingURL=deep-observe.d.ts.map

package/dist/deep-observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHG;AAEH,OAAO,KAAK,EAEV,qBAAqB,EAGtB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAMjE,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAErC,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAkDD;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyE5G"}

package/dist/describe-resources.d.ts

@@ -20,8 +20,31 @@
  * `chant.config.ts` (see `lexicons/k8s/src/config.ts`), not a separate
  * `gcp.profiles` key, because it is fundamentally the same kubectl context a
  * project's K8s entities would use against the same cluster.
+ *
+ * `resolveGcpKubectlContext` and `execConfigConnectorGet` below are exported
+ * so `./deep-observe.ts` (chant #1087) shares this exact cluster-binding
+ * resolution and `kubectl get -o json` mechanics rather than restating them —
+ * the two readers differ only in how much of the response each one keeps.
  */
 import type { ObservationResult } from "@intentius/chant/lexicon";
+/**
+ * Resolve this environment's cluster binding once and return the `--context`
+ * argv fragment every subsequent kubectl call should append (empty when
+ * unbound — ambient context, unchanged behavior). Throws on a bound-but-
+ * mismatched context (chant #1100), the same loud refusal both readers rely
+ * on core to turn into NOT-OBSERVED for every declared entity.
+ */
+export declare function resolveGcpKubectlContext(environment: string): Promise<string[]>;
+/**
+ * `kubectl get <kind>.<group> <name> [-n <namespace>] [--context <ctx>] -o
+ * json`, parsed. Throws on any kubectl failure — callers classify it with
+ * `classifyKubectlFailure` exactly like today, so a NotFound and an
+ * auth/connectivity failure are told apart at the call site, not here.
+ */
+export declare function execConfigConnectorGet(gvk: {
+    group: string;
+    kind: string;
+}, name: string, namespace: string | undefined, ctxArg: readonly string[]): Promise<Record<string, unknown>>;
 /**
  * Mirror of `lexicons/gcp/src/serializer.ts:deriveGVKFromType` — keeping the
  * derivation logic local so describeResources can compute the kubectl resource

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,MAAM,0BAA0B,CAAC;AAuBtG;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASpF;AA4BD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8E7B"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,MAAM,0BAA0B,CAAC;AAQtG;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIrF;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMlC;AAiBD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASpF;AA4BD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuE7B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "934b2e465f4a0be499267e8b23f84e1df1353c29eb599046ccb50bc20b3c2bd8",
+    "manifest.json": "364da7aab0d1cf639b4bb9b4da365272cd1e9fbebc1490237c12f0b3570473da",
     "meta.json": "475f10909854d059a2e2d4fb541c058803422e38b9c64bd4d6858c0623eedb8c",
     "types/index.d.ts": "5433b54c04b57d6fda8f3d81ef92ed0aca87f7e8e5dd3ea92d8de6e62a3ccfab",
     "rules/hardcoded-project.ts": "228631d3159e1ffcce2359c66073d4ae59bb0285f378e46e446f416aec50481c",
@@ -37,5 +37,5 @@
     "skills/chant-gcp-patterns.md": "a7ef31c1eb2f7244d3f73952c300472ef94c1eb09bd7a1003281b89299b6b704",
     "skills/chant-gcp-gke.md": "be277019da9a722c851e47cd2dfb9c9536668948c3535fb20db7697e934c4e2b"
   },
-  "composite": "9b0f2abc33da4def1bad8cc078ec2d56039630e59fe397152d17d1a317f80b30"
+  "composite": "ee170703110b77abd20502d2047a75cf91c12c2e70da5203b0e057ff6d4788c7"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gcp",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GCP",
   "intrinsics": [],

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAqC,MAAM,0BAA0B,CAAC;AAoBjG,eAAO,MAAM,SAAS,EAAE,aAuWvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAqC,MAAM,0BAA0B,CAAC;AAqBjG,eAAO,MAAM,SAAS,EAAE,aAuXvB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,7 +76,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.30.0",
+    "@intentius/chant": "^0.32.0",
     "typescript": "^5.9.3"
   }
 }

package/src/deep-observe-hooks.ts

@@ -0,0 +1,79 @@
+/**
+ * The gcp lexicon's *static* deep-observation noise rules (#1087, epic #1073).
+ *
+ * Split out from `./deep-observe.ts` for the same reason chant #1076 split
+ * the k8s lexicon's rules into `lexicons/k8s/src/deep-observe-hooks.ts`: 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`
+ * imports `./describe-resources.ts` for the live kubectl transport, which
+ * pulls in `node:child_process`; nothing this file exports may pull that in,
+ * directly or transitively, so `chant build` never resolves a process-
+ * spawning module just to normalize a declared tree.
+ *
+ * What lives here is entirely reused from `@intentius/chant/managed-fields`
+ * (chant #1087's module doc explains why that lives in core rather than the
+ * k8s lexicon) plus GCP/Config-Connector-specific annotation noise. Nothing
+ * here needs a live object in hand — the per-resource managed-fields prune
+ * (which does) is computed in `./deep-observe.ts` and layered on top.
+ */
+
+import type { DeepNode, DeepNormalizationHooks } from "@intentius/chant/lexicon";
+import { K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS, k8sListMapOrderKey } from "@intentius/chant/managed-fields";
+
+/**
+ * Config Connector's own observed-state annotations — written by
+ * `cnrm-controller-manager` after reconciling, mirroring GCP-side state the
+ * CRD schema has no field for (e.g. secret version pins). Never authored by
+ * a chant manifest, so pruning them unconditionally cannot hide declared
+ * config the way blindly pruning every `cnrm.cloud.google.com/*` annotation
+ * would — several of that family (`state-into-spec`, `deletion-policy`,
+ * `management-conflict-prevention-policy`) are themselves user-authored
+ * configuration, not observed state, and pruning those would hide genuine
+ * drift on them.
+ *
+ * Sparse and evidence-based (Config Connector's own docs), the same posture
+ * every other lexicon's noise table takes. Widening it is additive and needs
+ * no contract change.
+ *
+ * Most CNRM-controller noise doesn't need this list at all — it's already
+ * pruned by the reused managed-fields ownership rule in `./deep-observe.ts`,
+ * since `cnrm-controller-manager` is a foreign, undeclared owner of whatever
+ * it touches. This list only covers the narrow, evidence-based case worth
+ * pruning even were managedFields attribution ever missing for it.
+ */
+const CNRM_OBSERVED_STATE_ANNOTATION_KEYS: ReadonlySet<string> = new Set([
+  "cnrm.cloud.google.com/observed-secret-versions",
+]);
+
+const ANNOTATIONS_PREFIX = "metadata.annotations.";
+
+function isCnrmObservedStateAnnotation(node: DeepNode): boolean {
+  if (!node.pattern.startsWith(ANNOTATIONS_PREFIX)) return false;
+  return CNRM_OBSERVED_STATE_ANNOTATION_KEYS.has(node.pattern.slice(ANNOTATIONS_PREFIX.length));
+}
+
+/**
+ * GCP's static deep-observation noise rules — the entity-agnostic half,
+ * applied to the *declared* tree by core (`gcpPlugin.deepNormalizationHooks`)
+ * exactly like the other three rows, and layered under the per-resource
+ * managed-fields prune in `./deep-observe.ts` for the live tree.
+ *
+ * A Config Connector custom resource *is* a Kubernetes object (see
+ * `./deep-observe.ts`'s module doc), so the generic envelope
+ * (`K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS`) and Kubernetes' own list-map-key
+ * ordering conventions (`k8sListMapOrderKey` — needed because some CNRM kinds
+ * embed genuinely k8s-shaped substructures, e.g. Cloud Run's `RunService`)
+ * are reused verbatim from `@intentius/chant/managed-fields` rather than
+ * restated. The one GCP-specific rule is CNRM's own observed-state
+ * annotation noise.
+ */
+export const gcpDeepNormalizationHooks: DeepNormalizationHooks = {
+  prune(node: DeepNode): boolean {
+    if (K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS.has(node.pattern)) return true;
+    return isCnrmObservedStateAnnotation(node);
+  },
+  orderKey: k8sListMapOrderKey,
+};

package/src/deep-observe.test.ts

@@ -0,0 +1,522 @@
+/**
+ * GCP deep observation (#1087) — the GCP row of the deep-observe contract
+ * (#1014), and the managed-fields reuse from the k8s row (#1076).
+ *
+ * Every case here drives the real reader (`observeResourcesDeepGcp`) with
+ * `node:child_process`'s `exec` mocked — the same harness
+ * `describe-resources.test.ts` uses for the thin read. No ambient kubectl
+ * config is read and no cluster is contacted.
+ *
+ * The end-to-end acceptance test drives `observeResourcesDeepGcp`'s real
+ * output through core's real `diffDeepObservation`, with `gcpPlugin`'s real,
+ * exported `deepNormalizationHooks` — the same three pieces
+ * `lexicons/k8s/src/deep-observe.test.ts` exercises for the k8s row.
+ */
+
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+const execMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    exec: (cmd: string, cb: (err: Error | null, out: { stdout: string; stderr: string }) => void) => {
+      Promise.resolve(execMock(cmd)).then(
+        (out) => cb(null, out),
+        (err) => cb(err as Error, { stdout: "", stderr: "" }),
+      );
+    },
+  };
+});
+
+const loadChantConfigMock = vi.fn();
+vi.mock("@intentius/chant/config", () => ({
+  loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args),
+}));
+
+const { gcpPlugin } = await import("./plugin");
+const { observeResourcesDeepGcp } = await import("./deep-observe");
+const { gcpDeepNormalizationHooks } = await import("./deep-observe-hooks");
+const { diffDeepObservation, observeDeep } = await import("@intentius/chant/lifecycle/deep-observe");
+const { normalizeDeepObservation, normalizeDeepProperties } = await import("@intentius/chant/deep-observation");
+
+type Entity = { name: string; entityType: string; props: Record<string, unknown> };
+function makeEntities(records: Entity[]): Map<string, { entityType: string; props: Record<string, unknown> }> {
+  return new Map(records.map((r) => [r.name, { entityType: r.entityType, props: r.props }]));
+}
+
+/** Route a mocked `kubectl get <resource> <name> ... -o json` command to a canned JSON body, by matching on `<resource> <name>`. */
+function respondTo(bodies: Record<string, unknown>): (cmd: string) => { stdout: string; stderr: string } {
+  return (cmd: string) => {
+    for (const [needle, body] of Object.entries(bodies)) {
+      if (cmd.includes(needle)) return { stdout: JSON.stringify(body), stderr: "" };
+    }
+    throw new Error(`unexpected kubectl invocation: ${cmd}`);
+  };
+}
+
+beforeEach(() => {
+  execMock.mockReset();
+  loadChantConfigMock.mockReset();
+  loadChantConfigMock.mockResolvedValue({ config: {} });
+});
+
+describe("gcpPlugin wiring (#1087)", () => {
+  test("the plugin exposes the deep-observe contract, and the hooks are the shared static instance", () => {
+    expect(typeof gcpPlugin.observeResourcesDeep).toBe("function");
+    expect(gcpPlugin.deepNormalizationHooks).toBe(gcpDeepNormalizationHooks);
+  });
+});
+
+describe("gcpDeepNormalizationHooks — the static rules", () => {
+  test("prunes status and the server-minted metadata fields, reused verbatim from the k8s row", () => {
+    const out = normalizeDeepProperties(
+      {
+        status: { conditions: [{ type: "Ready", status: "True" }] },
+        metadata: {
+          name: "data-bucket",
+          uid: "u-1",
+          resourceVersion: "7",
+          generation: 3,
+          creationTimestamp: "2026-01-01T00:00:00Z",
+          managedFields: [{ manager: "cnrm-controller-manager" }],
+          labels: { app: "web" },
+        },
+      },
+      { entityType: "GCP::Storage::Bucket", side: "live", hooks: gcpDeepNormalizationHooks },
+    );
+    expect(out).toEqual({ metadata: { name: "data-bucket", labels: { app: "web" } } });
+  });
+
+  test("prunes Config Connector's own observed-state annotation, but not a user-authored cnrm.cloud.google.com annotation", () => {
+    const out = normalizeDeepProperties(
+      {
+        metadata: {
+          annotations: {
+            "cnrm.cloud.google.com/observed-secret-versions": '{"db-password":"1"}',
+            "cnrm.cloud.google.com/deletion-policy": "abandon",
+          },
+        },
+      },
+      { entityType: "GCP::Storage::Bucket", side: "live", hooks: gcpDeepNormalizationHooks },
+    );
+    expect(out).toEqual({ metadata: { annotations: { "cnrm.cloud.google.com/deletion-policy": "abandon" } } });
+  });
+
+  test("orders containers by name — reused for CNRM kinds embedding a k8s-shaped pod spec (e.g. Cloud Run's RunService)", () => {
+    const out = normalizeDeepProperties(
+      { spec: { template: { spec: { containers: [{ name: "sidecar" }, { name: "app" }] } } } },
+      { entityType: "GCP::Run::Service", side: "live", hooks: gcpDeepNormalizationHooks },
+    );
+    expect(
+      (out.spec as { template: { spec: { containers: Array<{ name: string }> } } }).template.spec.containers.map((c) => c.name),
+    ).toEqual(["app", "sidecar"]);
+  });
+});
+
+describe("observeResourcesDeepGcp — reading through kubectl (#1087)", () => {
+  test("a hand-edited field surfaces with its path; an unsupported entity type is unsupported-kind", async () => {
+    execMock.mockImplementation(
+      respondTo({
+        "storagebucket.storage.cnrm.cloud.google.com data-bucket": {
+          apiVersion: "storage.cnrm.cloud.google.com/v1beta1",
+          kind: "StorageBucket",
+          metadata: {
+            name: "data-bucket",
+            namespace: "config-control",
+            uid: "uid-bucket",
+            labels: { app: "web-renamed" },
+            managedFields: [
+              {
+                manager: "kubectl-edit",
+                operation: "Update",
+                fieldsV1: { "f:metadata": { "f:labels": { "f:app": {} } } },
+              },
+            ],
+          },
+          spec: {},
+          status: {},
+        },
+      }),
+    );
+
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepGcp({
+        environment: "prod",
+        entityNames: ["dataBucket", "unknownKind"],
+        entities: makeEntities([
+          {
+            name: "dataBucket",
+            entityType: "GCP::Storage::Bucket",
+            props: { metadata: { name: "data-bucket", namespace: "config-control", labels: { app: "web" } } },
+          },
+          { name: "unknownKind", entityType: "AWS::S3::Bucket", props: { metadata: { name: "x" } } },
+        ]),
+      }),
+    );
+
+    expect(result.resources.dataBucket.properties).toMatchObject({ metadata: { labels: { app: "web-renamed" } } });
+    expect(result.resources.dataBucket.properties).not.toHaveProperty("status");
+    expect(result.unobserved.unknownKind.reason).toBe("unsupported-kind");
+  });
+
+  test("a read failure is a hole with a reason, never silence", async () => {
+    execMock.mockImplementation(() => {
+      throw Object.assign(new Error("kubectl failed"), { stderr: "Error from server (Forbidden): storagebuckets.storage.cnrm.cloud.google.com is forbidden" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepGcp({
+        environment: "prod",
+        entityNames: ["broken"],
+        entities: makeEntities([
+          { name: "broken", entityType: "GCP::Storage::Bucket", props: { metadata: { name: "broken" } } },
+        ]),
+      }),
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved.broken.reason).toBe("no-credentials");
+  });
+
+  test("--owned withholds an unmarked object as filtered, not absent", async () => {
+    execMock.mockImplementation(
+      respondTo({
+        "storagebucket.storage.cnrm.cloud.google.com theirs": {
+          apiVersion: "storage.cnrm.cloud.google.com/v1beta1",
+          kind: "StorageBucket",
+          metadata: { name: "theirs", uid: "uid-theirs" },
+          spec: {},
+        },
+      }),
+    );
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepGcp({
+        environment: "prod",
+        entityNames: ["theirs"],
+        owned: true,
+        entities: makeEntities([{ name: "theirs", entityType: "GCP::Storage::Bucket", props: { metadata: { name: "theirs" } } }]),
+      }),
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved.theirs.reason).toBe("filtered");
+  });
+});
+
+/**
+ * The acceptance test for #1087, in the reference shape
+ * (`lexicons/aws/src/deep-observe.test.ts` / `lexicons/k8s/src/deep-observe.test.ts`):
+ * declared source, a live tree carrying realistic Config Connector
+ * managedFields noise, driven through the real reader and core's real
+ * `diffDeepObservation`, with `gcpPlugin`'s real static hooks.
+ */
+describe("end to end: Config Connector managed-fields-derived drift (#1087)", () => {
+  const declared = makeEntities([
+    // "dataBucket": chant's own kubectl-apply owns most fields (attributed to
+    // "kubectl-client-side-apply", not "chant" — see the module doc's GCP
+    // twist); CNRM owns an undeclared field and an observed-state annotation
+    // (both pruned); a hand kubectl-edit changed a declared label (drift);
+    // a declared annotation moved to a value the baseline accepts.
+    {
+      name: "dataBucket",
+      entityType: "GCP::Storage::Bucket",
+      props: {
+        metadata: {
+          name: "data-bucket",
+          namespace: "config-control",
+          labels: { app: "web", "cnrm-test": "true" },
+          annotations: { "build-id": "42" },
+        },
+        spec: { location: "US", storageClass: "STANDARD" },
+      },
+    },
+    // "sqlInstance": chant declares spec.tier; Config Connector's OWN
+    // controller currently holds it at a different value (a manual gcloud
+    // change the controller's "merge" reconciliation folded back in). Foreign
+    // ownership does not silence it, because chant declared it too —
+    // contested, same as k8s's "worker" case, but contested by CNRM itself
+    // rather than by a human.
+    {
+      name: "sqlInstance",
+      entityType: "GCP::SQL::Instance",
+      props: {
+        metadata: { name: "primary-db", namespace: "config-control" },
+        spec: { tier: "db-f1-micro" },
+      },
+    },
+    // No Config Connector GVK derivable for this type at all.
+    { name: "cache", entityType: "AWS::ElastiCache::CacheCluster", props: { metadata: { name: "cache" } } },
+    // The read itself fails.
+    { name: "broken", entityType: "GCP::Storage::Bucket", props: { metadata: { name: "broken" } } },
+  ]);
+
+  const bucketLive = {
+    apiVersion: "storage.cnrm.cloud.google.com/v1beta1",
+    kind: "StorageBucket",
+    metadata: {
+      name: "data-bucket",
+      namespace: "config-control",
+      uid: "uid-bucket",
+      resourceVersion: "42",
+      generation: 7,
+      creationTimestamp: "2026-01-01T00:00:00Z",
+      // GENUINE DRIFT: chant declares this label; a person ran `kubectl edit`
+      // and it now belongs to "kubectl-edit", not chant's own apply.
+      labels: { app: "web-renamed", "cnrm-test": "true" },
+      // ACCEPTED: chant declares this annotation; the platform's baseline
+      // accepts "43".
+      annotations: {
+        "build-id": "43",
+        // NOISE: CNRM's own observed-state bookkeeping, undeclared.
+        "cnrm.cloud.google.com/observed-secret-versions": '{"db-password":"1"}',
+        // NOISE: classic `kubectl apply`'s own bookkeeping, undeclared —
+        // pruned by the reused ownership rule with no special case needed,
+        // because its manager ("kubectl-client-side-apply") is foreign and
+        // chant's declared tree never carries this key.
+        "kubectl.kubernetes.io/last-applied-configuration": "{...}",
+      },
+      managedFields: [
+        {
+          manager: "kubectl-client-side-apply",
+          operation: "Update",
+          fieldsV1: {
+            "f:metadata": {
+              "f:labels": { "f:cnrm-test": {} },
+              "f:annotations": {
+                "f:build-id": {},
+                "f:kubectl.kubernetes.io/last-applied-configuration": {},
+              },
+            },
+            "f:spec": { "f:location": {}, "f:storageClass": {} },
+          },
+        },
+        {
+          // The hand edit — transferred ownership of just this one label.
+          manager: "kubectl-edit",
+          operation: "Update",
+          fieldsV1: { "f:metadata": { "f:labels": { "f:app": {} } } },
+        },
+        {
+          // NOISE: Config Connector's own controller sets an undeclared
+          // field and its own bookkeeping annotation.
+          manager: "cnrm-controller-manager",
+          operation: "Update",
+          fieldsV1: {
+            "f:spec": { "f:uniformBucketLevelAccess": {} },
+            "f:metadata": { "f:annotations": { "f:cnrm.cloud.google.com/observed-secret-versions": {} } },
+          },
+        },
+        {
+          // NOISE: status is a subresource write, excluded by default.
+          manager: "cnrm-controller-manager",
+          operation: "Update",
+          subresource: "status",
+          fieldsV1: { "f:status": { "f:conditions": {} } },
+        },
+      ],
+    },
+    spec: { location: "US", storageClass: "STANDARD", uniformBucketLevelAccess: true },
+    status: { conditions: [{ type: "Ready", status: "True" }] },
+  };
+
+  const sqlInstanceLive = {
+    apiVersion: "sql.cnrm.cloud.google.com/v1beta1",
+    kind: "SQLInstance",
+    metadata: {
+      name: "primary-db",
+      namespace: "config-control",
+      uid: "uid-sql",
+      managedFields: [
+        {
+          // Config Connector's own reconciliation currently holds `spec.tier`
+          // — contested because chant declares it too, regardless of who's
+          // holding it live.
+          manager: "cnrm-controller-manager",
+          operation: "Update",
+          fieldsV1: { "f:spec": { "f:tier": {} } },
+        },
+      ],
+    },
+    spec: { tier: "db-n1-standard-1" },
+  };
+
+  const cluster = () =>
+    respondTo({
+      "storagebucket.storage.cnrm.cloud.google.com data-bucket": bucketLive,
+      "sqlinstance.sql.cnrm.cloud.google.com primary-db": sqlInstanceLive,
+    });
+
+  const baseline = {
+    dataBucket: {
+      type: "GCP::Storage::Bucket",
+      accepted: [{ path: "metadata.annotations.build-id", value: "43" }],
+    },
+  };
+
+  test("exactly the genuine + contested drift surfaces; controller/kubectl-apply noise and the accepted annotation do not", async () => {
+    execMock.mockImplementation((cmd: string) => {
+      if (cmd.includes("broken")) throw Object.assign(new Error("boom"), { stderr: "Error from server (InternalError): backend unavailable" });
+      return cluster()(cmd);
+    });
+
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepGcp({ environment: "prod", entityNames: [...declared.keys()], entities: declared }),
+    );
+    const result = diffDeepObservation(declared, live, gcpDeepNormalizationHooks, baseline);
+
+    expect(result.drifted).toEqual([
+      {
+        name: "dataBucket",
+        type: "GCP::Storage::Bucket",
+        changes: [{ path: "metadata.labels.app", kind: "changed", declared: "web", live: "web-renamed" }],
+      },
+      {
+        name: "sqlInstance",
+        type: "GCP::SQL::Instance",
+        changes: [{ path: "spec.tier", kind: "changed", declared: "db-f1-micro", live: "db-n1-standard-1" }],
+      },
+    ]);
+
+    expect(result.accepted).toEqual([
+      {
+        name: "dataBucket",
+        type: "GCP::Storage::Bucket",
+        changes: [{ path: "metadata.annotations.build-id", kind: "changed", declared: "42", live: "43", baseline: "43" }],
+      },
+    ]);
+
+    // CNRM's undeclared field, its observed-state annotation, and classic
+    // kubectl's own bookkeeping annotation never appear at all — not as
+    // drift, not as "undeclared" noise.
+    const bucketDriftPaths = result.drifted.find((d) => d.name === "dataBucket")?.changes.map((c) => c.path) ?? [];
+    expect(bucketDriftPaths).not.toContain("spec.uniformBucketLevelAccess");
+    expect(JSON.stringify(result)).not.toContain("observed-secret-versions");
+    expect(JSON.stringify(result)).not.toContain("last-applied-configuration");
+
+    expect(result.unobserved).toEqual([
+      { name: "broken", type: "GCP::Storage::Bucket", reason: "read-failed", detail: expect.stringContaining("InternalError") },
+      {
+        name: "cache",
+        type: "AWS::ElastiCache::CacheCluster",
+        reason: "unsupported-kind",
+        detail: expect.stringContaining("cannot derive a Config Connector GVK"),
+      },
+    ]);
+  });
+
+  test("without the baseline the annotation is drift too; accepting it is what silences it", async () => {
+    execMock.mockImplementation((cmd: string) => {
+      if (cmd.includes("broken")) throw Object.assign(new Error("boom"), { stderr: "Error from server (InternalError): backend unavailable" });
+      return cluster()(cmd);
+    });
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepGcp({ environment: "prod", entityNames: [...declared.keys()], entities: declared }),
+    );
+    const result = diffDeepObservation(declared, live, gcpDeepNormalizationHooks);
+    const bucket = result.drifted.find((d) => d.name === "dataBucket");
+    expect(bucket?.changes.map((c) => c.path).sort()).toEqual(["metadata.annotations.build-id", "metadata.labels.app"]);
+    expect(result.accepted).toEqual([]);
+  });
+
+  test("a whole-lexicon failure (bound-context mismatch) is a hole for every declared entity, never a clean report", async () => {
+    loadChantConfigMock.mockResolvedValue({ config: { k8s: { profiles: { prod: { context: "prod-cnrm" } } } } });
+    execMock.mockImplementation((cmd: string) => {
+      if (cmd.includes("current-context")) return { stdout: "staging-cnrm\n", stderr: "" };
+      throw new Error(`unexpected cmd (should have refused before any kubectl get): ${cmd}`);
+    });
+
+    const live = await observeDeep(gcpPlugin, { environment: "prod", buildOutput: "", entities: declared });
+    expect(live.resources).toEqual({});
+    expect(new Set(Object.values(live.unobserved).map((u) => u.reason))).toEqual(new Set(["read-failed"]));
+    expect(Object.keys(live.unobserved).sort()).toEqual(["broken", "cache", "dataBucket", "sqlInstance"]);
+  });
+});
+
+/**
+ * The managers-specific case: on GCP's real kubectl-shelled apply path,
+ * chant's own writes are attributed to kubectl's own default manager
+ * (`kubectl-client-side-apply`), never to `chant`/`chant:<stack>` — unlike
+ * the k8s lexicon's typed-client SSA path. This proves the contested-field
+ * rule (question 3: "is it declared?") is what keeps GCP's drift semantics
+ * correct despite that, exactly as the module doc claims: the same live
+ * mutation is drift when declared and silence when undeclared, regardless of
+ * which non-chant manager holds the field.
+ */
+describe("the GCP manager twist: no chant-branded field manager, and the contested rule covers it anyway (#1087)", () => {
+  const liveWith = (manager: string, imageTag: string) => ({
+    apiVersion: "run.cnrm.cloud.google.com/v1beta1",
+    kind: "RunService",
+    metadata: {
+      name: "app",
+      namespace: "config-control",
+      uid: "uid-app",
+      managedFields: [
+        { manager, operation: "Update", fieldsV1: { "f:spec": { "f:template": { "f:spec": { "f:containers": { 'k:{"name":"app"}': { "f:image": {} } } } } } } },
+      ],
+    },
+    spec: { template: { spec: { containers: [{ name: "app", image: imageTag }] } } },
+  });
+
+  const declaredWith = (declareImage: boolean) =>
+    makeEntities([
+      {
+        name: "app",
+        entityType: "GCP::Run::Service",
+        props: {
+          metadata: { name: "app", namespace: "config-control" },
+          spec: { template: { spec: { containers: declareImage ? [{ name: "app", image: "app:1.0" }] : [{ name: "app" }] } } },
+        },
+      },
+    ]);
+
+  test("declared: the same mutated value is drift, whether the owning manager is kubectl's default or CNRM's controller", async () => {
+    for (const manager of ["kubectl-client-side-apply", "cnrm-controller-manager", "some-other-operator"]) {
+      execMock.mockImplementation(respondTo({ "runservice.run.cnrm.cloud.google.com app": liveWith(manager, "app:2.0") }));
+      const entities = declaredWith(true);
+      const live = normalizeDeepObservation(
+        await observeResourcesDeepGcp({ environment: "prod", entityNames: ["app"], entities }),
+      );
+      const result = diffDeepObservation(entities, live, gcpDeepNormalizationHooks);
+      expect(result.drifted, `manager ${manager}`).toEqual([
+        {
+          name: "app",
+          type: "GCP::Run::Service",
+          changes: [{ path: "spec.template.spec.containers[#app].image", kind: "changed", declared: "app:1.0", live: "app:2.0" }],
+        },
+      ]);
+    }
+  });
+
+  test("undeclared: the same mutated value is silence, not drift and not undeclared noise, whoever the manager is", async () => {
+    for (const manager of ["kubectl-client-side-apply", "cnrm-controller-manager", "some-other-operator"]) {
+      execMock.mockImplementation(respondTo({ "runservice.run.cnrm.cloud.google.com app": liveWith(manager, "app:2.0") }));
+      const entities = declaredWith(false);
+      const live = normalizeDeepObservation(
+        await observeResourcesDeepGcp({ environment: "prod", entityNames: ["app"], entities }),
+      );
+      const result = diffDeepObservation(entities, live, gcpDeepNormalizationHooks);
+      expect(result.drifted, `manager ${manager}`).toEqual([]);
+      expect(result.unchanged, `manager ${manager}`).toEqual(["app"]);
+      expect(JSON.stringify(result)).not.toContain("app:2.0");
+    }
+  });
+
+  test("chant's own field-manager naming scheme, if it were ever used on this path, would also be recognized", async () => {
+    // Future-proofing check: an explicit `chant`/`chant:<stack>` manager (were
+    // gcp's apply path ever to route through server-side apply, matching the
+    // k8s lexicon) is still classified chant-owned, not merely contested.
+    execMock.mockImplementation(respondTo({ "runservice.run.cnrm.cloud.google.com app": liveWith("chant:crdb-gke", "app:2.0") }));
+    const entities = declaredWith(false); // undeclared — the only way to tell "chant-owned" apart from "contested" behaviorally.
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepGcp({ environment: "prod", entityNames: ["app"], entities }),
+    );
+    const result = diffDeepObservation(entities, live, gcpDeepNormalizationHooks);
+    // Chant-owned paths are never pruned by the ownership rule, even when
+    // undeclared — so this reports as an undeclared live property, not silence.
+    expect(result.drifted).toEqual([
+      {
+        name: "app",
+        type: "GCP::Run::Service",
+        changes: [{ path: "spec.template.spec.containers[#app].image", kind: "undeclared", live: "app:2.0" }],
+      },
+    ]);
+  });
+});

package/src/deep-observe.ts

@@ -0,0 +1,276 @@
+/**
+ * GCP deep observation (#1087) — the GCP row of the deep-observe contract
+ * (#1014), reusing the k8s row (#1076) rather than writing a second one, per
+ * the issue and #1173's own per-row checklist: "A Config Connector resource
+ * *is* a Kubernetes object, so it carries managed-fields for the same
+ * reason. Share the hooks rather than writing a second implementation."
+ *
+ * ## A Config Connector CR is a Kubernetes object
+ *
+ * `kubectl get <kind>.<group> -o json` against a Config Connector-enabled
+ * cluster (`./describe-resources.ts`'s own transport, reused here) returns a
+ * real Kubernetes API object: `metadata.managedFields`, `status`,
+ * `metadata.{uid,resourceVersion,generation,creationTimestamp}` are all
+ * present for the identical reason they're present on a Deployment — the API
+ * server that served the read is the same kind of API server. The epic's own
+ * table lists `metadata.managedFields` under GCP's "field noise" to prune; it
+ * is the opposite of noise, and it is available here for exactly the reason
+ * chant #1076 reads it on the k8s row.
+ *
+ * So this reader reuses, unchanged, from `@intentius/chant/managed-fields`:
+ *
+ * - `K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS` — the generic Kubernetes object
+ *   envelope (`status`, `metadata.{uid,resourceVersion,generation,
+ *   creationTimestamp,managedFields,selfLink}`).
+ * - `k8sListMapOrderKey` — Kubernetes' own list-map-key conventions, needed
+ *   because some CNRM kinds embed genuinely k8s-shaped substructures (Cloud
+ *   Run's `RunService` wraps a Knative pod spec with
+ *   `containers`/`env`/`ports`, keyed the same way a Deployment's are).
+ * - `buildOwnershipSets`/`pruneByOwnership` — the managed-fields ownership
+ *   walk itself: chant #1076's actual contribution, and the piece this row
+ *   exists to reuse rather than reimplement.
+ *
+ * These live in core, not in the k8s lexicon, specifically so this file can
+ * reuse them without adding a dependency on the k8s lexicon package or (never,
+ * per the issue) on `@intentius/chant-k8s-client` — this reader shells
+ * `kubectl` exactly like `./describe-resources.ts` already does. Chant
+ * #1177/#1180 kept GCP off the typed client deliberately ("a separate
+ * lexicon and a separate decision"); this row does not revisit that.
+ *
+ * ## The GCP twist: who is "chant" on this path?
+ *
+ * Chant #1076's rule treats a field as always-diffable when *any* chant field
+ * manager (`chant`, `chant:<stack>` — chant #1075's SSA identity) owns it.
+ * That identity is only ever set by the k8s lexicon's typed client, applying
+ * with an explicit `--field-manager`. GCP has no equivalent apply activity:
+ * every gcp example's own deploy script (e.g.
+ * `examples/cockroachdb-multi-region-gke/scripts/deploy.sh`) runs plain
+ * `kubectl apply -f dist/*.yaml` — classic client-side apply, no
+ * `--server-side`, no `--field-manager`. kubectl's own hardcoded default
+ * field manager for that command is `kubectl-client-side-apply`, identical
+ * to what a human's `kubectl apply -f their-own-file.yaml` would record.
+ * **There is no field-manager name on GCP's real deploy path that
+ * distinguishes "chant applied this" from "a person applied this".**
+ * (Config Connector's own controller is distinguishable — its reconciler
+ * records itself as `cnrm-controller-manager`, per the k8s-config-connector
+ * source's own `ControllerManagedFieldManager` constant — just chant isn't,
+ * on this path.)
+ *
+ * That sounds like it breaks question 1 of the three-question rule
+ * (`isChantManager`) below. It doesn't, because question 3 already covers
+ * it: chant's own kubectl apply always applies the *exact* built manifest, so
+ * any field chant's own most recent apply set is, by construction, also in
+ * `declaredRoot` (`props`) on the very next read — chant never authors a
+ * field it does not also declare. Working through what that means per field:
+ *
+ * - A field only chant's own applies have ever touched: not recognized as
+ *   `chantOwned` (its manager is `kubectl-client-side-apply`, not `chant`),
+ *   but foreign-owned *and* declared → contested → kept diffable anyway.
+ *   Same outcome as being chant-owned would have been.
+ * - A field CNRM's controller sets and chant never declares: foreign-owned,
+ *   undeclared → pruned. Correct regardless of whether "chant" is recognized.
+ * - A field a human sets by hand (`kubectl edit`, or their own `kubectl apply
+ *   -f`) that chant *does* declare: foreign-owned (manager is `kubectl-edit`
+ *   or `kubectl-client-side-apply`) and declared → contested → surfaces as
+ *   drift. This is #1087's acceptance criterion 1.
+ *
+ * `isGcpChantFieldManager` below still checks the `chant`/`chant:<stack>`
+ * family, so a future GCP apply path that *does* route through server-side
+ * apply with an explicit chant field manager (matching the k8s lexicon's own
+ * path) is recognized with no change needed here. On today's plain-apply
+ * path it is inert — proven inert by this module's own test suite (the
+ * "managers-specific case") — and the contested-field rule (question 3) is
+ * what actually keeps GCP's drift semantics correct without it.
+ *
+ * ## What's genuinely GCP-specific
+ *
+ * - No typed operation surface (chant #1177's `operationFor` is a k8s
+ *   lexicon/typed-client concept, generated from cluster discovery this
+ *   reader never touches) — `./describe-resources.ts`'s `deriveGVK` stands in.
+ * - CNRM's own observed-state annotations (`./deep-observe-hooks.ts`'s
+ *   `gcpDeepNormalizationHooks`) — bookkeeping the controller writes into
+ *   `metadata.annotations` for GCP-side properties the CRD schema has no
+ *   field for. See that module's doc for why the list is narrow.
+ *
+ * ## Deliberately out of scope
+ *
+ * `status.conditions` staleness as its own signal — the issue's own
+ * "Proposed" section floats this as worth *deciding*, not worth doing here.
+ * `status` is pruned outright (matching k8s, and the acceptance criteria),
+ * and a CNRM projection lagging real GCP state is a genuine gap, but
+ * detecting it means reading the actual GCP API, not the CR — a different
+ * read than this contract's "normalize what Kubernetes reports" scope.
+ * Flagged, not papered over.
+ *
+ * ## The build-path boundary
+ *
+ * This module imports `./describe-resources.ts` for the live kubectl
+ * transport, which imports `node:child_process`. `gcpPlugin.ts` reaches this
+ * file only via `await import("./deep-observe")` inside
+ * `observeResourcesDeep` — never statically — the same way it already
+ * dynamic-imports `describeResources`/`exportResources`, so `chant build`
+ * never resolves a process-spawning module just to synthesize a template.
+ * `deepNormalizationHooks` is plain data with no such dependency
+ * (`./deep-observe-hooks.ts`) and is imported statically from `plugin.ts`,
+ * because core normalizes the *declared* tree with it whether or not a
+ * cluster read ever happens.
+ */
+
+import type {
+  DeepNormalizationHooks,
+  DeepObservationResult,
+  DeepResourceObservation,
+  UnobservedEntity,
+} from "@intentius/chant/lexicon";
+import { deepObservation, normalizeDeepProperties } from "@intentius/chant/deep-observation";
+import { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { classifyKubectlFailure } from "@intentius/chant/kubectl-context";
+import { buildOwnershipSets, pruneByOwnership, type OwnershipSets, type ManagedFieldsEntryLike } from "@intentius/chant/managed-fields";
+import { deriveGVK, execConfigConnectorGet, resolveGcpKubectlContext } from "./describe-resources";
+import { gcpDeepNormalizationHooks } from "./deep-observe-hooks";
+
+// 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. `plugin.ts`'s own `deepNormalizationHooks` field imports the hooks
+// separately, directly from `./deep-observe-hooks` — see the module doc.
+export { gcpDeepNormalizationHooks };
+
+export interface GcpDeepObserveOptions {
+  environment: string;
+  buildOutput?: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  stack?: string;
+  owned?: boolean;
+}
+
+/**
+ * Matches chant's field-manager naming scheme (chant #1075: bare `chant`, or
+ * `chant:<stack>`) — the same convention `@intentius/chant-k8s-client`'s
+ * `isChantFieldManager` checks. Restated here rather than imported: gcp must
+ * never depend on that package (chant #1074/#1177's structural boundary — the
+ * k8s lexicon reads live cluster state through a typed client, gcp shells
+ * kubectl, and the two stay independently deployable). This is a two-branch
+ * string comparison with nothing to drift out of sync; the piece that
+ * genuinely could — the managed-fields ownership walk — is shared through
+ * `@intentius/chant/managed-fields`, not reimplemented here. See the module
+ * doc for why this rarely matches anything on GCP's real deploy path today,
+ * and why that's fine.
+ */
+function isGcpChantFieldManager(manager: string | undefined): boolean {
+  if (!manager) return false;
+  return manager === "chant" || manager.startsWith("chant:");
+}
+
+/**
+ * The managed-fields prune, composed with the static rules, for one
+ * resource's normalization call — the same layering k8s's `perResourceHooks`
+ * uses, sharing the actual rule (`pruneByOwnership`) rather than restating it.
+ */
+function perResourceHooks(sets: OwnershipSets): DeepNormalizationHooks {
+  return {
+    prune(node) {
+      if (gcpDeepNormalizationHooks.prune?.(node)) return true;
+      return pruneByOwnership(node, sets);
+    },
+    orderKey: gcpDeepNormalizationHooks.orderKey,
+  };
+}
+
+/** `metadata.managedFields` off a raw `kubectl get -o json` object — a plain decode, no client-side type coercion. */
+function managedFieldsOfRaw(obj: Record<string, unknown>): ManagedFieldsEntryLike[] {
+  const metadata = obj.metadata;
+  if (!metadata || typeof metadata !== "object") return [];
+  const entries = (metadata as Record<string, unknown>).managedFields;
+  if (!Array.isArray(entries)) return [];
+  return entries.filter((e): e is ManagedFieldsEntryLike => !!e && typeof e === "object");
+}
+
+/** The live object minus the envelope fields that live outside `properties` on {@link DeepResourceObservation} (mirrors k8s's `propertiesTreeOf`). */
+function propertiesTreeOf(obj: Record<string, unknown>): Record<string, unknown> {
+  const { apiVersion: _apiVersion, kind: _kind, ...rest } = obj;
+  return rest;
+}
+
+/**
+ * Read the live property tree for each declared entity via `kubectl get
+ * <kind>.<group> -o json`, pruning by `metadata.managedFields` (see the
+ * module doc). Reuses `./describe-resources.ts`'s exact cluster-binding
+ * resolution and kubectl mechanics — the binding check (chant #1100) 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 observeResourcesDeepGcp(options: GcpDeepObserveOptions): Promise<DeepObservationResult> {
+  const resources: Record<string, DeepResourceObservation> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+
+  // Resolve the cluster identity once, before touching any resource — a
+  // declared-but-mismatched binding throws here (chant #1100), aborting the
+  // whole read rather than letting the per-entity try/catch below absorb it
+  // as an ordinary "not found". Core turns the throw into NOT-OBSERVED for
+  // every declared entity.
+  const ctxArg = await resolveGcpKubectlContext(options.environment);
+
+  for (const [entityName, { entityType, props }] of options.entities) {
+    const gvk = deriveGVK(entityType);
+    if (!gvk) {
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: `cannot derive a Config Connector GVK from ${entityType}`,
+      };
+      continue;
+    }
+
+    const metadata = props.metadata as { name?: string; namespace?: string } | undefined;
+    const name = metadata?.name;
+    if (!name) {
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "read-failed",
+        detail: "declared entity has no metadata.name to query by",
+      };
+      continue;
+    }
+
+    try {
+      const obj = await execConfigConnectorGet(gvk, name, metadata.namespace, ctxArg);
+      const objMetadata = obj.metadata as { labels?: Record<string, string>; uid?: string } | undefined;
+
+      // owned filter: withhold resources not carrying chant's marker label.
+      // Withheld is not absent (#1089) — the CR exists, it just isn't chant's.
+      if (options.owned && !hasOwnershipMarker(objMetadata?.labels, LABEL_OWNERSHIP_KEYS)) {
+        unobserved[entityName] = {
+          type: entityType,
+          reason: "filtered",
+          detail: "live resource carries no chant ownership marker and --owned was requested",
+        };
+        continue;
+      }
+
+      const liveRoot = propertiesTreeOf(obj);
+      const sets = buildOwnershipSets(managedFieldsOfRaw(obj), liveRoot, props, isGcpChantFieldManager);
+
+      resources[entityName] = {
+        type: entityType,
+        physicalId: objMetadata?.uid,
+        properties: normalizeDeepProperties(liveRoot, {
+          entityType,
+          side: "live",
+          hooks: perResourceHooks(sets),
+        }),
+      };
+    } catch (err) {
+      // A NotFound is a real absence, same as the thin read — records
+      // nothing here, since restating it would turn one finding into two.
+      // Anything else (auth, connectivity, a mismatched context) proves
+      // nothing and is a hole rather than an absence (#1089).
+      const outcome = classifyKubectlFailure(err);
+      if (outcome.kind === "unobserved") {
+        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+      }
+    }
+  }
+
+  return deepObservation(resources, unobserved);
+}

package/src/describe-resources.ts

@@ -20,6 +20,11 @@
  * `chant.config.ts` (see `lexicons/k8s/src/config.ts`), not a separate
  * `gcp.profiles` key, because it is fundamentally the same kubectl context a
  * project's K8s entities would use against the same cluster.
+ *
+ * `resolveGcpKubectlContext` and `execConfigConnectorGet` below are exported
+ * so `./deep-observe.ts` (chant #1087) shares this exact cluster-binding
+ * resolution and `kubectl get -o json` mechanics rather than restating them —
+ * the two readers differ only in how much of the response each one keeps.
  */
 
 import { exec } from "node:child_process";
@@ -32,6 +37,38 @@ import { resolveClusterTarget, classifyKubectlFailure } from "@intentius/chant/k
 
 const execAsync = promisify(exec);
 
+/**
+ * Resolve this environment's cluster binding once and return the `--context`
+ * argv fragment every subsequent kubectl call should append (empty when
+ * unbound — ambient context, unchanged behavior). Throws on a bound-but-
+ * mismatched context (chant #1100), the same loud refusal both readers rely
+ * on core to turn into NOT-OBSERVED for every declared entity.
+ */
+export async function resolveGcpKubectlContext(environment: string): Promise<string[]> {
+  const { config } = await loadChantConfig(process.cwd());
+  const target = await resolveClusterTarget(config as Record<string, unknown>, environment, "gcp");
+  return target.context ? ["--context", target.context] : [];
+}
+
+/**
+ * `kubectl get <kind>.<group> <name> [-n <namespace>] [--context <ctx>] -o
+ * json`, parsed. Throws on any kubectl failure — callers classify it with
+ * `classifyKubectlFailure` exactly like today, so a NotFound and an
+ * auth/connectivity failure are told apart at the call site, not here.
+ */
+export async function execConfigConnectorGet(
+  gvk: { group: string; kind: string },
+  name: string,
+  namespace: string | undefined,
+  ctxArg: readonly string[],
+): Promise<Record<string, unknown>> {
+  const kubectlResource = `${gvk.kind.toLowerCase()}.${gvk.group}`;
+  const nsArg = namespace ? ["-n", namespace] : [];
+  const cmd = ["kubectl", "get", kubectlResource, name, ...nsArg, ...ctxArg, "-o", "json"].join(" ");
+  const { stdout } = await execAsync(cmd);
+  return JSON.parse(stdout) as Record<string, unknown>;
+}
+
 interface KubectlResponse {
   metadata?: {
     name?: string;
@@ -103,9 +140,7 @@ export async function describeResources(options: {
   // resource — a declared-but-mismatched binding throws here, aborting the
   // whole describe rather than letting the per-entity try/catch below
   // absorb it as an ordinary "not found".
-  const { config } = await loadChantConfig(process.cwd());
-  const target = await resolveClusterTarget(config as Record<string, unknown>, options.environment, "gcp");
-  const ctxArg = target.context ? ["--context", target.context] : [];
+  const ctxArg = await resolveGcpKubectlContext(options.environment);
 
   for (const [entityName, { entityType, props }] of options.entities) {
     const gvk = deriveGVK(entityType);
@@ -131,13 +166,8 @@ export async function describeResources(options: {
       continue;
     }
 
-    const kubectlResource = `${gvk.kind.toLowerCase()}.${gvk.group}`;
-    const nsArg = metadata.namespace ? ["-n", metadata.namespace] : [];
-    const cmd = ["kubectl", "get", kubectlResource, name, ...nsArg, ...ctxArg, "-o", "json"].join(" ");
-
     try {
-      const { stdout } = await execAsync(cmd);
-      const obj: KubectlResponse = JSON.parse(stdout);
+      const obj = (await execConfigConnectorGet(gvk, name, metadata.namespace, ctxArg)) as KubectlResponse;
       // owned filter: withhold resources not carrying chant's marker label.
       // Withheld is not absent (#1089) — the CR exists, it just isn't chant's.
       if (options.owned && !hasOwnershipMarker(obj.metadata?.labels, LABEL_OWNERSHIP_KEYS)) {

package/src/plugin.ts

@@ -24,6 +24,7 @@ import { GcpParser } from "./import/parser";
 import { GcpGenerator } from "./import/generator";
 import { gcpCompletions } from "./lsp/completions";
 import { gcpHover } from "./lsp/hover";
+import { gcpDeepNormalizationHooks } from "./deep-observe-hooks";
 
 export const gcpPlugin: LexiconPlugin = {
   name: "gcp",
@@ -384,4 +385,20 @@ export const bucket = new StorageBucket({
     const { exportResources } = await import("./export-resources");
     return exportResources(options);
   },
+
+  // Property-level live drift via SSA managed-fields (#1087, epic #1073),
+  // reusing the k8s row (#1076) rather than writing a second implementation —
+  // a Config Connector custom resource is a Kubernetes object too. The
+  // reader lives in ./deep-observe.ts, loaded only through this dynamic
+  // import — same reason describeResources/exportResources are — so nothing
+  // on the build path resolves the live kubectl transport it shares with
+  // ./describe-resources.ts. deepNormalizationHooks is plain data with no
+  // transport dependency and is imported statically above, because core
+  // applies it to the *declared* tree whether or not a live read ever happens.
+  async observeResourcesDeep(options) {
+    const { observeResourcesDeepGcp } = await import("./deep-observe");
+    return observeResourcesDeepGcp(options);
+  },
+
+  deepNormalizationHooks: gcpDeepNormalizationHooks,
 };