@intentius/chant-lexicon-gcp 0.124.33 → 0.124.35

package/src/deep-observe.ts

@@ -182,9 +182,133 @@ const CNRM_REFINERS: Record<string, (tree: CnrmTree, ctx: RefineContext) => void
     // name. The declared side writes it as `location`.
     const m = ctx.restName ? /\/locations\/([^/]+)\//.exec(ctx.restName) : null;
     if (m) tree.location = m[1];
+    // #4240: v2 returns the account as an email; the declared side writes a
+    // `serviceAccountRef`, `name` for an account in the project.
+    const template = tree.template as Record<string, unknown> | undefined;
+    if (template && typeof template.serviceAccount === "string") {
+      const email = template.serviceAccount;
+      const suffix = `@${ctx.project}.iam.gserviceaccount.com`;
+      template.serviceAccountRef = email.endsWith(suffix) ? { name: email.slice(0, -suffix.length) } : { external: email };
+      delete template.serviceAccount;
+    }
+  },
+  // #4233: the inverse of gcp-compute.ts's body builders. Compute returns refs
+  // as full URLs and a region as a URL; CNRM writes `*Ref: { name }` and a
+  // bare `location` (`"global"` when the resource has no region).
+  IAMPolicyMember(tree) {
+    delete tree.etag;
+    delete tree.resource;
+  },
+  ComputeAddress(tree) {
+    computeLocation(tree);
+  },
+  ComputeRegionNetworkEndpointGroup(tree) {
+    if (typeof tree.region === "string") tree.region = lastSegment(tree.region);
+    const cloudRun = tree.cloudRun as Record<string, unknown> | undefined;
+    if (cloudRun && typeof cloudRun.service === "string") {
+      cloudRun.serviceRef = { name: cloudRun.service };
+      delete cloudRun.service;
+    }
+  },
+  ComputeBackendService(tree) {
+    computeLocation(tree);
+    if (tree.enableCDN !== undefined) {
+      tree.enableCdn = tree.enableCDN;
+      delete tree.enableCDN;
+    }
+    const draining = tree.connectionDraining as { drainingTimeoutSec?: unknown } | undefined;
+    if (draining) {
+      if (draining.drainingTimeoutSec !== undefined) tree.connectionDrainingTimeoutSec = draining.drainingTimeoutSec;
+      delete tree.connectionDraining;
+    }
+    if (Array.isArray(tree.backends)) {
+      tree.backend = (tree.backends as Array<Record<string, unknown>>).map((b) => {
+        const { group, ...rest } = b;
+        return { ...rest, ...(typeof group === "string" ? { group: refOf(group) } : {}) };
+      });
+      delete tree.backends;
+    }
+    if (Array.isArray(tree.healthChecks)) {
+      tree.healthChecks = (tree.healthChecks as unknown[]).map((h) => (typeof h === "string" ? { healthCheckRef: { name: lastSegment(h) } } : h));
+    }
+    if (typeof tree.securityPolicy === "string") {
+      tree.securityPolicyRef = { name: lastSegment(tree.securityPolicy) };
+      delete tree.securityPolicy;
+    }
+  },
+  ComputeURLMap(tree) {
+    computeLocation(tree);
+    if (typeof tree.defaultService === "string") tree.defaultService = refOf(tree.defaultService);
+    if (Array.isArray(tree.hostRules)) {
+      tree.hostRule = tree.hostRules;
+      delete tree.hostRules;
+    }
+    if (Array.isArray(tree.pathMatchers)) {
+      tree.pathMatcher = (tree.pathMatchers as Array<Record<string, unknown>>).map((m) => {
+        const { defaultService, pathRules, ...rest } = m;
+        return {
+          ...rest,
+          ...(typeof defaultService === "string" ? { defaultService: refOf(defaultService) } : {}),
+          ...(Array.isArray(pathRules)
+            ? {
+                pathRule: (pathRules as Array<Record<string, unknown>>).map(({ service, ...r }) => ({
+                  ...r,
+                  ...(typeof service === "string" ? { service: refOf(service) } : {}),
+                })),
+              }
+            : {}),
+        };
+      });
+      delete tree.pathMatchers;
+    }
+  },
+  ComputeTargetHTTPProxy(tree) {
+    computeLocation(tree);
+    if (typeof tree.urlMap === "string") {
+      tree.urlMapRef = { name: lastSegment(tree.urlMap) };
+      delete tree.urlMap;
+    }
   },
+  ComputeForwardingRule(tree) {
+    computeLocation(tree);
+    if (tree.IPProtocol !== undefined) {
+      tree.ipProtocol = tree.IPProtocol;
+      delete tree.IPProtocol;
+    }
+    if (typeof tree.target === "string") tree.target = refOf(tree.target);
+    if (typeof tree.backendService === "string") {
+      tree.backendServiceRef = { name: lastSegment(tree.backendService) };
+      delete tree.backendService;
+    }
+  },
+};
+
+function lastSegment(url: string): string {
+  return url.slice(url.lastIndexOf("/") + 1);
+}
+
+/** Compute's `region` URL as CNRM's `location`; no region means a global resource. */
+function computeLocation(tree: CnrmTree): void {
+  tree.location = typeof tree.region === "string" ? lastSegment(tree.region) : "global";
+  delete tree.region;
+}
+
+/** The `*Ref` a compute URL names, by its collection (`.../backendServices/web` -> `{ backendServiceRef: { name: "web" } }`). */
+const REF_KEY_BY_COLLECTION: Record<string, string> = {
+  networkEndpointGroups: "networkEndpointGroupRef",
+  backendServices: "backendServiceRef",
+  backendBuckets: "backendBucketRef",
+  targetHttpProxies: "targetHTTPProxyRef",
+  targetHttpsProxies: "targetHTTPSProxyRef",
+  instanceGroups: "instanceGroupRef",
 };
 
+function refOf(url: string): unknown {
+  const parts = url.split("/");
+  const key = REF_KEY_BY_COLLECTION[parts[parts.length - 2] ?? ""];
+  return key ? { [key]: { name: parts[parts.length - 1] } } : url;
+}
+
 /**
  * A REST payload as a CNRM-shaped property tree, in the declared side's
  * vocabulary. The generic reshape runs first, then the full resource path is
@@ -244,7 +368,7 @@ export async function observeResourcesDeepGcp(options: GcpDeepObserveOptions): P
     let client: GcpReadClientOptions;
     try {
       client = {
-        project: resolveReadProject(gvk.kind, name, metadata, manifestProjects),
+        project: resolveReadProject(gvk.kind, name, metadata, manifestProjects, props),
         ...(endpoint ? { endpoint } : {}),
       };
     } catch (err) {

package/src/describe-resources.test.ts

@@ -80,7 +80,7 @@ describe("gcp describeResources — direct REST (#1209)", () => {
 
   test("a kind the applier has no mapper for is unsupported-kind, not absent", async () => {
     const out = await read(
-      makeEntities([{ name: "e", entityType: "GCP::Compute::Address", props: { metadata: { name: "addr" } } }]),
+      makeEntities([{ name: "e", entityType: "GCP::Compute::Network", props: { metadata: { name: "net" } } }]),
     );
     expect(out.unobserved?.e?.reason).toBe("unsupported-kind");
     expect(fetchMock).not.toHaveBeenCalled();

package/src/describe-resources.ts

@@ -40,7 +40,7 @@ import type { ObservationResult, ResourceMetadata, UnobservedEntity } from "@int
 import { observation } from "@intentius/chant/observation";
 import { hasOwnershipMarker, classifyOwnership, readOwnership, type ChannelKeys } from "@intentius/chant/ownership";
 import { getResource, mapperForKind, GcpReadError, isNotFound, type GcpReadClientOptions } from "./api/read-client";
-import { resolveGcpProject, parseManifest } from "./op/activities/gcp-apply";
+import { resolveGcpProject, parseManifest, projectRefProject } from "./op/activities/gcp-apply";
 import { resolveGVK } from "./serializer";
 
 /**
@@ -105,7 +105,7 @@ export function manifestProjectAnnotations(buildOutput: string | undefined): Map
   if (!buildOutput) return out;
   try {
     for (const doc of parseManifest(buildOutput, "<build output>")) {
-      const project = doc.metadata?.annotations?.["cnrm.cloud.google.com/project-id"];
+      const project = projectRefProject(doc.spec) ?? doc.metadata?.annotations?.["cnrm.cloud.google.com/project-id"];
       if (doc.kind && doc.metadata?.name && typeof project === "string") {
         out.set(`${doc.kind}/${doc.metadata.name}`, project);
       }
@@ -119,8 +119,9 @@ export function manifestProjectAnnotations(buildOutput: string | undefined): Map
 }
 
 /**
- * The project a read should target: `GOOGLE_CLOUD_PROJECT` / the entity's own
- * annotation (via `resolveGcpProject`, the applier's rule), then the built
+ * The project a read should target: the entity's `projectRef.external`,
+ * `GOOGLE_CLOUD_PROJECT`, the entity's own annotation (via
+ * `resolveGcpProject`, the applier's rule), then the built
  * manifest's merged annotation. Throws the applier's own error when nothing
  * resolves, so the `no-binding` detail names both knobs.
  */
@@ -129,9 +130,10 @@ export function resolveReadProject(
   name: string,
   metadata: { annotations?: Record<string, string> } | undefined,
   manifestProjects: Map<string, string>,
+  props?: Record<string, unknown>,
 ): string {
   try {
-    return resolveGcpProject({ kind, metadata });
+    return resolveGcpProject({ kind, metadata, ...(props ? { spec: props } : {}) });
   } catch (err) {
     const fromManifest = manifestProjects.get(`${kind}/${name}`);
     if (fromManifest) return fromManifest;
@@ -230,7 +232,7 @@ export async function describeResources(options: {
     let client: GcpReadClientOptions;
     try {
       client = {
-        project: resolveReadProject(gvk.kind, name, metadata, manifestProjects),
+        project: resolveReadProject(gvk.kind, name, metadata, manifestProjects, props),
         ...(endpoint ? { endpoint } : {}),
       };
     } catch (err) {

package/src/health.ts

@@ -91,7 +91,7 @@ export async function observeHealthGcp(options: GcpHealthOptions): Promise<Healt
       }
       let project: string;
       try {
-        project = resolveReadProject(gvk.kind, name, metadata, manifestProjects);
+        project = resolveReadProject(gvk.kind, name, metadata, manifestProjects, props);
       } catch (err) {
         unobserved[entityName] = { type: entityType, reason: "no-binding", detail: err instanceof Error ? err.message : String(err) };
         return;

package/src/op/activities/gcp-apply.test.ts

@@ -5,6 +5,7 @@ import {
   bucketInsertBody,
   pubSubTopicBody,
   cloudRunServiceBody,
+  serviceAccountEmail,
   resolveGcpProject,
   resolveGcpEndpoint,
   applyResource,
@@ -118,6 +119,13 @@ describe("mappers build correct plans (#706)", () => {
 
   test("registry keys match each mapper's kind", () => {
     expect(Object.keys(MAPPERS).sort()).toEqual([
+      "ComputeAddress",
+      "ComputeBackendService",
+      "ComputeForwardingRule",
+      "ComputeRegionNetworkEndpointGroup",
+      "ComputeTargetHTTPProxy",
+      "ComputeURLMap",
+      "IAMPolicyMember",
       "IAMServiceAccount",
       "PubSubSubscription",
       "PubSubTopic",
@@ -136,6 +144,35 @@ describe("Cloud Run mapper + LRO (#706)", () => {
     });
   });
 
+  test("cloudRunServiceBody sends serviceAccountRef as template.serviceAccount (#4240)", () => {
+    const withRef = (ref: Record<string, string>) => ({
+      ...RUN_SERVICE,
+      spec: { ...(RUN_SERVICE.spec as object), template: { containers: [{ image: "gcr.io/x/hello" }], serviceAccountRef: ref } },
+    });
+    expect(cloudRunServiceBody(withRef({ name: "run-sa" }), "p")).toEqual({
+      template: { containers: [{ image: "gcr.io/x/hello" }], serviceAccount: "run-sa@p.iam.gserviceaccount.com" },
+    });
+    expect(cloudRunServiceBody(withRef({ external: "x@other.iam.gserviceaccount.com" }), "p")).toEqual({
+      template: { containers: [{ image: "gcr.io/x/hello" }], serviceAccount: "x@other.iam.gserviceaccount.com" },
+    });
+  });
+
+  test("serviceAccountEmail: external as given or from a path, name in the project", () => {
+    expect(serviceAccountEmail({ external: "projects/o/serviceAccounts/x@o.iam.gserviceaccount.com" })).toBe("x@o.iam.gserviceaccount.com");
+    expect(serviceAccountEmail({ name: "run-sa" }, "p")).toBe("run-sa@p.iam.gserviceaccount.com");
+    expect(serviceAccountEmail(undefined, "p")).toBeUndefined();
+    expect(() => serviceAccountEmail({ name: "run-sa" })).toThrow(/needs a project/);
+  });
+
+  test("RunService plan sends the service account email on create and update", () => {
+    const resource = {
+      ...RUN_SERVICE,
+      spec: { ...(RUN_SERVICE.spec as object), template: { containers: [{ image: "i" }], serviceAccountRef: { name: "run-sa" } } },
+    };
+    const plan = cloudRunServiceMapper.plan(resource, { base: "http://x", project: "p" });
+    expect((plan.create.body as { template: { serviceAccount: string } }).template.serviceAccount).toBe("run-sa@p.iam.gserviceaccount.com");
+  });
+
   test("RunService plan → POST v2 services?serviceId, async operation present", () => {
     const plan = cloudRunServiceMapper.plan(RUN_SERVICE, { base: "http://x", project: "p" });
     expect(plan.getUrl).toBe("http://x/v2/projects/p/locations/us-central1/services/hello-svc");
@@ -234,6 +271,22 @@ describe("resolveGcpProject (#711)", () => {
     expect(() => resolveGcpProject({ metadata: { name: "b" } }, {} as NodeJS.ProcessEnv))
       .toThrow(/no GCP project/);
   });
+
+  test("spec.projectRef.external wins over env and the annotation (#4201)", () => {
+    const run = { ...BUCKET, spec: { projectRef: { external: "ref-project" } } };
+    expect(resolveGcpProject(run, { GOOGLE_CLOUD_PROJECT: "env-project" } as NodeJS.ProcessEnv)).toBe("ref-project");
+  });
+
+  test("projectRef.external may be projects/<id>", () => {
+    const run = { metadata: { name: "r" }, spec: { projectRef: { external: "projects/three-cloud" } } };
+    expect(resolveGcpProject(run, {} as NodeJS.ProcessEnv)).toBe("three-cloud");
+  });
+
+  test("an unresolved GCP.ProjectId in projectRef reads GCP_PROJECT_ID, else falls through", () => {
+    const run = { ...BUCKET, spec: { projectRef: { external: { Ref: "GCP::ProjectId" } } } };
+    expect(resolveGcpProject(run, { GCP_PROJECT_ID: "pseudo-project" } as NodeJS.ProcessEnv)).toBe("pseudo-project");
+    expect(resolveGcpProject(run, {} as NodeJS.ProcessEnv)).toBe("annotated-project");
+  });
 });
 
 describe("resolveGcpEndpoint (#1449)", () => {

package/src/op/activities/gcp-apply.ts

@@ -3,6 +3,15 @@ import { parseYAML } from "@intentius/chant/yaml";
 import { sleep } from "@intentius/chant/op";
 import { hasOwnershipMarker, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
 import { GCP_RESOURCE_OWNERSHIP_KEYS } from "../../ownership";
+import { iamPolicyMemberMapper } from "./gcp-iam";
+import {
+  backendServiceMapper,
+  computeAddressMapper,
+  forwardingRuleMapper,
+  regionNetworkEndpointGroupMapper,
+  targetHttpProxyMapper,
+  urlMapMapper,
+} from "./gcp-compute";
 import {
   applyResult,
   type ApplyResult,
@@ -120,6 +129,29 @@ export interface ListSpec {
   items(responseBody: unknown): Array<{ name: string; labels?: Record<string, string> | null }>;
 }
 
+/**
+ * Where a mapper works: the API base, the project, and the rest of the applied
+ * manifest, so a `*Ref` to a resource declared alongside can take that
+ * resource's scope. The read path has no manifest.
+ */
+export interface MapperCtx {
+  base: string;
+  project: string;
+  manifest?: readonly GcpResource[];
+}
+
+/**
+ * A kind whose apply is not GET-then-create (#4233). IAMPolicyMember is a
+ * member inside another resource's policy, so it reads, merges and writes that
+ * policy instead. `read` answers like a GET: 200 with a body when present, 404
+ * when not.
+ */
+export interface CustomOps {
+  apply(resource: GcpResource, ctx: MapperCtx, http: GcpHttp, signal?: AbortSignal): Promise<{ created: boolean; updated: boolean }>;
+  delete(resource: GcpResource, ctx: MapperCtx, http: GcpHttp, signal?: AbortSignal): Promise<boolean>;
+  read(resource: GcpResource, ctx: MapperCtx, http: GcpHttp, signal?: AbortSignal): Promise<{ status: number; text: string }>;
+}
+
 /** Maps one CNRM kind to its GCP REST operations. The unit of the dispatch table. */
 export interface ResourceMapper {
   /** CNRM kind this handles. */
@@ -127,7 +159,11 @@ export interface ResourceMapper {
   /** Real-GCP API host, used when no `endpoint` override is given. */
   defaultHost: string;
   /** Build the GET + create plan for one resource against `base`. */
-  plan(resource: GcpResource, ctx: { base: string; project: string }): ApplyPlan;
+  plan(resource: GcpResource, ctx: MapperCtx): ApplyPlan;
+  /** False for a resource of this kind chant cannot act on (an IAM binding on a target with no policy endpoint): reported, not attempted. */
+  accepts?(resource: GcpResource, ctx: MapperCtx): boolean;
+  /** Present when apply, delete and read are not the plan's GET-then-create. */
+  custom?: CustomOps;
   /** Present for async resources whose create returns a long-running operation. */
   operation?: OperationSpec;
   /** Present when the kind can be pruned (list live → delete chant-owned orphans). */
@@ -245,14 +281,37 @@ export const pubSubTopicMapper: ResourceMapper = {
   },
 };
 
-/** Map a CNRM RunService to a Cloud Run v2 Service body. Pure. */
-export function cloudRunServiceBody(resource: GcpResource): { template?: unknown } {
-  const spec = (resource.spec ?? {}) as { template?: unknown };
+/**
+ * Map a CNRM RunService to a Cloud Run v2 Service body. Pure. CNRM names the
+ * service account with `template.serviceAccountRef`; v2 takes
+ * `template.serviceAccount` as an email (#4240).
+ */
+export function cloudRunServiceBody(resource: GcpResource, project?: string): { template?: unknown } {
+  const spec = (resource.spec ?? {}) as { template?: Record<string, unknown> };
   const body: { template?: unknown } = {};
-  if (spec.template) body.template = spec.template;
+  if (!spec.template) return body;
+  const { serviceAccountRef, ...template } = spec.template as { serviceAccountRef?: { name?: string; external?: string } };
+  const email = serviceAccountEmail(serviceAccountRef, project);
+  body.template = email ? { ...template, serviceAccount: email } : template;
   return body;
 }
 
+/**
+ * The email a CNRM `serviceAccountRef` names: `external` as given (an email,
+ * or a `projects/<p>/serviceAccounts/<email>` path), `name` as an account id
+ * in the project.
+ */
+export function serviceAccountEmail(ref: { name?: string; external?: string } | undefined, project?: string): string | undefined {
+  if (!ref) return undefined;
+  if (ref.external) return ref.external.split("/").pop();
+  if (ref.name) {
+    if (ref.name.includes("@")) return ref.name;
+    if (!project) throw new Error(`serviceAccountRef { name: "${ref.name}" } needs a project to form the account's email`);
+    return `${ref.name}@${project}.iam.gserviceaccount.com`;
+  }
+  return undefined;
+}
+
 export const cloudRunServiceMapper: ResourceMapper = {
   kind: "RunService",
   defaultHost: "https://run.googleapis.com",
@@ -269,11 +328,11 @@ export const cloudRunServiceMapper: ResourceMapper = {
       create: {
         method: "POST",
         url: `${services}?serviceId=${encodeURIComponent(name)}`,
-        body: cloudRunServiceBody(resource),
+        body: cloudRunServiceBody(resource, project),
       },
       // Cloud Run reconciles with a PATCH of the service; like create it returns
       // a long-running operation, polled via the mapper's `operation`.
-      update: { method: "PATCH", url, body: cloudRunServiceBody(resource) },
+      update: { method: "PATCH", url, body: cloudRunServiceBody(resource, project) },
     };
   },
 };
@@ -368,6 +427,14 @@ export const MAPPERS: Record<string, ResourceMapper> = {
   SecretManagerSecret: secretManagerSecretMapper,
   IAMServiceAccount: gcpServiceAccountMapper,
   RunService: cloudRunServiceMapper,
+  // #4233: a binding member, and the Cloud Run load balancer.
+  IAMPolicyMember: iamPolicyMemberMapper,
+  ComputeAddress: computeAddressMapper,
+  ComputeRegionNetworkEndpointGroup: regionNetworkEndpointGroupMapper,
+  ComputeBackendService: backendServiceMapper,
+  ComputeURLMap: urlMapMapper,
+  ComputeTargetHTTPProxy: targetHttpProxyMapper,
+  ComputeForwardingRule: forwardingRuleMapper,
 };
 
 /**
@@ -376,7 +443,29 @@ export const MAPPERS: Record<string, ResourceMapper> = {
  * refs point outside the manifest and are ignored for ordering. Pure.
  */
 export function referencedNames(resource: GcpResource): string[] {
-  const names: string[] = [];
+  return [...new Set(referencedResources(resource).map((r) => r.name))];
+}
+
+/**
+ * The CNRM kind a `*Ref` key points at, where the key alone says. A ref that
+ * carries its own `kind` (`resourceRef`) uses that. Two resources of different
+ * kinds may share a name (a RunService `web` and its NEG `web`), so ordering
+ * matches on kind when it can.
+ */
+const REF_KINDS: Record<string, string> = {
+  topicRef: "PubSubTopic",
+  serviceRef: "RunService",
+  serviceAccountRef: "IAMServiceAccount",
+  addressRef: "ComputeAddress",
+  networkEndpointGroupRef: "ComputeRegionNetworkEndpointGroup",
+  backendServiceRef: "ComputeBackendService",
+  urlMapRef: "ComputeURLMap",
+  targetHTTPProxyRef: "ComputeTargetHTTPProxy",
+};
+
+/** The local resources this resource references via `*Ref` fields, each with its kind when known. Pure. */
+export function referencedResources(resource: GcpResource): Array<{ name: string; kind?: string }> {
+  const refs: Array<{ name: string; kind?: string }> = [];
   const visit = (v: unknown, key?: string): void => {
     if (Array.isArray(v)) {
       for (const x of v) visit(x, key);
@@ -385,13 +474,14 @@ export function referencedNames(resource: GcpResource): string[] {
     if (v && typeof v === "object") {
       const obj = v as Record<string, unknown>;
       if (key && /Refs?$/.test(key) && typeof obj.name === "string") {
-        names.push(obj.name);
+        const kind = typeof obj.kind === "string" ? obj.kind : REF_KINDS[key];
+        refs.push(kind ? { name: obj.name, kind } : { name: obj.name });
       }
       for (const [k, val] of Object.entries(obj)) visit(val, k);
     }
   };
   visit(resource.spec);
-  return [...new Set(names)];
+  return refs;
 }
 
 /**
@@ -401,10 +491,10 @@ export function referencedNames(resource: GcpResource): string[] {
  * Pure — a DFS post-order.
  */
 export function orderByReferences(resources: GcpResource[]): GcpResource[] {
-  const byName = new Map<string, GcpResource>();
+  const byName = new Map<string, GcpResource[]>();
   for (const r of resources) {
     const n = r.metadata?.name;
-    if (n) byName.set(n, r);
+    if (n) byName.set(n, [...(byName.get(n) ?? []), r]);
   }
   const ordered: GcpResource[] = [];
   const done = new Set<GcpResource>();
@@ -413,9 +503,10 @@ export function orderByReferences(resources: GcpResource[]): GcpResource[] {
     if (done.has(r)) return;
     if (active.has(r)) throw new Error(`reference cycle involving ${r.metadata?.name ?? "?"}`);
     active.add(r);
-    for (const ref of referencedNames(r)) {
-      const dep = byName.get(ref);
-      if (dep && dep !== r) visit(dep);
+    for (const ref of referencedResources(r)) {
+      const named = (byName.get(ref.name) ?? []).filter((d) => d !== r);
+      const deps = ref.kind ? named.filter((d) => d.kind === ref.kind) : named;
+      for (const dep of deps) visit(dep);
     }
     active.delete(r);
     done.add(r);
@@ -443,11 +534,34 @@ export function resolveGcpEndpoint(
 }
 
 /** Resolve the project: `GOOGLE_CLOUD_PROJECT` env, else the CNRM project-id annotation. Pure. */
+/**
+ * The project a resource names in `spec.projectRef.external` (#4201): a
+ * project id or `projects/<id>`. A `GCP.ProjectId` pseudo-parameter there
+ * (`{ Ref: "GCP::ProjectId" }`, unresolved in discovery output) reads
+ * `GCP_PROJECT_ID`, as the serializer does.
+ */
+export function projectRefProject(spec: Record<string, unknown> | undefined, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const ref = spec?.projectRef;
+  if (ref === null || typeof ref !== "object") return undefined;
+  let external = (ref as Record<string, unknown>).external;
+  if (external !== null && typeof external === "object" && typeof (external as { toJSON?: unknown }).toJSON === "function") {
+    external = (external as { toJSON(): unknown }).toJSON();
+  }
+  if (external !== null && typeof external === "object" && (external as Record<string, unknown>).Ref === "GCP::ProjectId") {
+    return env.GCP_PROJECT_ID || undefined;
+  }
+  if (typeof external !== "string" || external === "") return undefined;
+  return external.startsWith("projects/") ? external.slice("projects/".length).split("/")[0] : external;
+}
+
 export function resolveGcpProject(resource: GcpResource, env: NodeJS.ProcessEnv = process.env): string {
-  const project = env.GOOGLE_CLOUD_PROJECT || resource.metadata?.annotations?.[PROJECT_ID_ANNOTATION];
+  const project =
+    projectRefProject(resource.spec, env) ||
+    env.GOOGLE_CLOUD_PROJECT ||
+    resource.metadata?.annotations?.[PROJECT_ID_ANNOTATION];
   if (!project) {
     throw new Error(
-      `no GCP project — set GOOGLE_CLOUD_PROJECT or the ${PROJECT_ID_ANNOTATION} annotation`,
+      `no GCP project — set spec.projectRef.external, GOOGLE_CLOUD_PROJECT or the ${PROJECT_ID_ANNOTATION} annotation`,
     );
   }
   return project;
@@ -480,12 +594,16 @@ const defaultHttp: GcpHttp = async (method, url, body, signal) => {
 export async function applyResource(
   mapper: ResourceMapper,
   resource: GcpResource,
-  ctx: { base: string; project: string },
+  ctx: MapperCtx,
   http: GcpHttp = defaultHttp,
   signal?: AbortSignal,
 ): Promise<{ kind: string; name: string; created: boolean; updated: boolean }> {
-  const plan = mapper.plan(resource, ctx);
   const name = resource.metadata?.name ?? "?";
+  if (mapper.custom) {
+    const result = await mapper.custom.apply(resource, ctx, http, signal);
+    return { kind: mapper.kind, name, ...result };
+  }
+  const plan = mapper.plan(resource, ctx);
   const get = await http("GET", plan.getUrl, undefined, signal);
 
   if (get.status === 200) {
@@ -689,7 +807,7 @@ export interface GcpNotPrunable {
  */
 export async function pruneOrphans(
   desired: GcpResource[],
-  resolve: (mapper: ResourceMapper, resource?: GcpResource) => { base: string; project: string },
+  resolve: (mapper: ResourceMapper, resource?: GcpResource) => MapperCtx,
   http: GcpHttp = defaultHttp,
   signal?: AbortSignal,
 ): Promise<{
@@ -757,9 +875,10 @@ export async function gcpApply(
 }> {
   const resources = orderByReferences(parseManifest(readFileSync(args.manifestPath, "utf8"), args.manifestPath));
   const endpoint = resolveGcpEndpoint(args);
-  const resolve = (mapper: ResourceMapper, resource?: GcpResource) => ({
+  const resolve = (mapper: ResourceMapper, resource?: GcpResource): MapperCtx => ({
     base: (endpoint ?? mapper.defaultHost).replace(/\/$/, ""),
     project: args.project ?? (resource ? resolveGcpProject(resource) : ""),
+    manifest: resources,
   });
 
   const applied: Array<{ kind: string; name: string; created: boolean; updated: boolean }> = [];
@@ -773,6 +892,11 @@ export async function gcpApply(
       continue;
     }
     const ctx = resolve(mapper, r);
+    if (mapper.accepts && !mapper.accepts(r, ctx)) {
+      console.log(`skip: ${r.kind}/${r.metadata?.name ?? "?"} has nothing chant can apply it to`);
+      notAttempted.push({ kind: r.kind as string, name: r.metadata?.name ?? "?", reason: "unsupported-kind" });
+      continue;
+    }
     const result = await applyResource(mapper, r, ctx, http, signal);
     const verb = result.created ? "created" : result.updated ? "updated" : "unchanged";
     console.log(`${verb}: ${result.kind}/${result.name} (${ctx.base})`);
@@ -793,12 +917,15 @@ export async function gcpApply(
 export async function deleteResource(
   mapper: ResourceMapper,
   resource: GcpResource,
-  ctx: { base: string; project: string },
+  ctx: MapperCtx,
   http: GcpHttp = defaultHttp,
   signal?: AbortSignal,
 ): Promise<{ kind: string; name: string; deleted: boolean }> {
-  const plan = mapper.plan(resource, ctx);
   const name = resource.metadata?.name ?? "?";
+  if (mapper.custom) {
+    return { kind: mapper.kind, name, deleted: await mapper.custom.delete(resource, ctx, http, signal) };
+  }
+  const plan = mapper.plan(resource, ctx);
   const res = await http("DELETE", plan.getUrl, undefined, signal);
   if (res.status === 404) {
     return { kind: mapper.kind, name, deleted: false };
@@ -847,7 +974,13 @@ export async function gcpDelete(
     }
     const base = (resolveGcpEndpoint(args) ?? mapper.defaultHost).replace(/\/$/, "");
     const project = args.project ?? resolveGcpProject(r);
-    const result = await deleteResource(mapper, r, { base, project }, http, signal);
+    const ctx: MapperCtx = { base, project, manifest: resources };
+    if (mapper.accepts && !mapper.accepts(r, ctx)) {
+      console.log(`skip: ${r.kind}/${r.metadata?.name ?? "?"} has nothing chant can delete it from`);
+      notAttempted.push({ kind: r.kind as string, name: r.metadata?.name ?? "?", reason: "unsupported-kind" });
+      continue;
+    }
+    const result = await deleteResource(mapper, r, ctx, http, signal);
     console.log(`${result.deleted ? "deleted" : "absent"}: ${result.kind}/${result.name} (${base})`);
     deleted.push(result);
   }