@intentius/chant-lexicon-gcp 0.124.38 → 0.124.40

package/dist/op/activities/gcp-compute.js

@@ -14,9 +14,16 @@
  * backend service can point at a regional NEG.
  *
  * Inserts return a compute `Operation`, polled at its `selfLink` (rebased onto
- * the endpoint override, so floci-gcp answers). These kinds reconcile by
- * existence only: an existing resource is left as it is, since compute updates
- * need the live `fingerprint` and most of these fields are immutable.
+ * the endpoint override, so floci-gcp answers).
+ *
+ * An existing load balancer resource is compared with its desired body and
+ * updated in place where compute allows it (#4238): a backend service or URL
+ * map by PATCH with the live `fingerprint`, a proxy's URL map by `setUrlMap`,
+ * a forwarding rule's target by `setTarget`, labels by `setLabels` with the
+ * live `labelFingerprint`. A difference on a field compute can't change in
+ * place (anything on a serverless NEG, an address's IP) is reported as
+ * "replace required" and left alone. A network and a subnetwork still
+ * reconcile by existence only.
  */
 import { GCP_RESOURCE_OWNERSHIP_KEYS } from "../../ownership.js";
 import { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
@@ -326,7 +333,83 @@ export const computeOperation = {
         return errors?.length ? errors.map((e) => e.message ?? e.code ?? "error").join("; ") : undefined;
     },
 };
-function computeMapper(kind, collection, build, regionalCollection = collection, scopeFor = (spec) => scopeOf(spec)) {
+/** A compute reference with everything before `projects/` dropped, so a full URL and a partial one compare equal. */
+function refTail(v) {
+    const at = v.indexOf("projects/");
+    return at >= 0 ? v.slice(at) : v;
+}
+/**
+ * True when the live value holds the desired one: every desired key is set
+ * live to an equal value, arrays element by element, and a compute URL
+ * equals its partial form. Fields only the live side has (defaults, server
+ * ids) don't count. Pure.
+ */
+export function holds(desired, live) {
+    if (typeof desired === "string" && typeof live === "string") {
+        return desired === live || (desired.includes("projects/") && refTail(desired) === refTail(live));
+    }
+    if (Array.isArray(desired)) {
+        return Array.isArray(live) && desired.length === live.length && desired.every((d, i) => holds(d, live[i]));
+    }
+    if (isObj(desired)) {
+        return isObj(live) && Object.entries(desired).every(([k, v]) => holds(v, live[k]));
+    }
+    return desired === live;
+}
+/** The desired body's top-level fields the live resource doesn't hold, `name` aside. Pure. */
+export function changedFields(desired, live) {
+    return Object.keys(desired).filter((k) => k !== "name" && !holds(desired[k], live[k]));
+}
+const replace = (kind, fields) => ({
+    replace: `${fields.join(", ")} differ${fields.length === 1 ? "s" : ""}, and compute can't change ${fields.length === 1 ? "it" : "them"} on a ${kind} in place`,
+});
+/** `labels` by `setLabels` with the live `labelFingerprint`; anything else changed is a replace. */
+function labelsOnly(kind) {
+    return async ({ url, desired, live, changed }) => {
+        const other = changed.filter((f) => f !== "labels");
+        if (other.length)
+            return replace(kind, other);
+        if (!changed.length)
+            return { requests: [] };
+        return { requests: [{ method: "POST", url: `${url}/setLabels`, body: { labels: desired.labels, labelFingerprint: live.labelFingerprint } }] };
+    };
+}
+/** Every changed field by one PATCH carrying the live `fingerprint` (backend services, URL maps). */
+const patchWithFingerprint = async ({ url, desired, live, changed }) => changed.length ? { requests: [{ method: "PATCH", url, body: { ...desired, fingerprint: live.fingerprint } }] } : { requests: [] };
+const reconcileProxy = async ({ url, desired, changed }) => {
+    const other = changed.filter((f) => f !== "urlMap");
+    if (other.length)
+        return replace("ComputeTargetHTTPProxy", other);
+    return changed.length ? { requests: [{ method: "POST", url: `${url}/setUrlMap`, body: { urlMap: desired.urlMap } }] } : { requests: [] };
+};
+/**
+ * A forwarding rule's `IPAddress` is a declared address's partial URL, where
+ * the live rule holds the IP itself, so the address is read and its IP
+ * compared. The target changes by `setTarget`, labels by `setLabels`; any
+ * other field is a replace.
+ */
+const reconcileForwardingRule = async ({ url, desired, live, changed, ctx, http, signal }) => {
+    let fields = changed;
+    const ip = desired.IPAddress;
+    if (fields.includes("IPAddress") && typeof ip === "string" && ip.includes("/addresses/")) {
+        const res = await http("GET", `${ctx.base}/compute/v1/${refTail(ip)}`, undefined, signal);
+        const address = res.status === 200 ? JSON.parse(res.text).address : undefined;
+        if (address !== undefined && address === live.IPAddress)
+            fields = fields.filter((f) => f !== "IPAddress");
+    }
+    const other = fields.filter((f) => f !== "target" && f !== "labels");
+    if (other.length)
+        return replace("ComputeForwardingRule", other);
+    const requests = [];
+    if (fields.includes("target"))
+        requests.push({ method: "POST", url: `${url}/setTarget`, body: { target: desired.target } });
+    if (fields.includes("labels")) {
+        requests.push({ method: "POST", url: `${url}/setLabels`, body: { labels: desired.labels, labelFingerprint: live.labelFingerprint } });
+    }
+    return { requests };
+};
+const replaceOnAnyChange = (kind) => async ({ changed }) => (changed.length ? replace(kind, changed) : { requests: [] });
+function computeMapper(kind, collection, build, regionalCollection = collection, scopeFor = (spec) => scopeOf(spec), reconcile) {
     return {
         kind,
         defaultHost: COMPUTE_HOST,
@@ -335,15 +418,28 @@ function computeMapper(kind, collection, build, regionalCollection = collection,
             const scope = scopeFor(resource.spec);
             const coll = `${ctx.base}/compute/v1/${scopePath(ctx.project, scope)}/${scope === "global" ? collection : regionalCollection}`;
             const name = computeName(resource);
-            return { getUrl: `${coll}/${enc(name)}`, create: { method: "POST", url: coll, body: build(resource, ctx) } };
+            const url = `${coll}/${enc(name)}`;
+            const desired = build(resource, ctx);
+            return {
+                getUrl: url,
+                create: { method: "POST", url: coll, body: desired },
+                ...(reconcile
+                    ? {
+                        reconcile: (live, http, signal) => {
+                            const l = isObj(live) ? live : {};
+                            return reconcile({ url, desired, live: l, changed: changedFields(desired, l), ctx, http, signal });
+                        },
+                    }
+                    : {}),
+            };
         },
     };
 }
-export const computeAddressMapper = computeMapper("ComputeAddress", "addresses", addressBody);
-export const regionNetworkEndpointGroupMapper = computeMapper("ComputeRegionNetworkEndpointGroup", "networkEndpointGroups", negBody);
-export const backendServiceMapper = computeMapper("ComputeBackendService", "backendServices", backendServiceBody);
-export const urlMapMapper = computeMapper("ComputeURLMap", "urlMaps", urlMapBody);
-export const targetHttpProxyMapper = computeMapper("ComputeTargetHTTPProxy", "targetHttpProxies", targetHttpProxyBody);
-export const forwardingRuleMapper = computeMapper("ComputeForwardingRule", "forwardingRules", forwardingRuleBody);
+export const computeAddressMapper = computeMapper("ComputeAddress", "addresses", addressBody, undefined, undefined, labelsOnly("ComputeAddress"));
+export const regionNetworkEndpointGroupMapper = computeMapper("ComputeRegionNetworkEndpointGroup", "networkEndpointGroups", negBody, undefined, undefined, replaceOnAnyChange("ComputeRegionNetworkEndpointGroup"));
+export const backendServiceMapper = computeMapper("ComputeBackendService", "backendServices", backendServiceBody, undefined, undefined, patchWithFingerprint);
+export const urlMapMapper = computeMapper("ComputeURLMap", "urlMaps", urlMapBody, undefined, undefined, patchWithFingerprint);
+export const targetHttpProxyMapper = computeMapper("ComputeTargetHTTPProxy", "targetHttpProxies", targetHttpProxyBody, undefined, undefined, reconcileProxy);
+export const forwardingRuleMapper = computeMapper("ComputeForwardingRule", "forwardingRules", forwardingRuleBody, undefined, undefined, reconcileForwardingRule);
 export const networkMapper = computeMapper("ComputeNetwork", "networks", networkBody, "networks", () => "global");
 export const subnetworkMapper = computeMapper("ComputeSubnetwork", "subnetworks", subnetworkBody);

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -368,8 +368,12 @@ export const bucket = new StorageBucket({
         return observeResourcesDeepGcp(options);
     },
     deepNormalizationHooks: gcpDeepNormalizationHooks,
-    /** Runtime health (#4177): Cloud Run services. Implementation in ./health.ts. */
-    healthTypes: ["GCP::Run::Service"],
+    /**
+     * Runtime health (#4177, #4239): Cloud Run services, backend services and IAM
+     * policy members. Implementation in ./health.ts, whose GCP_HEALTH_TYPES this
+     * list matches; written out so the build never imports the reader.
+     */
+    healthTypes: ["GCP::Run::Service", "GCP::Compute::BackendService", "GCP::Iam::PolicyMember"],
     async observeHealth(options) {
         const { observeHealthGcp } = await import("./health.js");
         return observeHealthGcp(options);

package/dist/skills/chant-gcp.md

@@ -202,6 +202,8 @@ Composites group related Config Connector resources with secure defaults. Each r
 | `ManagedCertificate` | ComputeManagedSslCertificate | Auto-renewal via Google-managed cert |
 | `SecureProject` | Project + IAMAuditConfig + essential Service resources | Audit logging, required APIs enabled, org policy constraints |
 | `GpuNodePool` | ContainerNodePool with GPU accelerators | Scale-to-zero, nvidia.com/gpu taint, GKE metadata workload identity |
+| `PrivateEgressNetwork` | ComputeNetwork + ComputeSubnetwork | Custom mode, regional routing, Private Google Access |
+| `PublicCloudRun` | IAMServiceAccount + RunService + serverless NEG + global external Application Load Balancer | Own service account, Direct VPC egress for private ranges, optional managed certificate with HTTP to HTTPS redirect, optional Cloud Armor policy |
 
 ### Example: GKE cluster with secure defaults
 

package/package.json

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

package/src/api/read-client.ts

@@ -98,6 +98,28 @@ export function mapperForKind(kind: string): ResourceMapper | undefined {
  * build a URL — the same input the applier hands it. Returns the parsed body,
  * or throws {@link GcpReadError} carrying the status.
  */
+/**
+ * The URL a read of this resource GETs: the applier's own `plan().getUrl`, so
+ * a health read's sub-calls (`getHealth`) land on the same resource path.
+ * Throws a {@link GcpReadError} when the declared spec can't produce one,
+ * which is a hole, never an absence.
+ */
+export function readUrl(client: GcpReadClientOptions, kind: string, name: string, declared?: Record<string, unknown>): string {
+  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 ?? {},
+  };
+  try {
+    return mapper.plan(resource, { base, project: client.project, ...(client.manifest ? { manifest: client.manifest } : {}) }).getUrl;
+  } catch (err) {
+    throw new GcpReadError(`could not build a read URL for ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 export async function getResource(
   client: GcpReadClientOptions,
   kind: string,
@@ -128,14 +150,7 @@ export async function getResource(
       throw new GcpReadError(`could not read ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
     }
   } else {
-    let getUrl: string;
-    try {
-      getUrl = mapper.plan(resource, ctx).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 getUrl = readUrl(client, kind, name, declared);
     try {
       res = await http("GET", getUrl);
     } catch (err) {

package/src/components/capability-plugin.ts

@@ -0,0 +1,25 @@
+/**
+ * `gcpCapabilityPlugin`: the gcp lexicon's capability plugin (#4273). Core
+ * loads it when a project's `chant.config.ts` lists `lexicons: ["gcp"]`, so a
+ * component's `gcp-apply` step resolves, plans in `chant components pr-plan`
+ * and runs.
+ */
+
+import type { Capability } from "@intentius/chant/components/capability";
+import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { gcpApplyCapability } from "./gcp-apply";
+
+/** The GCP verb families this plugin contributes. */
+export const GCP_VERB_FAMILIES = {
+  apply: ["gcp-apply"],
+} as const;
+
+/** The gcp lexicon's capability plugin. */
+export const gcpCapabilityPlugin: CapabilityPlugin = {
+  name: "gcp",
+  get version(): string {
+    return ownPackageVersion(import.meta.url);
+  },
+  capabilities: () => [gcpApplyCapability] as unknown as Array<Capability<never, unknown>>,
+  families: () => GCP_VERB_FAMILIES,
+};

package/src/components/gcp-apply-floci.e2e.test.ts

@@ -0,0 +1,80 @@
+/**
+ * `gcp-apply`'s plan and apply against floci-gcp (#4273), over real HTTP.
+ * Set CHANT_FLOCI_GCP_ENDPOINT to a running floci-gcp, for example
+ * `docker run -d -p 4688:4588 floci/floci-gcp:0.5.0` and
+ * `CHANT_FLOCI_GCP_ENDPOINT=http://localhost:4688`. Skipped without it.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gcpDelete } from "../op/activities/gcp-apply";
+import { createGcpApplyCapability, GcpPlanMovedError } from "./gcp-apply";
+
+const endpoint = process.env.CHANT_FLOCI_GCP_ENDPOINT;
+
+describe.skipIf(!endpoint)("gcp-apply plan against floci-gcp (#4273)", () => {
+  const suffix = `${process.pid}-${Date.now()}`;
+  const ctx = { env: "local", component: "gcp-e2e" };
+  const saved = { ...process.env };
+  let dir: string;
+  let manifest: string;
+  const bucket = (storageClass: string) => ({
+    apiVersion: "storage.cnrm.cloud.google.com/v1beta1",
+    kind: "StorageBucket",
+    metadata: { name: `chant-plan-${suffix}` },
+    spec: { location: "US", storageClass },
+  });
+  const topic = { apiVersion: "pubsub.cnrm.cloud.google.com/v1beta1", kind: "PubSubTopic", metadata: { name: `chant-plan-${suffix}` }, spec: {} };
+  const write = (resources: unknown[]): void => writeFileSync(manifest, JSON.stringify(resources));
+
+  beforeAll(() => {
+    Object.assign(process.env, { GCP_ENDPOINT_URL: endpoint, GCP_PROJECT_ID: "floci-local" });
+    dir = mkdtempSync(join(tmpdir(), "gcp-apply-floci-"));
+    manifest = join(dir, "manifest.json");
+  });
+
+  afterAll(async () => {
+    try {
+      write([bucket("STANDARD"), topic]);
+      await gcpDelete({ manifestPath: manifest });
+    } finally {
+      process.env = saved;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("plans a create, applies it, plans no change, plans an update and refuses a plan the manifest moved past", async () => {
+    const capability = createGcpApplyCapability();
+
+    write([bucket("STANDARD"), topic]);
+    const created = await capability.plan!(ctx, { manifest });
+    expect(created.changeSet!.entries.map((e) => [e.type, e.action])).toEqual([
+      ["PubSubTopic", "create"],
+      ["StorageBucket", "create"],
+    ]);
+    const first = await capability.run({ ...ctx, plans: { [ctx.component]: created.artifact } }, { manifest });
+    expect(first.applied.map((a) => a.created)).toEqual([true, true]);
+
+    const same = await capability.plan!(ctx, { manifest });
+    expect(same.changeSet!.entries.map((e) => e.action)).toEqual(["no-op", "no-op"]);
+    expect(same.changeSet!.member.holes).toEqual([]);
+
+    write([bucket("NEARLINE"), topic]);
+    const updated = await capability.plan!(ctx, { manifest });
+    expect(updated.changeSet!.entries.filter((e) => e.action !== "no-op").map((e) => [e.type, e.action, e.attributes.map((a) => a.path)])).toEqual([
+      ["StorageBucket", "update", ["storageClass"]],
+    ]);
+
+    write([bucket("COLDLINE"), topic]);
+    await expect(capability.run({ ...ctx, plans: { [ctx.component]: updated.artifact } }, { manifest })).rejects.toBeInstanceOf(GcpPlanMovedError);
+
+    write([bucket("NEARLINE"), topic]);
+    const second = await capability.run({ ...ctx, plans: { [ctx.component]: updated.artifact } }, { manifest });
+    expect(second.applied.find((a) => a.kind === "StorageBucket")).toMatchObject({ created: false, updated: true });
+
+    const after = await capability.plan!(ctx, { manifest });
+    expect(after.changeSet!.entries.map((e) => e.action)).toEqual(["no-op", "no-op"]);
+  }, 120_000);
+});

package/src/components/gcp-apply.test.ts

@@ -0,0 +1,259 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isCapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { buildCapabilityRegistry } from "@intentius/chant/components/capability-plugin-loader";
+import { isPlanMovedError } from "@intentius/chant/components/capability";
+import type { GcpHttp } from "../op/activities/gcp-apply";
+import { createGcpApplyCapability, GcpPlanMovedError, readOnlyHttp } from "./gcp-apply";
+import { gcpCapabilityPlugin } from "./capability-plugin";
+
+/**
+ * An in-memory GCP behind the applier's REST paths: buckets, topics and
+ * Cloud Run services, keyed by URL path. Records every request.
+ */
+function fakeGcp() {
+  const store = new Map<string, Record<string, unknown>>();
+  const calls: Array<{ method: string; url: string }> = [];
+  const http: GcpHttp = async (method, url, body) => {
+    calls.push({ method, url });
+    const u = new URL(url);
+    const path = u.pathname;
+    const b = (body ?? {}) as Record<string, unknown>;
+    const found = (p: string) => (store.has(p) ? { status: 200, text: JSON.stringify(store.get(p)) } : { status: 404, text: "not found" });
+    if (method === "GET") {
+      if (path.endsWith("/storage/v1/b")) {
+        return { status: 200, text: JSON.stringify({ items: [...store.entries()].filter(([k]) => k.startsWith("/storage/v1/b/")).map(([, v]) => v) }) };
+      }
+      if (path.includes("/operations/")) return { status: 200, text: JSON.stringify({ done: true }) };
+      return found(path);
+    }
+    if (method === "POST" && path.endsWith("/storage/v1/b")) {
+      store.set(`${path}/${b.name as string}`, { ...b });
+      return { status: 200, text: JSON.stringify(b) };
+    }
+    if (method === "POST" && path.endsWith("/services")) {
+      const id = u.searchParams.get("serviceId")!;
+      store.set(`${path}/${id}`, { ...b, name: id, uri: `https://${id}-abc.a.run.app` });
+      return { status: 200, text: JSON.stringify({ name: "projects/p/locations/us-central1/operations/op1" }) };
+    }
+    if (method === "PUT") {
+      store.set(path, { ...b, name: path.split("/").pop() });
+      return { status: 200, text: JSON.stringify(b) };
+    }
+    if (method === "PATCH") {
+      const patch = (b.topic ?? b) as Record<string, unknown>;
+      store.set(path, { ...store.get(path), ...patch });
+      return { status: 200, text: JSON.stringify(store.get(path)) };
+    }
+    if (method === "DELETE") {
+      store.delete(path);
+      return { status: 200, text: "{}" };
+    }
+    return { status: 400, text: `unhandled ${method} ${url}` };
+  };
+  return { store, calls, http, writes: () => calls.filter((c) => c.method !== "GET") };
+}
+
+const bucket = (name: string, storageClass = "STANDARD") => ({
+  apiVersion: "storage.cnrm.cloud.google.com/v1beta1",
+  kind: "StorageBucket",
+  metadata: { name, annotations: { "cnrm.cloud.google.com/project-id": "test-project" } },
+  spec: { location: "us-central1", storageClass },
+});
+const topic = { apiVersion: "pubsub.cnrm.cloud.google.com/v1beta1", kind: "PubSubTopic", metadata: { name: "events" }, spec: {} };
+const service = {
+  apiVersion: "run.cnrm.cloud.google.com/v1beta1",
+  kind: "RunService",
+  metadata: { name: "web" },
+  spec: { location: "us-central1", template: { containers: [{ image: "us-docker.pkg.dev/test/web:1" }] } },
+};
+
+const ctx = { env: "test", component: "gcp-app" };
+const ENV_KEYS = ["GCP_ENDPOINT_URL", "GCP_PROJECT_ID", "GOOGLE_CLOUD_PROJECT"] as const;
+
+describe("gcp-apply (#4273)", () => {
+  let dir: string;
+  let manifest: string;
+  const saved: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>> = {};
+  const write = (resources: unknown[]): void => writeFileSync(manifest, JSON.stringify(resources));
+
+  beforeEach(() => {
+    for (const k of ENV_KEYS) saved[k] = process.env[k];
+    process.env.GCP_ENDPOINT_URL = "http://floci.test:4588";
+    process.env.GCP_PROJECT_ID = "test-project";
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+    dir = mkdtempSync(join(tmpdir(), "gcp-apply-step-"));
+    manifest = join(dir, "manifest.json");
+  });
+
+  afterEach(() => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("plans creates without writing, applies them, then plans no change with the Cloud Run URL known", async () => {
+    const gcp = fakeGcp();
+    const capability = createGcpApplyCapability(gcp.http);
+    write([bucket("assets"), topic, service]);
+
+    const first = await capability.plan!(ctx, { manifest });
+    expect(gcp.writes()).toEqual([]);
+    expect(first.member).toBe("gcp-app");
+    expect(first.changeSet!.entries.map((e) => [e.address, e.action])).toEqual([
+      ["PubSubTopic/events", "create"],
+      ["RunService/web", "create"],
+      ["StorageBucket/assets", "create"],
+    ]);
+    expect(first.changeSet!.entries.every((e) => e.lexicon === "gcp" && e.planner === "chant" && e.scope === "test-project")).toBe(true);
+    expect(first.outputs).toEqual({ known: {}, unknown: ["webUri"] });
+    // Every read went to the endpoint override.
+    expect(gcp.calls.every((c) => c.url.startsWith("http://floci.test:4588/"))).toBe(true);
+
+    const applied = await capability.run({ ...ctx, plans: { "gcp-app": first.artifact } }, { manifest });
+    expect(applied.applied.map((a) => [a.kind, a.created])).toEqual([
+      ["StorageBucket", true],
+      ["PubSubTopic", true],
+      ["RunService", true],
+    ]);
+    expect(applied.outputs).toEqual({ webUri: "https://web-abc.a.run.app" });
+
+    const second = await capability.plan!(ctx, { manifest });
+    expect(second.changeSet!.entries.map((e) => e.action)).toEqual(["no-op", "no-op", "no-op"]);
+    expect(second.outputs).toEqual({ known: { webUri: "https://web-abc.a.run.app" }, unknown: [] });
+    await expect(capability.outputs!(ctx, { manifest })).resolves.toEqual({ webUri: "https://web-abc.a.run.app" });
+
+    // Applying again agrees with the plan: nothing is sent.
+    const before = gcp.writes().length;
+    const again = await capability.run(ctx, { manifest });
+    expect(again.applied.every((a) => !a.created && !a.updated)).toBe(true);
+    expect(gcp.writes().length).toBe(before);
+  });
+
+  test("an update names each changed field with its value before and after, and run refuses a plan the manifest moved past", async () => {
+    const gcp = fakeGcp();
+    const capability = createGcpApplyCapability(gcp.http);
+    write([bucket("assets")]);
+    await capability.run(ctx, { manifest });
+
+    write([bucket("assets", "NEARLINE")]);
+    const plan = await capability.plan!(ctx, { manifest });
+    expect(plan.changeSet!.entries).toEqual([
+      expect.objectContaining({
+        address: "StorageBucket/assets",
+        action: "update",
+        disruption: "in-place",
+        attributes: [{ path: "storageClass", before: "STANDARD", after: "NEARLINE" }],
+      }),
+    ]);
+
+    write([bucket("assets", "COLDLINE")]);
+    const moved = capability.run({ ...ctx, plans: { "gcp-app": plan.artifact } }, { manifest });
+    await expect(moved).rejects.toBeInstanceOf(GcpPlanMovedError);
+    await expect(moved).rejects.toSatisfy(isPlanMovedError);
+    expect(gcp.store.get("/storage/v1/b/assets")!.storageClass).toBe("STANDARD");
+
+    write([bucket("assets", "NEARLINE")]);
+    const done = await capability.run({ ...ctx, plans: { "gcp-app": plan.artifact } }, { manifest });
+    expect(done.applied).toEqual([{ kind: "StorageBucket", name: "assets", created: false, updated: true }]);
+  });
+
+  test("with prune, a chant-owned bucket the manifest dropped is a delete and a foreign one is left out", async () => {
+    const gcp = fakeGcp();
+    const capability = createGcpApplyCapability(gcp.http);
+    write([bucket("keep"), bucket("old")]);
+    await capability.run(ctx, { manifest });
+    gcp.store.set("/storage/v1/b/foreign", { name: "foreign", labels: {} });
+
+    write([bucket("keep")]);
+    const plan = await capability.plan!(ctx, { manifest, prune: true });
+    expect(plan.changeSet!.entries.map((e) => [e.address, e.action, e.disruption])).toEqual([
+      ["StorageBucket/keep", "no-op", undefined],
+      ["StorageBucket/old", "delete", "destroy"],
+    ]);
+  });
+
+  test("a kind with no mapper, and a read that is neither 200 nor 404, are holes", async () => {
+    const http: GcpHttp = async () => ({ status: 403, text: "denied" });
+    const capability = createGcpApplyCapability(http);
+    write([bucket("assets"), { kind: "SQLInstance", metadata: { name: "db" }, spec: {} }]);
+    const plan = await capability.plan!(ctx, { manifest });
+    expect(plan.changeSet!.entries).toEqual([]);
+    expect(plan.changeSet!.member.holes.map((h) => h.address)).toEqual(["StorageBucket/assets", "SQLInstance/db"]);
+    expect(plan.changeSet!.member.holes[0]!.reason).toMatch(/answered 403/);
+    expect(plan.changeSet!.member.holes[1]!.reason).toMatch(/no REST mapper for SQLInstance/);
+  });
+
+  test("inputs waiting on another component read nothing and leave a hole", async () => {
+    const gcp = fakeGcp();
+    const capability = createGcpApplyCapability(gcp.http);
+    const plan = await capability.plan!({ ...ctx, unresolvedInputs: ["network"] }, { manifest: join(dir, "not-built.json") });
+    expect(gcp.calls).toEqual([]);
+    expect(plan.artifact).toBeUndefined();
+    expect(plan.changeSet!.member.holes).toEqual([{ address: "gcp-app", type: "gcp-apply", reason: "inputs from network; re-checked on apply" }]);
+  });
+
+  test("the project follows projectRef.external, then the annotation, then GCP_PROJECT_ID, then GOOGLE_CLOUD_PROJECT", async () => {
+    const gcp = fakeGcp();
+    const capability = createGcpApplyCapability(gcp.http);
+    const named = (name: string, extra: Record<string, unknown>) => ({ kind: "PubSubTopic", metadata: { name, ...extra }, spec: {} });
+    write([
+      { kind: "PubSubTopic", metadata: { name: "a", annotations: { "cnrm.cloud.google.com/project-id": "annotated" } }, spec: { projectRef: { external: "projects/from-ref" } } },
+      named("b", { annotations: { "cnrm.cloud.google.com/project-id": "annotated" } }),
+      named("c", {}),
+    ]);
+    await capability.plan!(ctx, { manifest });
+    delete process.env.GCP_PROJECT_ID;
+    process.env.GOOGLE_CLOUD_PROJECT = "cloud-project";
+    write([named("d", {})]);
+    await capability.plan!(ctx, { manifest });
+    expect(gcp.calls.map((c) => new URL(c.url).pathname)).toEqual([
+      "/v1/projects/from-ref/topics/a",
+      "/v1/projects/annotated/topics/b",
+      "/v1/projects/test-project/topics/c",
+      "/v1/projects/cloud-project/topics/d",
+    ]);
+  });
+
+  test("the step's endpoint wins over GCP_ENDPOINT_URL and enters the plan digest", async () => {
+    const gcp = fakeGcp();
+    const capability = createGcpApplyCapability(gcp.http);
+    write([topic]);
+    const viaEnv = await capability.plan!(ctx, { manifest });
+    const viaStep = await capability.plan!(ctx, { manifest, endpoint: "http://localhost:4599" });
+    expect(gcp.calls.map((c) => new URL(c.url).origin)).toEqual(["http://floci.test:4588", "http://localhost:4599"]);
+    expect(viaStep.planDigest).not.toBe(viaEnv.planDigest);
+  });
+
+  test("the plan's HTTP refuses a write, and lets a policy read through", async () => {
+    const seen: string[] = [];
+    const read = readOnlyHttp(async (method, url) => {
+      seen.push(`${method} ${url}`);
+      return { status: 200, text: "{}" };
+    });
+    await expect(read("PATCH", "http://x/b/assets", {})).rejects.toThrow(/a plan only reads/);
+    await expect(read("POST", "http://x/v1/projects/p/serviceAccounts", {})).rejects.toThrow(/a plan only reads/);
+    await read("POST", "http://x/v1/projects/p/topics/t:getIamPolicy", {});
+    await read("GET", "http://x/b/assets");
+    expect(seen).toEqual(["POST http://x/v1/projects/p/topics/t:getIamPolicy", "GET http://x/b/assets"]);
+  });
+});
+
+describe("gcpCapabilityPlugin (#4273)", () => {
+  test("satisfies the CapabilityPlugin contract and contributes gcp-apply with plan and outputs", () => {
+    expect(isCapabilityPlugin(gcpCapabilityPlugin)).toBe(true);
+    const [step] = gcpCapabilityPlugin.capabilities();
+    expect(step!.kind).toBe("gcp-apply");
+    expect(typeof step!.plan).toBe("function");
+    expect(typeof step!.outputs).toBe("function");
+  });
+
+  test("a project listing the gcp lexicon gets gcp-apply in its registry", async () => {
+    const registry = await buildCapabilityRegistry({ lexicons: ["gcp"] });
+    expect(registry.has("gcp-apply")).toBe(true);
+  });
+});