@intentius/chant-lexicon-gcp 0.41.20 → 0.44.1

package/src/composites/landing-zone.ts

@@ -0,0 +1,173 @@
+/**
+ * Landing-zone bootstrap composites (#791, epic #787 C1) — the GCP slice.
+ *
+ * Fixed-shape resources for greenfield creation of the recommended
+ * governance foundation through a Config Connector management stack. The
+ * evaluability rules (EVL002/004) require composites to declare a fixed set
+ * of resources, so these carry the foundation only; arbitrary folder/project
+ * trees are authored as config with `landingZoneConfig()` (../governance.ts)
+ * and reconciled by the GCP cloud warden, and further folders/projects are
+ * declared as ordinary resources.
+ *
+ * The pieces compose:
+ *   const lz = GovernanceFoundation({ orgId: "123456789012" });
+ *   const lr = LocationRestriction({ orgId: "123456789012", locations: ["in:eu-locations"] });
+ *   const ac = OrganizationAuditConfig({ orgId: "123456789012" });
+ * There is no OrganizationRoot analog — GCP organizations come from Cloud
+ * Identity / Workspace, not the resource API, so greenfield and brownfield
+ * both start from an existing org id.
+ */
+
+import { Composite } from "@intentius/chant";
+import { IAMAuditConfig, OrgpolicyPolicy, ResourcemanagerFolder } from "../generated";
+import {
+  AUDIT_ALL_SERVICES,
+  DISABLE_SA_KEY_CREATION,
+  SKIP_DEFAULT_NETWORK,
+  resourceLocationRestriction,
+  type OrgPolicyConfig,
+} from "../governance";
+
+/** "organizations/123" and "123" are both accepted everywhere an org id appears. */
+function orgNumber(orgId: string): string {
+  return orgId.replace(/^organizations\//, "");
+}
+
+function labels(component: string): Record<string, string> {
+  return {
+    "app.kubernetes.io/managed-by": "chant",
+    "app.kubernetes.io/component": component,
+  };
+}
+
+function orgPolicy(
+  metaName: string,
+  policy: OrgPolicyConfig,
+  orgId: string,
+  namespace?: string,
+): InstanceType<typeof OrgpolicyPolicy> {
+  return new OrgpolicyPolicy({
+    metadata: {
+      name: metaName,
+      ...(namespace && { namespace }),
+      labels: labels("org-policy"),
+    },
+    resourceID: policy.constraint,
+    organizationRef: { external: orgNumber(orgId) },
+    spec: { rules: policy.rules },
+  } as Record<string, unknown>);
+}
+
+// ---------------------------------------------------------------------------
+// GovernanceFoundation — the recommended foundation
+// ---------------------------------------------------------------------------
+
+export interface GovernanceFoundationProps {
+  /** The organization to hang the foundation off ("123456789012" or "organizations/123456789012"). */
+  orgId: string;
+  /** Namespace for all resources. */
+  namespace?: string;
+}
+
+export type GovernanceFoundationResult = {
+  folderSecurity: InstanceType<typeof ResourcemanagerFolder>;
+  folderInfrastructure: InstanceType<typeof ResourcemanagerFolder>;
+  folderSandbox: InstanceType<typeof ResourcemanagerFolder>;
+  folderWorkloads: InstanceType<typeof ResourcemanagerFolder>;
+  policyDisableSaKeyCreation: InstanceType<typeof OrgpolicyPolicy>;
+  policySkipDefaultNetwork: InstanceType<typeof OrgpolicyPolicy>;
+};
+
+/**
+ * Security / Infrastructure / Sandbox / Workloads folders with
+ * `disable-sa-key-creation` and `skip-default-network` enforced at the
+ * organization root — the same baseline `landingZoneConfig()` declares.
+ */
+export const GovernanceFoundation = Composite<GovernanceFoundationProps, GovernanceFoundationResult>((props) => {
+  const { orgId, namespace } = props;
+  const folder = (metaName: string, displayName: string): InstanceType<typeof ResourcemanagerFolder> =>
+    new ResourcemanagerFolder({
+      metadata: {
+        name: metaName,
+        ...(namespace && { namespace }),
+        labels: labels("folder"),
+      },
+      displayName,
+      organizationRef: { external: orgNumber(orgId) },
+    } as Record<string, unknown>);
+
+  return {
+    folderSecurity: folder("security", "Security"),
+    folderInfrastructure: folder("infrastructure", "Infrastructure"),
+    folderSandbox: folder("sandbox", "Sandbox"),
+    folderWorkloads: folder("workloads", "Workloads"),
+    policyDisableSaKeyCreation: orgPolicy("disable-sa-key-creation", DISABLE_SA_KEY_CREATION, orgId, namespace),
+    policySkipDefaultNetwork: orgPolicy("skip-default-network", SKIP_DEFAULT_NETWORK, orgId, namespace),
+  };
+}, "GovernanceFoundation");
+
+// ---------------------------------------------------------------------------
+// LocationRestriction — optional root guardrail
+// ---------------------------------------------------------------------------
+
+export interface LocationRestrictionProps {
+  /** The organization the policy binds to. */
+  orgId: string;
+  /** The only locations resources may be created in (value groups like "in:eu-locations" work). */
+  locations: string[];
+  /** Namespace for all resources. */
+  namespace?: string;
+}
+
+export type LocationRestrictionResult = {
+  policyResourceLocations: InstanceType<typeof OrgpolicyPolicy>;
+};
+
+export const LocationRestriction = Composite<LocationRestrictionProps, LocationRestrictionResult>((props) => {
+  const policyResourceLocations = orgPolicy(
+    "resource-location-restriction",
+    resourceLocationRestriction(props.locations),
+    props.orgId,
+    props.namespace,
+  );
+  return { policyResourceLocations };
+}, "LocationRestriction");
+
+// ---------------------------------------------------------------------------
+// OrganizationAuditConfig — the audit sink
+// ---------------------------------------------------------------------------
+
+export interface OrganizationAuditConfigProps {
+  /** The organization audit logging is enabled on. */
+  orgId: string;
+  /** Defaults to "allServices". */
+  service?: string;
+  /** Defaults to ADMIN_READ / DATA_READ / DATA_WRITE. */
+  logTypes?: string[];
+  /** Namespace for all resources. */
+  namespace?: string;
+}
+
+export type OrganizationAuditConfigResult = {
+  auditConfig: InstanceType<typeof IAMAuditConfig>;
+};
+
+export const OrganizationAuditConfig = Composite<OrganizationAuditConfigProps, OrganizationAuditConfigResult>(
+  (props) => {
+    const auditConfig = new IAMAuditConfig({
+      metadata: {
+        name: "organization-audit",
+        ...(props.namespace && { namespace: props.namespace }),
+        labels: labels("audit"),
+      },
+      resourceRef: {
+        kind: "Organization",
+        external: `organizations/${orgNumber(props.orgId)}`,
+      },
+      service: props.service ?? AUDIT_ALL_SERVICES.service,
+      auditLogConfigs: (props.logTypes ?? [...AUDIT_ALL_SERVICES.logTypes]).map((logType) => ({ logType })),
+    } as Record<string, unknown>);
+    return { auditConfig };
+  },
+  "OrganizationAuditConfig",
+);

package/src/deep-observe-hooks.ts

@@ -1,6 +1,6 @@
 /**
- * GCP deep-observation noise rules (#1209) — for REST payloads, not Config
- * Connector objects.
+ * GCP deep-observation noise rules (#1209, #1210) — for REST payloads, not
+ * Config Connector objects.
  *
  * ## What this replaced, and why it had to
  *
@@ -22,8 +22,21 @@
  * 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.
+ *
+ * ## The declared side is CNRM, and some of it never reaches GCP
+ *
+ * The declared tree is a Config Connector spec, and a few of its fields are
+ * instructions to the CNRM machinery rather than resource configuration —
+ * `projectRef`, `resourceID`, the `cnrm.cloud.google.com/*`
+ * annotations. No REST payload will ever echo them (the project is in the
+ * URL), so left alone each one reports `absent` drift on every clean apply.
+ * They are pruned as declared-side envelope, the mirror image of the
+ * live-side server fields.
  */
 import type { DeepNode, DeepNormalizationHooks } from "@intentius/chant/deep-observation";
+import { LABEL_OWNERSHIP_KEYS, type ChannelKeys } from "@intentius/chant/ownership";
+import { GCP_RESOURCE_OWNERSHIP_KEYS } from "./ownership";
+import { resolveGVK } from "./serializer";
 
 /**
  * Fields GCP populates on essentially anything, wherever they appear.
@@ -36,6 +49,7 @@ export const GCP_READ_ONLY_NAMES: ReadonlySet<string> = new Set([
   "etag",
   "selfLink",
   "id",
+  "projectId",
   "projectNumber",
   "timeCreated",
   "updated",
@@ -44,13 +58,25 @@ export const GCP_READ_ONLY_NAMES: ReadonlySet<string> = new Set([
   "generation",
   "metageneration",
   "uid",
+  "uniqueId",
+  "email",
   "state",
   "reconciling",
   "observedGeneration",
+  // Cloud Run's server-computed service surface (v2 GetService).
+  "uri",
+  "urls",
+  "conditions",
+  "terminalCondition",
+  "latestReadyRevision",
+  "latestCreatedRevision",
 ]);
 
 /**
- * Per-kind values GCP fills in when the request omits them.
+ * Per-kind values GCP fills in when the request omits them, keyed by the
+ * index-erased pattern from the tree root (the declared-props shape
+ * `./deep-observe.ts` reshapes the live payload into — spec fields at the
+ * root, so `storageClass`, not `spec.storageClass`).
  *
  * 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
@@ -62,10 +88,9 @@ export const GCP_SERVICE_DEFAULTS: Readonly<Record<string, Readonly<Record<strin
   StorageBucket: {
     storageClass: "STANDARD",
     locationType: "multi-region",
-    "iamConfiguration.publicAccessPrevention": "inherited",
-    "iamConfiguration.uniformBucketLevelAccess.enabled": false,
+    publicAccessPrevention: "inherited",
+    uniformBucketLevelAccess: false,
     "softDeletePolicy.retentionDurationSeconds": "604800",
-    kind: "storage#bucket",
   },
   PubSubTopic: {
     "messageStoragePolicy.enforceInTransit": false,
@@ -74,11 +99,11 @@ export const GCP_SERVICE_DEFAULTS: Readonly<Record<string, Readonly<Record<strin
     ackDeadlineSeconds: 10,
     "expirationPolicy.ttl": "2678400s",
     enableMessageOrdering: false,
+    enableExactlyOnceDelivery: false,
+    retainAckedMessages: false,
+    detached: false,
     "retryPolicy.minimumBackoff": "10s",
   },
-  SecretManagerSecret: {
-    etag: undefined, // covered by READ_ONLY; listed for readers looking here first
-  },
   RunService: {
     ingress: "INGRESS_TRAFFIC_ALL",
     launchStage: "GA",
@@ -88,12 +113,28 @@ export const GCP_SERVICE_DEFAULTS: Readonly<Record<string, Readonly<Record<strin
   },
 };
 
-/** chant's own ownership labels, as the applier stamps them. */
-const CHANT_OWNERSHIP_LABEL_PATTERNS: ReadonlySet<string> = new Set([
-  "metadata.labels.managed-by",
-  "metadata.labels.chant-stack",
-  "metadata.labels.chant-env",
-]);
+/**
+ * chant's own ownership marker, in both vocabularies it is written in: the
+ * serializer stamps k8s-style label keys on the CNRM object
+ * (`app.kubernetes.io/managed-by`), while `gcpApply` stamps the GCP-legal
+ * equivalents on the live resource (`managed-by` — GCP label keys allow no `/`
+ * or `.`). See `./ownership.ts` for why the two surfaces differ. A declared
+ * tree carries the first family, a live payload can carry either (the applier
+ * forwards the manifest's labels where a kind accepts labels at all), and
+ * neither is drift: it is chant showing its own signature to itself — the same
+ * correction #1301 made for AWS.
+ */
+const CHANT_OWNERSHIP_LABEL_PATTERNS: ReadonlySet<string> = new Set(
+  [LABEL_OWNERSHIP_KEYS, GCP_RESOURCE_OWNERSHIP_KEYS].flatMap((keys: ChannelKeys) => [
+    `metadata.labels.${keys.managedBy}`,
+    `metadata.labels.${keys.stack}`,
+    `metadata.labels.${keys.env}`,
+  ]),
+);
+
+/** Declared-side CNRM machinery a REST payload never echoes (see module doc). */
+const CNRM_ENVELOPE_PATTERNS: ReadonlySet<string> = new Set(["projectRef", "resourceID"]);
+const CNRM_ANNOTATION_PREFIX = "metadata.annotations.cnrm.cloud.google.com/";
 
 /** Last dotted segment of a path pattern — `spec.foo.etag` -> `etag`. */
 function lastSegment(pattern: string): string {
@@ -101,6 +142,13 @@ function lastSegment(pattern: string): string {
   return i === -1 ? pattern : pattern.slice(i + 1);
 }
 
+/** A `{}` with nothing pruned out of it, as GCP returns for an unset message. */
+function isEmptyObject(value: unknown): boolean {
+  return (
+    typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 0
+  );
+}
+
 /**
  * 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.
@@ -110,22 +158,40 @@ export const gcpDeepNormalizationHooks: DeepNormalizationHooks = {
     // Server-assigned, wherever it appears, on either side.
     if (GCP_READ_ONLY_NAMES.has(lastSegment(node.pattern))) return true;
 
-    // chant's own ownership marker is not drift. The applier stamps these, so
-    // reporting them back is chant showing its own signature to itself — the
-    // same correction #1301 made for AWS after the emulator began applying tags.
+    // chant's own ownership marker is not drift (see the set's doc).
     if (CHANT_OWNERSHIP_LABEL_PATTERNS.has(node.pattern)) return true;
 
-    // A provider default is noise only where source never declared the
-    // property. `counterpart` is a tri-state; only `absent` licenses this.
+    // CNRM machinery on the declared side: instructions to the controller, not
+    // resource state, and no REST payload ever carries them.
+    if (CNRM_ENVELOPE_PATTERNS.has(node.pattern)) return true;
+    if (node.pattern.startsWith(CNRM_ANNOTATION_PREFIX)) return true;
+
+    // Everything below subtracts provider-populated values from the live tree,
+    // and only where source never declared the property. `counterpart` is a
+    // tri-state; only `absent` licenses it.
     if (node.side !== "live" || node.counterpart !== "absent") return false;
+
+    // An undeclared `null` or `{}` is GCP's spelling of "unset" — a field the
+    // API includes in the payload without there being any configuration in it
+    // (a service account's `description: null`, Cloud Run's
+    // `binaryAuthorization: {}`).
+    if (node.value === null || isEmptyObject(node.value)) return true;
+
     const kindDefaults = GCP_SERVICE_DEFAULTS[shortKind(node.entityType)];
     if (!kindDefaults) return false;
     return Object.prototype.hasOwnProperty.call(kindDefaults, node.pattern) && kindDefaults[node.pattern] === node.value;
   },
 };
 
-/** `GCP::Storage::Bucket` -> `StorageBucket`, the key `GCP_SERVICE_DEFAULTS` uses. */
+/**
+ * `GCP::Pubsub::Topic` -> `PubSubTopic`, the key `GCP_SERVICE_DEFAULTS` uses —
+ * the CNRM kind, resolved through the serializer's GVK map because the naive
+ * `${service}${shortKind}` concatenation miscases 4 of the 6 appliable kinds
+ * (`PubsubTopic`, `IamServiceAccount`, …) and silently matches no defaults.
+ */
 function shortKind(entityType: string): string {
+  const resolved = resolveGVK(entityType);
+  if (resolved) return resolved.kind;
   const parts = entityType.split("::");
   return parts.length === 3 ? `${parts[1]}${parts[2]}` : entityType;
 }

package/src/deep-observe.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import { gcpPlugin } from "./plugin";
-import { observeResourcesDeepGcp } from "./deep-observe";
+import { observeResourcesDeepGcp, toCnrmTree } from "./deep-observe";
 import { gcpDeepNormalizationHooks, GCP_READ_ONLY_NAMES, GCP_SERVICE_DEFAULTS } from "./deep-observe-hooks";
 import type { DeepNode } from "@intentius/chant/deep-observation";
 
@@ -8,7 +8,8 @@ import type { DeepNode } from "@intentius/chant/deep-observation";
  * The deep reader is on GCP REST now, not kubectl (#1209), so these stub
  * `fetch`. What they mostly assert is the consequence of that: a REST payload
  * carries no field ownership, so the noise rules are a static table rather than
- * a per-resource managed-fields prune.
+ * a per-resource managed-fields prune — plus the #1210 half of the port, the
+ * per-kind mapping of each REST shape onto the declared CNRM vocabulary.
  */
 const fetchMock = vi.fn();
 
@@ -23,7 +24,7 @@ function entities(records: Array<[string, string, Record<string, unknown>]>) {
   return new Map(records.map(([n, t, p]) => [n, { entityType: t, props: p }]));
 }
 
-async function observe(e: ReturnType<typeof entities>, opts: { owned?: boolean } = {}) {
+async function observe(e: ReturnType<typeof entities>, opts: { owned?: boolean; buildOutput?: string } = {}) {
   return observeResourcesDeepGcp({ environment: "local", entityNames: [...e.keys()], entities: e, ...opts });
 }
 
@@ -68,6 +69,109 @@ describe("gcpDeepNormalizationHooks — the static rules (#1209)", () => {
     // nothing to layer now, which is why the static table has to be enough.
     expect(Object.keys(gcpDeepNormalizationHooks)).toEqual(["prune"]);
   });
+
+  test("defaults are keyed by the CNRM kind, not a naive recasing of the entity type", () => {
+    // `GCP::Pubsub::Subscription` names the kind `PubSubSubscription`; a naive
+    // `${service}${shortKind}` gives `PubsubSubscription` and matches nothing.
+    const defaulted = node({
+      entityType: "GCP::Pubsub::Subscription",
+      pattern: "ackDeadlineSeconds",
+      value: 10,
+      side: "live",
+      counterpart: "absent",
+    });
+    expect(gcpDeepNormalizationHooks.prune!(defaulted)).toBe(true);
+  });
+
+  test("both ownership vocabularies are pruned — the serializer's k8s labels and the applier's GCP ones", () => {
+    for (const pattern of [
+      "metadata.labels.managed-by",
+      "metadata.labels.chant-stack",
+      "metadata.labels.chant-env",
+      "metadata.labels.app.kubernetes.io/managed-by",
+      "metadata.labels.chant.intentius.io/stack",
+      "metadata.labels.chant.intentius.io/env",
+    ]) {
+      expect(gcpDeepNormalizationHooks.prune!(node({ pattern, side: "live" }))).toBe(true);
+      expect(gcpDeepNormalizationHooks.prune!(node({ pattern, side: "declared" }))).toBe(true);
+    }
+  });
+
+  test("declared-side CNRM machinery never reaches GCP and is not drift", () => {
+    for (const pattern of ["projectRef", "resourceID", "metadata.annotations.cnrm.cloud.google.com/project-id"]) {
+      expect(gcpDeepNormalizationHooks.prune!(node({ pattern, side: "declared" }))).toBe(true);
+    }
+    // A user's own annotation is still a fact worth diffing.
+    expect(gcpDeepNormalizationHooks.prune!(node({ pattern: "metadata.annotations.team", side: "declared" }))).toBe(false);
+  });
+
+  test("an undeclared null or `{}` is GCP's spelling of unset, not drift", () => {
+    const nullValue = node({ pattern: "description", value: null, side: "live", counterpart: "absent" });
+    expect(gcpDeepNormalizationHooks.prune!(nullValue)).toBe(true);
+    const husk = node({ pattern: "binaryAuthorization", value: {}, side: "live", counterpart: "absent" });
+    expect(gcpDeepNormalizationHooks.prune!(husk)).toBe(true);
+    // Declared, or carrying members, it is a value like any other.
+    expect(gcpDeepNormalizationHooks.prune!(node({ pattern: "description", value: null, side: "live", counterpart: "present" }))).toBe(false);
+    expect(gcpDeepNormalizationHooks.prune!(node({ pattern: "binaryAuthorization", value: { policy: "p" }, side: "live", counterpart: "absent" }))).toBe(false);
+  });
+});
+
+describe("toCnrmTree — each REST shape in the declared vocabulary (#1210)", () => {
+  const ctx = { project: "my-project" };
+
+  test("a full resource path shortens to the declared name", () => {
+    const tree = toCnrmTree("PubSubTopic", { name: "projects/my-project/topics/t", messageRetentionDuration: "86400s" }, ctx);
+    expect(tree).toEqual({ metadata: { name: "t" }, messageRetentionDuration: "86400s" });
+  });
+
+  test("bucket: GCS's iamConfiguration and lifecycle map onto the CNRM field names", () => {
+    const tree = toCnrmTree(
+      "StorageBucket",
+      {
+        name: "b",
+        iamConfiguration: { uniformBucketLevelAccess: { enabled: true }, publicAccessPrevention: "enforced" },
+        lifecycle: { rule: [{ action: { type: "Delete" }, condition: { age: 30 } }] },
+      },
+      ctx,
+    ) as Record<string, unknown>;
+    expect(tree.uniformBucketLevelAccess).toBe(true);
+    expect(tree.publicAccessPrevention).toBe("enforced");
+    expect(tree.lifecycleRule).toEqual([{ action: { type: "Delete" }, condition: { age: 30 } }]);
+    expect(tree.iamConfiguration).toBeUndefined();
+    expect(tree.lifecycle).toBeUndefined();
+  });
+
+  test("subscription: a same-project topic path becomes topicRef.name, a foreign one topicRef.external", () => {
+    const same = toCnrmTree("PubSubSubscription", { name: "projects/my-project/subscriptions/s", topic: "projects/my-project/topics/t" }, ctx) as Record<string, unknown>;
+    expect(same.topicRef).toEqual({ name: "t" });
+    expect(same.topic).toBeUndefined();
+    const foreign = toCnrmTree("PubSubSubscription", { name: "projects/my-project/subscriptions/s", topic: "projects/other/topics/t" }, ctx) as Record<string, unknown>;
+    expect(foreign.topicRef).toEqual({ external: "projects/other/topics/t" });
+  });
+
+  test("secret: automatic replication maps onto CNRM's boolean spelling", () => {
+    const tree = toCnrmTree("SecretManagerSecret", { name: "projects/my-project/secrets/s", replication: { automatic: {} } }, ctx) as Record<string, unknown>;
+    expect(tree.replication).toEqual({ automatic: true });
+  });
+
+  test("service account: the email identity maps back to the declared account id", () => {
+    const tree = toCnrmTree(
+      "IAMServiceAccount",
+      { name: "projects/my-project/serviceAccounts/sa-1@my-project.iam.gserviceaccount.com", displayName: "SA" },
+      ctx,
+    );
+    expect((tree.metadata as Record<string, unknown>).name).toBe("sa-1");
+  });
+
+  test("run service: location comes from the resource name the payload carries nowhere else", () => {
+    const tree = toCnrmTree(
+      "RunService",
+      { name: "projects/my-project/locations/us-central1/services/svc", template: { containers: [{ image: "i" }] } },
+      ctx,
+    ) as Record<string, unknown>;
+    expect(tree.location).toBe("us-central1");
+    expect((tree.metadata as Record<string, unknown>).name).toBe("svc");
+  });
 });
 
 describe("observeResourcesDeepGcp — over REST (#1209)", () => {
@@ -90,19 +194,20 @@ describe("observeResourcesDeepGcp — over REST (#1209)", () => {
     const out = await observe(entities([["b", "GCP::Storage::Bucket", { metadata: { name: "my-bucket" } }]]));
 
     expect(fetchMock.mock.calls[0][0]).toBe("http://localhost:4588/storage/v1/b/my-bucket");
-    const props = out.resources.b.properties as Record<string, Record<string, unknown>>;
+    const props = out.resources.b.properties as Record<string, unknown>;
 
-    // Reshaped into the CNRM shape the declared source is written in — without
-    // this every field drifts twice, once as `spec.x -> <absent>` and once as
-    // `x -> <undeclared>`.
-    expect(props.spec.storageClass).toBe("NEARLINE");
-    expect(props.spec.location).toBe("US");
-    expect(props.metadata.name).toBe("my-bucket");
+    // Reshaped into the declared-props shape — identity under `metadata`, spec
+    // fields at the root, exactly as `new StorageBucket({ … })` authors them.
+    // Without this every field drifts twice, once as `declared -> <absent>`
+    // and once as `<undeclared> -> live`.
+    expect(props.storageClass).toBe("NEARLINE");
+    expect(props.location).toBe("US");
+    expect((props.metadata as Record<string, unknown>).name).toBe("my-bucket");
 
     // Server-assigned, pruned wherever they landed.
-    expect(props.spec.etag).toBeUndefined();
-    expect(props.spec.selfLink).toBeUndefined();
-    expect(props.spec.id).toBeUndefined();
+    expect(props.etag).toBeUndefined();
+    expect(props.selfLink).toBeUndefined();
+    expect(props.id).toBeUndefined();
   });
 
   test("chant's own ownership labels are not drift", async () => {
@@ -165,4 +270,44 @@ describe("observeResourcesDeepGcp — over REST (#1209)", () => {
     );
     expect(fetchMock).toHaveBeenCalledTimes(2);
   });
+
+  test("kinds resolve through the serializer's GVK map, not naive recasing", async () => {
+    // `GCP::Pubsub::Topic` derives `PubsubTopic` naively — no such mapper, so
+    // 4 of the 6 appliable kinds silently reported unsupported-kind until the
+    // readers resolved kinds the way the serializer does.
+    fetchMock.mockResolvedValue(reply(200, { name: "projects/my-project/topics/t" }));
+    const out = await observe(entities([["t", "GCP::Pubsub::Topic", { metadata: { name: "t" } }]]));
+    expect(out.unobserved?.t).toBeUndefined();
+    expect(out.resources.t).toBeDefined();
+    expect(fetchMock.mock.calls[0][0]).toBe("http://localhost:4588/v1/projects/my-project/topics/t");
+  });
+
+  test("the project falls back to the built manifest's merged annotation", async () => {
+    // A project-wide `defaultAnnotations` is a separate declarable the
+    // serializer merges at synthesis — the entity's own props never carry it,
+    // and discovery is what the observe paths receive.
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+    fetchMock.mockResolvedValue(reply(200, { name: "b" }));
+    const buildOutput = [
+      "apiVersion: storage.cnrm.cloud.google.com/v1beta1",
+      "kind: StorageBucket",
+      "metadata:",
+      "  name: b",
+      "  annotations:",
+      "    cnrm.cloud.google.com/project-id: manifest-project",
+      "spec:",
+      "  location: US",
+    ].join("\n");
+    const out = await observe(entities([["b", "GCP::Storage::Bucket", { metadata: { name: "b" } }]]), { buildOutput });
+    expect(out.unobserved?.b).toBeUndefined();
+    expect(out.resources.b).toBeDefined();
+    expect(fetchMock.mock.calls[0][0]).toBe("http://localhost:4588/storage/v1/b/b");
+  });
+
+  test("no project from any source is still a no-binding hole, never a guess", async () => {
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+    const out = await observe(entities([["t", "GCP::Pubsub::Topic", { metadata: { name: "t" } }]]));
+    expect(out.unobserved?.t?.reason).toBe("no-binding");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
 });