@intentius/chant-lexicon-gcp 0.37.2 → 0.38.0

package/dist/api/read-client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * GCP read transport (#1209) — the applier's own REST client, pointed at the
+ * read side.
+ *
+ * GCP applies cluster-free over direct REST (#706) and, until this, observed
+ * through a Config Connector cluster: `kubectl get <cnrm-gvk> -o json` per
+ * entity, on both the thin and the deep path. That split is what #1085's
+ * principle forbids — a lexicon should be observed on the transport it is
+ * applied with, or the two can disagree about what a resource even is — and it
+ * is what made GCP the heaviest of the three O slots.
+ *
+ * ## The URL comes from the applier, not from here
+ *
+ * Every GET is built by the same `ResourceMapper.plan()` the applier uses, and
+ * this module reads `plan().getUrl` rather than composing its own URL. That is
+ * deliberate: a reader that builds its own paths is a second, silently
+ * divergent opinion about where a resource lives, and the first symptom is a
+ * read that reports absent for something the applier just wrote. Reusing the
+ * mapper makes the two structurally incapable of disagreeing.
+ *
+ * ## What that bounds
+ *
+ * Coverage is exactly the applier's dispatch table (`MAPPERS`) — StorageBucket,
+ * PubSubTopic, PubSubSubscription, SecretManagerSecret, IAMServiceAccount,
+ * RunService. The kubectl path could fetch any CNRM kind the cluster knew
+ * about, so this is narrower on paper. It is not narrower in practice for
+ * anything chant can act on: a kind with no mapper cannot be applied either, so
+ * observing it produced a live tree nothing could ever reconcile against.
+ *
+ * A kind outside the table reports NOT-OBSERVED with `unsupported-kind` rather
+ * than being dropped, so the estate says "chant did not look at this" instead of
+ * quietly implying it is not there. Widening the table is #1209's stated
+ * non-goal and belongs with the applier.
+ */
+import { type ResourceMapper } from "../op/activities/gcp-apply.js";
+/** Where to read, and as whom. */
+export interface GcpReadClientOptions {
+    /** Endpoint override for every kind (floci-gcp `http://localhost:4588`). Omit for real GCP. */
+    endpoint?: string;
+    /** GCP project the resources live in. */
+    project: string;
+    /** Injectable HTTP, so tests never touch the network. */
+    http?: GcpReadHttp;
+}
+/** Injectable HTTP client — mirrors the applier's `GcpHttp`. */
+export type GcpReadHttp = (method: string, url: string) => Promise<{
+    status: number;
+    text: string;
+}>;
+/**
+ * A read that failed for a reason the caller must classify — carries the HTTP
+ * status so a 404 (absent) is told apart from a 401/403 (no credentials) and a
+ * 5xx/network error (could not look). Mirrors `AzureReadError`.
+ */
+export declare class GcpReadError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** A 404 — the resource is genuinely absent, which is an answer, not a failure. */
+export declare function isNotFound(err: unknown): boolean;
+/** The mapper for a CNRM kind, or undefined when chant cannot act on it. */
+export declare function mapperForKind(kind: string): ResourceMapper | undefined;
+/**
+ * GET one resource on the applier's transport.
+ *
+ * `declared` is the entity's own declared spec, which is what `plan()` needs to
+ * build a URL — the same input the applier hands it. Returns the parsed body,
+ * or throws {@link GcpReadError} carrying the status.
+ */
+export declare function getResource(client: GcpReadClientOptions, kind: string, name: string, declared?: Record<string, unknown>): Promise<Record<string, unknown>>;
+//# sourceMappingURL=read-client.d.ts.map

package/dist/api/read-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-client.d.ts","sourceRoot":"","sources":["../../src/api/read-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5F,kCAAkC;AAClC,MAAM,WAAW,oBAAoB;IACnC,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAOrG;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAGnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBADxB,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEhD;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEtE;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqClC"}

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

@@ -1,39 +1,50 @@
 /**
- * The gcp lexicon's *static* deep-observation noise rules (#1087, epic #1073).
+ * GCP deep-observation noise rules (#1209) — for REST payloads, not Config
+ * Connector objects.
  *
- * 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 this replaced, and why it had to
  *
- * 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.
+ * Until #1209 the deep reader read Config Connector custom resources through
+ * kubectl, and suppressed noise two ways: this module's static rules (the k8s
+ * object envelope plus CNRM's own observed-state annotations) and, in
+ * `./deep-observe.ts`, a per-resource prune driven by `metadata.managedFields`
+ * — Kubernetes records which manager owns which field, so everything the CNRM
+ * controller owned was subtracted before the diff ran.
+ *
+ * Reading GCP's own REST APIs removes both. **A GCP payload never says who
+ * wrote a field**, so there is no managed-fields attribution to prune by, and
+ * it is not a Kubernetes object, so the k8s envelope and CNRM annotation rules
+ * match nothing in it. Audited every rule that was here: all of them were
+ * CNRM-shaped, none applies.
+ *
+ * So the noise story is re-answered rather than re-pointed, in the shape the
+ * other two cloud lexicons already use — a static table naming what the
+ * provider populates. It is hand-maintained, which is the honest cost: a
+ * server-set field nobody has listed reads as drift until it is. That is
+ * visible and fixable, where an over-broad rule silently hides real drift.
  */
-import type { DeepNormalizationHooks } from "@intentius/chant/lexicon";
+import type { DeepNormalizationHooks } from "@intentius/chant/deep-observation";
 /**
- * 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.
+ * Fields GCP populates on essentially anything, wherever they appear.
  *
- * 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.
+ * Pruned on BOTH sides and regardless of whether source declared them: these
+ * are server-assigned identity and bookkeeping, and a user who writes one is
+ * writing something the API will overwrite anyway.
+ */
+export declare const GCP_READ_ONLY_NAMES: ReadonlySet<string>;
+/**
+ * Per-kind values GCP fills in when the request omits them.
+ *
+ * Unlike {@link GCP_READ_ONLY_NAMES} these are only noise where **source never
+ * declared the property** — a default somebody explicitly wrote is a fact worth
+ * diffing, and pruning it would hide a real change away from it. The
+ * `counterpart === "absent"` gate below is what enforces that, and it is the
+ * same rule the AWS and Azure hooks apply.
+ */
+export declare const GCP_SERVICE_DEFAULTS: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/**
+ * GCP's static deep-observation noise rules, applied by core to the declared
+ * tree and the live tree alike so the two are compared in the same shape.
  */
 export declare const gcpDeepNormalizationHooks: DeepNormalizationHooks;
 //# sourceMappingURL=deep-observe-hooks.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"deep-observe-hooks.d.ts","sourceRoot":"","sources":["../src/deep-observe-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAY,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAE1F;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAelD,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CA4B5F,CAAC;AAeF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,sBAiBvC,CAAC"}

package/dist/deep-observe.d.ts

@@ -129,6 +129,30 @@ export interface GcpDeepObserveOptions {
     stack?: string;
     owned?: boolean;
 }
+/**
+ * Reshape a GCP REST body into the CNRM shape the declared source is written in.
+ *
+ * This is the half of the port that is not transport (#1209). chant's GCP
+ * source declares Config Connector custom resources — `{ metadata: { name },
+ * spec: { location, storageClass } }` — while the REST APIs return their own
+ * flat shape, `{ name, location, storageClass }`. Diffing one against the other
+ * makes every field drift twice: once as `spec.location: US -> <absent>` and
+ * again as `location: <undeclared> -> US`.
+ *
+ * Verified against floci-gcp before this existed: a bucket that matched its
+ * declaration exactly reported **7 property drifts**, all of them shape.
+ *
+ * chant has met this before. #1207 records it for AWS: Cloud Control returns
+ * the CloudFormation resource model and lines up for free, while the EC2 API
+ * returns the EC2 shape and needs mapping onto the declared shape before the
+ * diff can compare. GCP is the EC2 case.
+ *
+ * The mapping is CNRM's own convention rather than a per-kind table: identity
+ * and labels live under `metadata`, everything else is `spec`. That holds for
+ * every kind the applier can write, and a per-kind table would be a second
+ * place to forget a field.
+ */
+export declare function restToCnrmShape(body: Record<string, unknown>): Record<string, unknown>;
 /**
  * Read the live property tree for each declared entity via `kubectl get
  * <kind>.<group> -o json`, pruning by `metadata.managedFields` (see the

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

@@ -1 +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"}
+{"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;AAajE,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;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWtF;AAUD;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA0F5G"}

package/dist/describe-resources.d.ts

@@ -1,50 +1,62 @@
 /**
- * Live introspection of a GCP project via Config Connector CRDs.
+ * GCP thin observation (#1209) — presence and scrubbed outputs, read over the
+ * applier's own REST transport.
  *
- * GCP entities in chant are emitted as Config Connector custom resources
- * (apiVersion <service>.cnrm.cloud.google.com/v1beta1, kind <Service><Kind>).
- * To observe them at runtime we shell out to kubectl against a Config
- * Connector-enabled cluster — the same pattern as the K8s lexicon.
+ * chant applies GCP cluster-free over direct REST (#706). Until this, it
+ * observed through a Config Connector cluster — `kubectl get <cnrm-gvk> -o
+ * json` per entity — which is the split #1085's principle forbids: a lexicon
+ * observed on a different transport than it is applied with can disagree with
+ * itself about what a resource even is, and needs a GKE cluster to answer a
+ * question about a bucket.
  *
- *   GCP::Storage::Bucket    → kubectl get storagebucket.storage.cnrm.cloud.google.com
- *   GCP::Compute::Subnetwork → kubectl get computesubnetwork.compute.cnrm.cloud.google.com
+ * Every GET here is built by the same `ResourceMapper` the applier uses (see
+ * ./api/read-client.ts), so reader and applier cannot diverge about where a
+ * resource lives.
  *
- * Resource-not-found is an absence — `state diff --live` reports it as missing.
- * Everything else the kubectl call can fail with (auth, an unreachable API
- * server, an entity type with no derivable GVK) is NOT-OBSERVED (#1089), so a
- * read that never happened cannot become a proposed `create`.
+ * ## What changed in the answers, not just the transport
  *
- * Since this reads Config Connector CRDs through the same kubectl path as
- * the K8s lexicon, it resolves the same environment→cluster binding (chant
- * #1100) via `resolveClusterTarget` — `k8s.profiles.<env>.context` in
- * `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.
+ * **Status.** Config Connector encodes state as a `Ready` condition, which a
+ * GCP REST payload has no equivalent of — a bucket simply exists. So a
+ * successful GET is `PRESENT` unless the body carries a recognisable state of
+ * its own (Cloud Run's `status.conditions`, an explicit `state`). `PRESENT` is
+ * the same sentinel the Azure reader emits for the same reason.
  *
- * `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.
+ * **Ownership.** CNRM carried chant's marker as a k8s label. The REST payloads
+ * carry `labels` only on kinds that have them (a bucket does; a Pub/Sub topic
+ * does not), so ownership is `unknown` where there is nothing to read — and
+ * `--owned` degrades to detect-only rather than withholding everything it
+ * cannot prove, the same posture the AWS thin path takes when
+ * `describe-stack-resources` returns no tags.
+ *
+ * **Coverage.** kubectl could fetch any CNRM kind the cluster knew about; REST
+ * reaches the kinds the applier has a mapper for. That is narrower on paper and
+ * not in practice: a kind with no mapper cannot be applied either, so observing
+ * it produced a live tree nothing could reconcile against. Anything outside the
+ * table reports NOT-OBSERVED with `unsupported-kind` (#1089) rather than being
+ * dropped.
  */
 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>>;
+/** The parts of a GCP REST payload this reader looks at. Every field is
+ * optional because they vary by kind — a bucket has `id` and `labels`, a
+ * Pub/Sub topic has neither. */
+interface GcpRestResponse {
+    id?: string;
+    name?: string;
+    selfLink?: string;
+    labels?: Record<string, string> | null;
+    updated?: string;
+    timeCreated?: string;
+    state?: string;
+    status?: {
+        conditions?: Array<{
+            type?: string;
+            status?: string;
+            state?: string;
+            reason?: string;
+        }>;
+        [k: string]: unknown;
+    };
+}
 /**
  * Mirror of `lexicons/gcp/src/serializer.ts:deriveGVKFromType` — keeping the
  * derivation logic local so describeResources can compute the kubectl resource
@@ -54,6 +66,19 @@ export declare function deriveGVK(entityType: string): {
     group: string;
     kind: string;
 } | null;
+/**
+ * Status from a REST payload.
+ *
+ * Most GCP resources have no status at all — a bucket that answers a GET simply
+ * exists — so `PRESENT` is the honest answer and the common one. Where a kind
+ * does carry state (Cloud Run's `status.conditions`, a `state` enum), that is
+ * reported instead.
+ *
+ * `PRESENT` is deliberately the same sentinel the Azure reader emits for a
+ * resource with no `provisioningState`: one word, meaning "read it back, it is
+ * there, there is nothing richer to say".
+ */
+export declare function statusFromRest(obj: GcpRestResponse): string;
 export declare function describeResources(options: {
     environment: string;
     buildOutput: string;
@@ -64,4 +89,5 @@ export declare function describeResources(options: {
     }>;
     owned?: boolean;
 }): Promise<ObservationResult>;
+export {};
 //# sourceMappingURL=describe-resources.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,MAAM,0BAA0B,CAAC;AAqBtG;;gCAEgC;AAChC,UAAU,eAAe;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACxF,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASpF;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAY3D;AAED,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,CAmH7B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "571c6a7cd95e35daf0a9759b2b1c4bf92f4c9292da39fceac9f2f15fa835408c",
+    "manifest.json": "13863f1d8cea5d465ec62a46a03f663f99410213d240931a81278ece85f7486b",
     "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": "451fa6ba716cda0e9d03c8f69ae4d50ad4ec9fb58c4b6a2cfe56564fc6298223"
+  "composite": "13fc3388cd69bbb0f029a77554c0c8b9295f78e934e9ec67b65c8a516f58485a"
 }

package/dist/manifest.json

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

package/dist/op/activities/floci-gcp.d.ts

@@ -1,9 +1,10 @@
+import { type EmulatorCapability, type EmulatorSpec } from "@intentius/chant/op";
 export interface FlociGcpUpArgs {
     /** Container name. Default: `chant-floci-gcp`. */
     name?: string;
     /** Host port mapped to the emulator's `:4588`. Default: `4588`. */
     port?: number;
-    /** Image. Default: `floci/floci-gcp:latest`. */
+    /** Image. Default: the pinned `floci/floci-gcp` tag. */
     image?: string;
     /** Readiness timeout in ms. Default: `60000`. */
     timeoutMs?: number;
@@ -14,6 +15,16 @@ export interface FlociGcpDownArgs {
     /** Container name to remove. Default: `chant-floci-gcp`. */
     name?: string;
 }
+export declare const FLOCI_GCP_SPEC: EmulatorSpec;
+/**
+ * The gcp plugin's emulator capability (#1345).
+ *
+ * `env` is deliberately empty: `gcpApply` reaches the emulator through an
+ * explicit `endpoint` argument rather than an ambient variable, so there is no
+ * var to inject and claiming one would be worse than claiming none. The
+ * endpoint is still reported by `chant emulator up --json`.
+ */
+export declare const FLOCI_GCP_EMULATOR: EmulatorCapability;
 export declare const flociGcpExistsCommand: (name: string) => string;
 export declare const flociGcpRmCommand: (name: string) => string;
 export declare const flociGcpHealthUrl: (port: number) => string;

package/dist/op/activities/floci-gcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"floci-gcp.d.ts","sourceRoot":"","sources":["../../../src/op/activities/floci-gcp.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAWD,eAAO,MAAM,qBAAqB,0BAAoB,CAAC;AACvD,eAAO,MAAM,iBAAiB,0BAAgB,CAAC;AAC/C,eAAO,MAAM,iBAAiB,0BAAgB,CAAC;AAC/C,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,0BAAe,CAAC;AAC7C,eAAO,MAAM,kBAAkB,GAAI,OAAM,cAAmB,KAAG,MAA8B,CAAC;AAE9F,+EAA+E;AAC/E,eAAO,MAAM,UAAU,GAAI,OAAM,cAAmB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CACnF,CAAC;AAEvB,6EAA6E;AAC7E,eAAO,MAAM,YAAY,GAAI,OAAM,gBAAqB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,IAAI,CACrE,CAAC"}
+{"version":3,"file":"floci-gcp.d.ts","sourceRoot":"","sources":["../../../src/op/activities/floci-gcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEpG,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAKD,eAAO,MAAM,cAAc,EAAE,YAM5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,kBAGhC,CAAC;AAIF,eAAO,MAAM,qBAAqB,0BAAoB,CAAC;AACvD,eAAO,MAAM,iBAAiB,0BAAgB,CAAC;AAC/C,eAAO,MAAM,iBAAiB,0BAAgB,CAAC;AAC/C,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,0BAAe,CAAC;AAC7C,eAAO,MAAM,kBAAkB,GAAI,OAAM,cAAmB,KAAG,MAA8B,CAAC;AAE9F,+EAA+E;AAC/E,eAAO,MAAM,UAAU,GAAI,OAAM,cAAmB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CACnF,CAAC;AAEvB,6EAA6E;AAC7E,eAAO,MAAM,YAAY,GAAI,OAAM,gBAAqB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,IAAI,CACrE,CAAC"}

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;AAqBjG,eAAO,MAAM,SAAS,EAAE,aAuXvB,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;AAuBjG,eAAO,MAAM,SAAS,EAAE,aAyXvB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.37.2",
+  "version": "0.38.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.37.2",
+    "@intentius/chant": "^0.38.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/read-client.ts

@@ -0,0 +1,129 @@
+/**
+ * GCP read transport (#1209) — the applier's own REST client, pointed at the
+ * read side.
+ *
+ * GCP applies cluster-free over direct REST (#706) and, until this, observed
+ * through a Config Connector cluster: `kubectl get <cnrm-gvk> -o json` per
+ * entity, on both the thin and the deep path. That split is what #1085's
+ * principle forbids — a lexicon should be observed on the transport it is
+ * applied with, or the two can disagree about what a resource even is — and it
+ * is what made GCP the heaviest of the three O slots.
+ *
+ * ## The URL comes from the applier, not from here
+ *
+ * Every GET is built by the same `ResourceMapper.plan()` the applier uses, and
+ * this module reads `plan().getUrl` rather than composing its own URL. That is
+ * deliberate: a reader that builds its own paths is a second, silently
+ * divergent opinion about where a resource lives, and the first symptom is a
+ * read that reports absent for something the applier just wrote. Reusing the
+ * mapper makes the two structurally incapable of disagreeing.
+ *
+ * ## What that bounds
+ *
+ * Coverage is exactly the applier's dispatch table (`MAPPERS`) — StorageBucket,
+ * PubSubTopic, PubSubSubscription, SecretManagerSecret, IAMServiceAccount,
+ * RunService. The kubectl path could fetch any CNRM kind the cluster knew
+ * about, so this is narrower on paper. It is not narrower in practice for
+ * anything chant can act on: a kind with no mapper cannot be applied either, so
+ * observing it produced a live tree nothing could ever reconcile against.
+ *
+ * A kind outside the table reports NOT-OBSERVED with `unsupported-kind` rather
+ * than being dropped, so the estate says "chant did not look at this" instead of
+ * quietly implying it is not there. Widening the table is #1209's stated
+ * non-goal and belongs with the applier.
+ */
+import { MAPPERS, type GcpResource, type ResourceMapper } from "../op/activities/gcp-apply";
+
+/** Where to read, and as whom. */
+export interface GcpReadClientOptions {
+  /** Endpoint override for every kind (floci-gcp `http://localhost:4588`). Omit for real GCP. */
+  endpoint?: string;
+  /** GCP project the resources live in. */
+  project: string;
+  /** Injectable HTTP, so tests never touch the network. */
+  http?: GcpReadHttp;
+}
+
+/** Injectable HTTP client — mirrors the applier's `GcpHttp`. */
+export type GcpReadHttp = (method: string, url: string) => Promise<{ status: number; text: string }>;
+
+const defaultHttp: GcpReadHttp = async (method, url) => {
+  const res = await fetch(url, { method });
+  return { status: res.status, text: await res.text() };
+};
+
+/**
+ * A read that failed for a reason the caller must classify — carries the HTTP
+ * status so a 404 (absent) is told apart from a 401/403 (no credentials) and a
+ * 5xx/network error (could not look). Mirrors `AzureReadError`.
+ */
+export class GcpReadError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "GcpReadError";
+  }
+}
+
+/** A 404 — the resource is genuinely absent, which is an answer, not a failure. */
+export function isNotFound(err: unknown): boolean {
+  return err instanceof GcpReadError && err.status === 404;
+}
+
+/** The mapper for a CNRM kind, or undefined when chant cannot act on it. */
+export function mapperForKind(kind: string): ResourceMapper | undefined {
+  return MAPPERS[kind];
+}
+
+/**
+ * GET one resource on the applier's transport.
+ *
+ * `declared` is the entity's own declared spec, which is what `plan()` needs to
+ * build a URL — the same input the applier hands it. Returns the parsed body,
+ * or throws {@link GcpReadError} carrying the status.
+ */
+export async function getResource(
+  client: GcpReadClientOptions,
+  kind: string,
+  name: string,
+  declared?: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const mapper = mapperForKind(kind);
+  if (!mapper) throw new GcpReadError(`no REST mapper for kind ${kind}`);
+
+  const base = (client.endpoint ?? mapper.defaultHost).replace(/\/$/, "");
+  const resource: GcpResource = {
+    kind,
+    metadata: { name },
+    spec: (declared?.spec as Record<string, unknown> | undefined) ?? declared ?? {},
+  };
+
+  let getUrl: string;
+  try {
+    getUrl = mapper.plan(resource, { base, project: client.project }).getUrl;
+  } catch (err) {
+    // A mapper that cannot plan from the declared spec cannot produce a URL, so
+    // there is nothing to read — a hole, never an absence.
+    throw new GcpReadError(`could not build a read URL for ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const http = client.http ?? defaultHttp;
+  let res: { status: number; text: string };
+  try {
+    res = await http("GET", getUrl);
+  } catch (err) {
+    throw new GcpReadError(err instanceof Error ? err.message : String(err));
+  }
+
+  if (res.status === 404) throw new GcpReadError(`${kind}/${name} not found`, 404);
+  if (res.status < 200 || res.status >= 300) {
+    throw new GcpReadError(`GET ${kind}/${name} failed with ${res.status}: ${res.text.slice(0, 200)}`, res.status);
+  }
+  try {
+    return JSON.parse(res.text) as Record<string, unknown>;
+  } catch {
+    throw new GcpReadError(`GET ${kind}/${name} returned a non-JSON body`, res.status);
+  }
+}