@microagi/alchemy-gcp 0.7.0 → 0.8.1

package/lib/Storage/BucketIamMember.d.ts

@@ -0,0 +1,29 @@
+import * as Effect from "effect/Effect";
+import type { StorageBucket } from "./Bucket.ts";
+/**
+ * Bind a single `(role, member)` IAM grant onto a
+ * {@link StorageBucket}.
+ *
+ * Target-side binding — same pattern as
+ * {@link import("../CloudResourceManager/ProjectIamMember.ts").projectIamMember}
+ * / `serviceAccountIamMember`. The bucket's `reconcile` merges all
+ * bindings into a single `setIamPolicy` call on the bucket, preserving
+ * foreign roles + members.
+ *
+ * Identity for dedup: the rendered SID is `IamMember(<bucket>, <key>)`.
+ * The engine collapses binds by SID, so callers MUST supply a
+ * stack-unique `key` per (bucket, role, member) triple.
+ *
+ * @example Granting a service account read+write on a bucket
+ * ```typescript
+ * yield* GCP.storageBucketIamMember(bucket, "TempBucketRw", {
+ *   role: "roles/storage.objectUser",
+ *   member: `serviceAccount:${sa.email}`,
+ * });
+ * ```
+ */
+export declare const storageBucketIamMember: (bucket: StorageBucket, key: string, args: {
+    role: string;
+    member: string;
+}) => Effect.Effect<void>;
+//# sourceMappingURL=BucketIamMember.d.ts.map

package/lib/Storage/BucketIamMember.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BucketIamMember.d.ts","sourceRoot":"","sources":["../../src/Storage/BucketIamMember.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,sBAAsB,WACzB,aAAa,OAChB,MAAM,QACL;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KACrC,MAAM,CAAC,MAAM,CAAC,IAAI,CAGiB,CAAC"}

package/lib/Storage/BucketIamMember.js

@@ -0,0 +1,26 @@
+/**
+ * Bind a single `(role, member)` IAM grant onto a
+ * {@link StorageBucket}.
+ *
+ * Target-side binding — same pattern as
+ * {@link import("../CloudResourceManager/ProjectIamMember.ts").projectIamMember}
+ * / `serviceAccountIamMember`. The bucket's `reconcile` merges all
+ * bindings into a single `setIamPolicy` call on the bucket, preserving
+ * foreign roles + members.
+ *
+ * Identity for dedup: the rendered SID is `IamMember(<bucket>, <key>)`.
+ * The engine collapses binds by SID, so callers MUST supply a
+ * stack-unique `key` per (bucket, role, member) triple.
+ *
+ * @example Granting a service account read+write on a bucket
+ * ```typescript
+ * yield* GCP.storageBucketIamMember(bucket, "TempBucketRw", {
+ *   role: "roles/storage.objectUser",
+ *   member: `serviceAccount:${sa.email}`,
+ * });
+ * ```
+ */
+export const storageBucketIamMember = (bucket, key, args) => bucket.bind `IamMember(${bucket}, ${key})`({
+    iamBindings: [{ role: args.role, members: [args.member] }],
+});
+//# sourceMappingURL=BucketIamMember.js.map

package/lib/Storage/BucketIamMember.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BucketIamMember.js","sourceRoot":"","sources":["../../src/Storage/BucketIamMember.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,MAAqB,EACrB,GAAW,EACX,IAAsC,EACjB,EAAE,CACvB,MAAM,CAAC,IAAI,CAAA,aAAa,MAAM,KAAK,GAAG,GAAG,CAAC;IACxC,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;CAC3D,CAAmC,CAAC"}

package/lib/Storage/index.d.ts

@@ -0,0 +1,4 @@
+export { StorageBucket, StorageBucketProvider, } from "./Bucket.ts";
+export type { StorageBucketProps, StorageBucketIamBinding, StorageBucketBindingContract, } from "./Bucket.ts";
+export * from "./BucketIamMember.ts";
+//# sourceMappingURL=index.d.ts.map

package/lib/Storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AACrB,cAAc,sBAAsB,CAAC"}

package/lib/Storage/index.js

@@ -0,0 +1,3 @@
+export { StorageBucket, StorageBucketProvider, } from "./Bucket.js";
+export * from "./BucketIamMember.js";
+//# sourceMappingURL=index.js.map

package/lib/Storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/Storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAMrB,cAAc,sBAAsB,CAAC"}

package/lib/Tags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tags.d.ts","sourceRoot":"","sources":["../src/Tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AAEH,QAAA,MAAM,aAAa,gBAAgB,CAAC;AACpC,QAAA,MAAM,eAAe,kBAAkB,CAAC;AACxC,QAAA,MAAM,YAAY,eAAe,CAAC;AAQlC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;wBAQ5B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,0GAW3B,CAAC;AAEH,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,eAAe,IAAI,mBAAmB,EACtC,YAAY,IAAI,gBAAgB,GACjC,CAAC;AAsBF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,mGAQhC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,+FAStC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,aAAa,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAI7E,CAAC"}
+{"version":3,"file":"Tags.d.ts","sourceRoot":"","sources":["../src/Tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AAEH,QAAA,MAAM,aAAa,gBAAgB,CAAC;AACpC,QAAA,MAAM,eAAe,kBAAkB,CAAC;AACxC,QAAA,MAAM,YAAY,eAAe,CAAC;AAQlC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;wBAQ5B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,0GAW3B,CAAC;AAEH,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,eAAe,IAAI,mBAAmB,EACtC,YAAY,IAAI,gBAAgB,GACjC,CAAC;AAsBF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,mGAQhC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,+FAStC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,gBAAiB,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAI7E,CAAC"}

package/lib/index.d.ts

@@ -5,11 +5,13 @@ export * from "./ArtifactRegistry/index.ts";
 export * from "./CloudResourceManager/index.ts";
 export * from "./Compute/index.ts";
 export * from "./Container/index.ts";
+export * from "./Iam/index.ts";
 export * from "./Kubernetes/index.ts";
 export * from "./ManagedLustre/index.ts";
 export * from "./Run/index.ts";
 export * from "./ServiceNetworking/index.ts";
 export * from "./Sqladmin/index.ts";
 export * from "./ServiceUsage/index.ts";
+export * from "./Storage/index.ts";
 export * from "./Providers.ts";
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,aAAa,EACb,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,aAAa,EACb,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC"}

package/lib/index.js

@@ -4,11 +4,13 @@ export * from "./ArtifactRegistry/index.js";
 export * from "./CloudResourceManager/index.js";
 export * from "./Compute/index.js";
 export * from "./Container/index.js";
+export * from "./Iam/index.js";
 export * from "./Kubernetes/index.js";
 export * from "./ManagedLustre/index.js";
 export * from "./Run/index.js";
 export * from "./ServiceNetworking/index.js";
 export * from "./Sqladmin/index.js";
 export * from "./ServiceUsage/index.js";
+export * from "./Storage/index.js";
 export * from "./Providers.js";
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAKhC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAKhC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@microagi/alchemy-gcp",
-  "version": "0.7.0",
-  "description": "GCP provider for Alchemy v2 (Effect-based IaC). Resources for Project, Cluster, NodePool, Compute, ManagedLustre, ServiceUsage, ServiceNetworking, Cloud Run (Service + Job + IAM), Cloud SQL (Instance + Database + User with IAM database authn), Artifact Registry (Docker repositories, standard + remote pull-through caches), with ADC-backed credentials and target-side IAM bindings.",
+  "version": "0.8.1",
+  "description": "GCP provider for Alchemy v2 (Effect-based IaC). Resources for Project, ServiceAccount, Cluster, NodePool, Compute, ManagedLustre, ServiceUsage, ServiceNetworking, Cloud Run (Service + Job + IAM), Cloud SQL (Instance + Database + User with IAM database authn), Artifact Registry (Docker repositories, standard + remote pull-through caches), Kubernetes (typed Secret + generic SSA Manifest), with ADC-backed credentials and target-side IAM bindings.",
   "keywords": [
     "alchemy",
     "alchemy-effect",
@@ -43,7 +43,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsgo -p tsconfig.build.json",
     "clean": "rm -rf lib",
     "test": "CI=1 bun test",
     "test:watch": "CI=1 bun test --watch",

package/src/Container/NodePool.ts

@@ -144,6 +144,14 @@ export type NodePoolProps = {
     gvnic?: { enabled: boolean };
     /** Confidential VM. Mutable via `update`. */
     confidentialNodes?: { enabled: boolean };
+    /**
+     * GCFS (Image Streaming) — stream container image data from Artifact
+     * Registry so containers start before the full image is pulled,
+     * cutting cold start for large images. Only accelerates images stored
+     * in Artifact Registry. Mutable via `update`. Enabling/disabling on an
+     * existing pool re-creates its nodes (rolling node recreation).
+     */
+    gcfsConfig?: { enabled: boolean };
   };
   /** Cluster autoscaler. Mutable via `setAutoscaling`. */
   autoscaling?: {
@@ -295,6 +303,7 @@ export const toNodeConfigCreateBody = (
       : {}),
     ...(config.gvnic ? { gvnic: config.gvnic } : {}),
     ...(config.confidentialNodes ? { confidentialNodes: config.confidentialNodes } : {}),
+    ...(config.gcfsConfig ? { gcfsConfig: config.gcfsConfig } : {}),
   };
 };
 
@@ -374,6 +383,9 @@ const toNodePoolUpdateBody = (
   if (nc.confidentialNodes && !deepEqual(oc.confidentialNodes, nc.confidentialNodes)) {
     body.confidentialNodes = nc.confidentialNodes;
   }
+  if (nc.gcfsConfig && !deepEqual(oc.gcfsConfig, nc.gcfsConfig)) {
+    body.gcfsConfig = nc.gcfsConfig;
+  }
   if (
     nc.workloadMetadataConfig &&
     !deepEqual(oc.workloadMetadataConfig, nc.workloadMetadataConfig)

package/src/Iam/ServiceAccount.ts

@@ -0,0 +1,450 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as iam from "@distilled.cloud/gcp/unstable/iam-v1";
+import { Resource } from "alchemy";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { diffTags } from "alchemy/Tags";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import {
+  descriptionHasAlchemyMarker,
+  gcpAlchemyDescription,
+  stripAlchemyMarker,
+} from "../Tags.ts";
+import type * as GCP from "../Providers.ts";
+
+/**
+ * A GCP service account (GSA). Lives under a {@link import("../CloudResourceManager/Project.ts").Project}
+ * and serves as the federated identity target for Workload Identity
+ * (`iam.gke.io/gcp-service-account: <email>` on a k8s SA) and as the
+ * principal in any IAM grant that should out-live a human user.
+ *
+ * Adoption is gated on an alchemy marker embedded in the GSA's
+ * `description` field (see `gcpAlchemyDescription` /
+ * `descriptionHasAlchemyMarker`) — GSAs have no labels field, so the
+ * label-based adoption gate used by Project can't apply. The marker is
+ * only written on insert; `description` is mutable but we never *clear*
+ * it because doing so would orphan the adoption signal.
+ *
+ * All lifecycle operations (`createProjectsServiceAccounts`,
+ * `patchProjectsServiceAccounts`, `deleteProjectsServiceAccounts`) are
+ * synchronous — no LRO polling required.
+ *
+ * @section Creating a ServiceAccount
+ * @example Minimal GSA under a project
+ * ```typescript
+ * const gsa = yield* GCP.ServiceAccount("Builder", {
+ *   project: project.projectId,
+ *   accountId: "research-builder",
+ *   displayName: "Research pod build + push (BuildKit client)",
+ * });
+ * ```
+ *
+ * @example With explicit description and Workload Identity binding
+ * ```typescript
+ * const gsa = yield* GCP.ServiceAccount("Builder", {
+ *   project: project.projectId,
+ *   accountId: "research-builder",
+ *   displayName: "Research pod build + push",
+ *   description: "Used by per-researcher BuildKit clients to push to AR.",
+ * });
+ * yield* GCP.serviceAccountIamMember(gsa, "ClusterA-WorkloadIdentity", {
+ *   role: "roles/iam.workloadIdentityUser",
+ *   member: `serviceAccount:${projectA.projectId}.svc.id.goog[researchers/build]`,
+ * });
+ * ```
+ */
+export type ServiceAccountProps = {
+  /**
+   * GCP project id (e.g. `micro-research-shared`) the GSA lives under.
+   * Immutable — changing this orphans the GSA's unique id and any
+   * bindings, so `diff` triggers a replacement.
+   */
+  project: string;
+  /**
+   * The account id segment of the service account's email. Must match
+   * `[a-z]([-a-z0-9]*[a-z0-9])`, 6-30 chars. Immutable — replaces.
+   */
+  accountId: string;
+  /**
+   * User-visible display name. Max 100 UTF-8 bytes. Mutable.
+   */
+  displayName?: string;
+  /**
+   * User-supplied description (max 256 UTF-8 bytes). The alchemy
+   * ownership marker is prepended automatically — see
+   * `gcpAlchemyDescription`. The user-supplied portion is preserved
+   * verbatim and surfaced back through `Attributes.description`.
+   */
+  description?: string;
+};
+
+/**
+ * Single (role, members) entry on a GSA's IAM policy. Targets declare
+ * this contract so capabilities (e.g. Workload Identity) can `.bind`
+ * IAM grants onto the GSA — the provider's `reconcile` merges all
+ * bound entries by role into a single `setIamPolicy` call.
+ */
+export type ServiceAccountIamBinding = {
+  /** IAM role, e.g. `"roles/iam.workloadIdentityUser"`. */
+  role: string;
+  /** Principals, e.g. `["serviceAccount:foo.svc.id.goog[ns/ksa]"]`. */
+  members: ReadonlyArray<string>;
+};
+
+export type ServiceAccountBindingContract = {
+  iamBindings: ReadonlyArray<ServiceAccountIamBinding>;
+};
+
+export type ServiceAccount = Resource<
+  "GCP.ServiceAccount",
+  ServiceAccountProps,
+  {
+    /** Full resource name, e.g. `projects/micro-research-shared/serviceAccounts/research-builder@micro-research-shared.iam.gserviceaccount.com`. */
+    name: string;
+    /** Email address derived from the account id, e.g. `research-builder@micro-research-shared.iam.gserviceaccount.com`. */
+    email: string;
+    /** Server-assigned stable numeric id. */
+    uniqueId: string;
+    /** Project the GSA lives under. */
+    projectId: string;
+    /** Account id (the part before `@`). */
+    accountId: string;
+    /** User-visible display name, or `undefined` if never set. */
+    displayName: string | undefined;
+    /** User-visible description (without the alchemy marker), or `undefined` if never set. */
+    description: string | undefined;
+    /** Whether the GSA is currently disabled. */
+    disabled: boolean;
+  },
+  ServiceAccountBindingContract,
+  GCP.Providers
+>;
+
+export const ServiceAccount = Resource<ServiceAccount>("GCP.ServiceAccount");
+
+const toAttributes = (sa: iam.ServiceAccount): ServiceAccount["Attributes"] => {
+  const accountId = (sa.email ?? "").split("@")[0];
+  return {
+    name: sa.name ?? "",
+    email: sa.email ?? "",
+    uniqueId: sa.uniqueId ?? "",
+    projectId: sa.projectId ?? "",
+    accountId,
+    displayName: sa.displayName,
+    description: stripAlchemyMarker(sa.description),
+    disabled: sa.disabled ?? false,
+  };
+};
+
+export const ServiceAccountProvider = () =>
+  Provider.effect(
+    ServiceAccount,
+    Effect.gen(function* () {
+      const getProjectsServiceAccounts = yield* iam.getProjectsServiceAccounts;
+      const createProjectsServiceAccounts = yield* iam.createProjectsServiceAccounts;
+      const patchProjectsServiceAccounts = yield* iam.patchProjectsServiceAccounts;
+      const deleteProjectsServiceAccounts = yield* iam.deleteProjectsServiceAccounts;
+      const listProjectsServiceAccounts = yield* iam.listProjectsServiceAccounts;
+      const getIamPolicyProjectsServiceAccounts = yield* iam.getIamPolicyProjectsServiceAccounts;
+      const setIamPolicyProjectsServiceAccounts = yield* iam.setIamPolicyProjectsServiceAccounts;
+
+      const resourceName = (projectId: string, accountId: string) =>
+        `projects/${projectId}/serviceAccounts/${accountId}`;
+
+      const observeServiceAccount = (projectId: string, accountId: string) =>
+        getProjectsServiceAccounts({
+          name: resourceName(projectId, accountId),
+        }).pipe(
+          // GSAs that don't exist OR that the caller can't see both
+          // collapse to "absent" — same 403→missing pattern as the
+          // project observer.
+          Effect.catchTag("NotFound", () =>
+            Effect.succeed(undefined as iam.ServiceAccount | undefined),
+          ),
+          Effect.catchTag("Forbidden", () =>
+            Effect.succeed(undefined as iam.ServiceAccount | undefined),
+          ),
+        );
+
+      const requireServiceAccount = (
+        projectId: string,
+        accountId: string,
+        context: string,
+      ) =>
+        observeServiceAccount(projectId, accountId).pipe(
+          Effect.flatMap((sa) =>
+            sa
+              ? Effect.succeed(sa)
+              : Effect.fail(
+                  new ConfigError({
+                    message: `ServiceAccount ${accountId} in project ${projectId} ${context}.`,
+                  }),
+                ),
+          ),
+        );
+
+      // List-page scan for cold recovery. Alchemy marker in the
+      // description field identifies our GSAs; the page boundary is
+      // arbitrary — we still need to page through to find any marker
+      // that happens to fall past the first page.
+      const findByAlchemyMarker = Effect.fn(function* (
+        id: string,
+        projectId: string,
+      ) {
+        let pageToken: string | undefined;
+        // Up to 100 pages × 100 items per page = 10000 GSAs; well past
+        // any realistic project size. If we ever exceed that we should
+        // cap and warn rather than silently miss matches.
+        for (let i = 0; i < 100; i++) {
+          const page = yield* listProjectsServiceAccounts({
+            name: `projects/${projectId}`,
+            ...(pageToken ? { pageToken } : {}),
+            pageSize: 100,
+          });
+          for (const sa of page.accounts ?? []) {
+            if (yield* descriptionHasAlchemyMarker(id, sa.description)) {
+              return sa;
+            }
+          }
+          pageToken = page.nextPageToken;
+          if (!pageToken) return undefined;
+        }
+        return undefined;
+      });
+
+      // Sync mutable fields: displayName + description. Both use
+      // `updateMask` so we only PATCH what actually changed. Diff
+      // against OBSERVED state, not `olds`, so adoption converges
+      // correctly when a foreign description is on the GSA.
+      const syncMutable = Effect.fn(function* (
+        observed: iam.ServiceAccount,
+        desired: {
+          displayName: string | undefined;
+          descriptionWithMarker: string;
+          descriptionUserOnly: string | undefined;
+        },
+      ) {
+        const updateMaskFields: string[] = [];
+        if (desired.displayName !== observed.displayName) {
+          updateMaskFields.push("display_name");
+        }
+        const descDiff = diffTags(
+          { description: observed.description ?? "" },
+          { description: desired.descriptionWithMarker },
+        );
+        if (
+          descDiff.removed.length > 0 ||
+          descDiff.upsert.length > 0
+        ) {
+          updateMaskFields.push("description");
+        }
+
+        if (updateMaskFields.length === 0) return observed;
+
+        return yield* patchProjectsServiceAccounts({
+          name: observed.name!,
+          body: {
+            updateMask: updateMaskFields.join(","),
+            serviceAccount: {
+              displayName: desired.displayName,
+              description: desired.descriptionWithMarker,
+            },
+          },
+        });
+      });
+
+      // Apply merged IAM bindings as a single setIamPolicy. Same
+      // foreign-binding preservation + etag-retry pattern as the
+      // Project's `syncIam` — see `src/CloudResourceManager/Project.ts:421-474`.
+      const syncIam = (args: {
+        resourceName: string;
+        bindings: ReadonlyArray<
+          import("alchemy/Resource").ResourceBinding<ServiceAccountBindingContract>
+        >;
+      }) =>
+        Effect.gen(function* () {
+          const desiredByRole = new Map<string, Set<string>>();
+          for (const b of args.bindings) {
+            for (const ib of b.data.iamBindings) {
+              const set = desiredByRole.get(ib.role) ?? new Set<string>();
+              for (const m of ib.members) set.add(m);
+              desiredByRole.set(ib.role, set);
+            }
+          }
+          if (desiredByRole.size === 0) return;
+
+          const current = yield* getIamPolicyProjectsServiceAccounts({
+            resource: args.resourceName,
+            "options.requestedPolicyVersion": 3,
+          });
+
+          const existingBindings = (current.bindings ?? []).map((b) => ({
+            ...b,
+            members: [...(b.members ?? [])],
+          }));
+          let mutated = false;
+          for (const [role, members] of desiredByRole) {
+            let existing = existingBindings.find(
+              (b) => b.role === role && !b.condition,
+            );
+            if (!existing) {
+              existing = { role, members: [] };
+              existingBindings.push(existing);
+            }
+            const merged = new Set([...(existing.members ?? []), ...members]);
+            if (merged.size !== (existing.members?.length ?? 0)) mutated = true;
+            existing.members = [...merged];
+          }
+          if (!mutated) return;
+
+          yield* setIamPolicyProjectsServiceAccounts({
+            resource: args.resourceName,
+            body: {
+              policy: { ...current, bindings: existingBindings, version: 3 },
+            },
+          });
+        }).pipe(
+          Effect.retry({
+            schedule: Schedule.exponential(Duration.seconds(2)).pipe(
+              Schedule.both(Schedule.recurs(8)),
+            ),
+          }),
+        );
+
+      return {
+        // Stable identity: accountId + project; both immutable; either
+        // change → replace. The server-assigned uniqueId is also stable
+        // for the lifetime of the GSA (re-create gets a different one).
+        stables: ["accountId", "projectId", "uniqueId", "name", "email"],
+        diff: Effect.fn(function* ({ id, news, olds = {}, output }) {
+          if (!isResolved(news)) return undefined;
+          // Replace ONLY when a prior identity is actually known AND differs.
+          // A partial/adopted state can lack the persisted accountId/projectId
+          // (an adoption that never persisted full Attributes leaves
+          // output.projectId === "" / undefined). Treating that "unknown" as a
+          // replace spuriously deletes+recreates a live, correctly-named GSA
+          // (and churns its uniqueId → breaks Workload-Identity bindings).
+          // When the prior identity is absent, fall through to reconcile, which
+          // observes the live resource and re-persists its Attributes. The
+          // truthiness guard covers both `undefined` and the `""` toAttributes
+          // default; a genuine accountId/project change still has a non-empty
+          // prior value to compare against, so real replacements are unaffected.
+          // `||` (not `??`): toAttributes persists `accountId`/`projectId` as
+          // `""` when absent, and an empty string must fall through to `olds`
+          // (the previous Props) rather than mask it — otherwise a genuine
+          // identity change with an empty `output` but a populated `olds` would
+          // skip the replace and adopt/create at the new identity without
+          // deleting the old GSA.
+          const priorAccount = output?.accountId || olds.accountId;
+          const priorProject = output?.projectId || olds.project;
+          if (
+            (priorAccount && news.accountId !== priorAccount) ||
+            (priorProject && news.project !== priorProject)
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, bindings }) {
+          const descriptionWithMarker = yield* gcpAlchemyDescription(
+            id,
+            news.description,
+          );
+
+          // 1. Observe — cloud state is authoritative. A second
+          //    scan-by-marker covers the cold-recovery case where
+          //    persisted `output`/`olds` lost the uniqueId after
+          //    state loss. We prefer the direct-by-name probe first
+          //    (cheap) and fall back to the scan only when direct
+          //    observation returned `undefined`.
+          let observed = yield* observeServiceAccount(news.project, news.accountId);
+          if (!observed) {
+            observed = yield* findByAlchemyMarker(id, news.project);
+          }
+
+          // 2. Ensure — create if missing. createProjectsServiceAccounts
+          //    is synchronous (returns the SA, not an LRO). Conflict
+          //    covers a peer reconciler race — re-observe.
+          if (!observed) {
+            observed = yield* createProjectsServiceAccounts({
+              name: `projects/${news.project}`,
+              body: {
+                accountId: news.accountId,
+                serviceAccount: {
+                  displayName: news.displayName,
+                  description: descriptionWithMarker,
+                },
+              },
+            }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as iam.ServiceAccount | undefined),
+              ),
+            );
+
+            if (!observed) {
+              observed = yield* requireServiceAccount(
+                news.project,
+                news.accountId,
+                "did not appear after create",
+              );
+            }
+          }
+
+          // 3. Sync mutable fields against OBSERVED state.
+          const synced = yield* syncMutable(observed, {
+            displayName: news.displayName ?? observed.displayName,
+            descriptionWithMarker,
+            descriptionUserOnly: news.description,
+          });
+
+          // 4. Sync IAM bindings (Workload Identity, impersonators, …).
+          //    Single setIamPolicy on the GSA with merged bindings;
+          //    foreign roles preserved. Etag-retried internally.
+          yield* syncIam({
+            resourceName: synced.name!,
+            bindings,
+          });
+
+          return toAttributes(synced);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          // Synchronous delete — Empty response, no LRO. NotFound
+          // means the GSA was already deleted (or never existed in our
+          // scope); both are idempotent successes.
+          yield* deleteProjectsServiceAccounts({
+            name: output.name,
+          }).pipe(
+            Effect.catchTag("NotFound", () => Effect.void),
+            Effect.catchTag("Forbidden", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+          // Direct-by-name probe when we have any handle on the
+          // accountId. Falls back to a project-wide scan-by-marker
+          // for cold recovery after state loss.
+          const accountId =
+            output?.accountId ?? olds?.accountId;
+          const projectId =
+            output?.projectId ?? olds?.project;
+
+          let observed: iam.ServiceAccount | undefined;
+          if (accountId && projectId) {
+            observed = yield* observeServiceAccount(projectId, accountId);
+          }
+          if (!observed && projectId) {
+            observed = yield* findByAlchemyMarker(id, projectId);
+          }
+          if (!observed) return undefined;
+
+          const attrs = toAttributes(observed);
+          // Adoption gate via description marker (see Tags.ts §description).
+          return (yield* descriptionHasAlchemyMarker(id, observed.description))
+            ? attrs
+            : Unowned(attrs);
+        }),
+      };
+    }),
+  );