@microagi/alchemy-gcp 0.1.2

package/src/ServiceNetworking/PsaConnection.ts

@@ -0,0 +1,269 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as sn from "@distilled.cloud/gcp/servicenetworking-v1";
+import { Resource } from "alchemy";
+import type { ScopedPlanStatusSession } from "alchemy/Cli/Cli";
+import { deepEqual, isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import type { NetworkRef } from "../Compute/Network.ts";
+import type * as GCP from "../Providers.ts";
+
+/**
+ * A **Private Services Access (PSA)** connection that peers a Google
+ * service-producer VPC into the consumer VPC, drawing from one or more
+ * pre-allocated `GCP.GlobalAddress` ranges.
+ *
+ * Identity: `(network, service)`. There can only be one PSA connection
+ * per `(VPC, service)` pair, so the resource is keyed by both. The
+ * peering name (used in delete/patch URLs) is server-assigned —
+ * canonically `servicenetworking-googleapis-com` for the standard
+ * Service Networking peering — and is read off the live connection
+ * rather than reconstructed.
+ *
+ * Service Networking operations use a CRM-style `Operation.done:
+ * boolean`, not the compute `.status: "DONE"` shape, so this resource
+ * uses its own polling helper rather than the Compute one.
+ *
+ * @section Setting up PSA for Parallelstore
+ * @example
+ * ```typescript
+ * // Reserve the range first.
+ * const psaRange = yield* GCP.GlobalAddress("PsaRange", {
+ *   project: hostProject.projectId,
+ *   network: vpc.selfLink,
+ *   purpose: "VPC_PEERING",
+ *   addressType: "INTERNAL",
+ *   prefixLength: 20,
+ * });
+ *
+ * // Then peer. `networkRef` enforces the project-number form at the
+ * // type level — `Project.projectNumber` is typed as `${number}` so
+ * // this composes without manual casts.
+ * yield* GCP.PsaConnection("Psa", {
+ *   network: GCP.networkRef(hostProject.projectNumber, vpc.name),
+ *   reservedPeeringRanges: [psaRange.name],
+ * });
+ * ```
+ *
+ * The `network` field is typed as `NetworkRef` —
+ * `projects/{projectNumber}/global/networks/{name}` — because the
+ * service producer's backend resolves peerings against the numeric
+ * project id, not the project id string. Use `networkRef` to build
+ * the value; passing a project ID will fail to typecheck.
+ */
+export type PsaConnectionProps = {
+  /**
+   * Fully-qualified consumer VPC in project-number form. Build with
+   * `networkRef(project.projectNumber, vpc.name)` from `Compute/Network.ts`
+   * — that helper composes the right shape and the type system rejects
+   * passing a project ID. Immutable — replace.
+   */
+  network: NetworkRef;
+  /**
+   * Service Networking service. Defaults to `servicenetworking.googleapis.com`
+   * (the only producer that PSA-aware GCP services like Parallelstore,
+   * Cloud SQL, Memorystore peer through).
+   */
+  service?: string;
+  /**
+   * Names of `GCP.GlobalAddress` ranges (with `purpose=VPC_PEERING`) to
+   * cede to the service producer. Mutable via `patchServicesConnections`.
+   * Removing a range previously assigned requires `force=true` server-
+   * side; this provider always passes `force=true` on patch to honour
+   * the user's declared shape.
+   */
+  reservedPeeringRanges: ReadonlyArray<string>;
+};
+
+export type PsaConnectionAttributes = {
+  /** Consumer VPC URL, threaded through from props. */
+  network: NetworkRef;
+  /** `services/<service>` resource name, threaded through from props. */
+  serviceName: string;
+  /** Server-assigned peering name (e.g. `servicenetworking-googleapis-com`). */
+  peering: string;
+  /** Reserved peering ranges currently in use. */
+  reservedPeeringRanges: ReadonlyArray<string>;
+};
+
+export type PsaConnection = Resource<
+  "GCP.PsaConnection",
+  PsaConnectionProps,
+  PsaConnectionAttributes,
+  never,
+  GCP.Providers
+>;
+export const PsaConnection = Resource<PsaConnection>("GCP.PsaConnection");
+
+const DEFAULT_SERVICE = "servicenetworking.googleapis.com";
+
+const serviceParent = (service: string) =>
+  service.startsWith("services/") ? service : `services/${service}`;
+
+export const PsaConnectionProvider = () =>
+  Provider.effect(
+    PsaConnection,
+    Effect.gen(function* () {
+      const listConnections = yield* sn.listServicesConnections;
+      const createConnection = yield* sn.createServicesConnections;
+      const patchConnection = yield* sn.patchServicesConnections;
+      const deleteConnection = yield* sn.deleteConnectionServicesConnections;
+      const getOperations = yield* sn.getOperations;
+
+      const awaitOperation = Effect.fn(function* (
+        operationName: string,
+        session: ScopedPlanStatusSession,
+      ) {
+        const op = yield* getOperations({ name: operationName }).pipe(
+          Effect.flatMap((current) =>
+            current.done === true
+              ? Effect.succeed(current)
+              : Effect.fail({ _tag: "OperationPending" as const }),
+          ),
+          Effect.retry({
+            while: (e: { _tag?: string }) => e?._tag === "OperationPending",
+            schedule: Schedule.exponential(Duration.seconds(2), 1.5).pipe(
+              Schedule.either(Schedule.spaced(Duration.seconds(15))),
+              // PSA peering creates can take 5–10 min while the
+              // service producer provisions its side. 80 × 15s ≈ 20 min.
+              Schedule.both(Schedule.recurs(80)),
+              Schedule.tapOutput(() =>
+                session.note(`Waiting for ServiceNetworking operation ${operationName}…`),
+              ),
+            ),
+          }),
+        );
+        if (op.error) {
+          return yield* new ConfigError({
+            message: `ServiceNetworking operation ${operationName} failed: ${
+              op.error.message ?? JSON.stringify(op.error)
+            }`,
+          });
+        }
+        return op;
+      });
+
+      // List connections in the consumer VPC and return the matching
+      // one (there can be at most one connection per `(network, service)`
+      // pair). 404/403 collapse to "not present".
+      const observe = (parent: string, network: string) =>
+        listConnections({ parent, network }).pipe(
+          Effect.map((res) =>
+            (res.connections ?? []).find((c) => c.network === network),
+          ),
+          Effect.catchTag("NotFound", () =>
+            Effect.succeed(undefined as sn.Connection | undefined),
+          ),
+          Effect.catchTag("Forbidden", () =>
+            Effect.succeed(undefined as sn.Connection | undefined),
+          ),
+        );
+
+      return {
+        stables: ["network", "serviceName", "peering"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+          const oldsService = olds.service ?? DEFAULT_SERVICE;
+          const newsService = news.service ?? DEFAULT_SERVICE;
+          if (
+            (olds.network !== undefined && olds.network !== news.network) ||
+            (olds.service !== undefined && oldsService !== newsService)
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+          const service = news.service ?? DEFAULT_SERVICE;
+          const parent = serviceParent(service);
+          const desired = [...news.reservedPeeringRanges].sort();
+
+          let observed = yield* observe(parent, news.network);
+
+          if (!observed) {
+            const op = yield* createConnection({
+              parent,
+              body: {
+                network: news.network,
+                reservedPeeringRanges: desired,
+              },
+            }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as sn.Operation | undefined),
+              ),
+            );
+            if (op?.name) yield* awaitOperation(op.name, session);
+            observed = yield* observe(parent, news.network);
+          }
+
+          if (!observed) {
+            return yield* new ConfigError({
+              message: `PSA connection on ${news.network} did not appear after create.`,
+            });
+          }
+
+          // Sync reserved ranges. `force=true` is required when removing
+          // a previously-assigned range; we pass it unconditionally to
+          // keep the patch idempotent regardless of which direction the
+          // diff went.
+          const observedRanges = [...(observed.reservedPeeringRanges ?? [])].sort();
+          if (!deepEqual(observedRanges, desired) && observed.peering) {
+            const op = yield* patchConnection({
+              name: `${parent}/connections/${observed.peering}`,
+              force: true,
+              updateMask: "reservedPeeringRanges",
+              body: {
+                network: news.network,
+                reservedPeeringRanges: desired,
+              },
+            });
+            if (op.name) yield* awaitOperation(op.name, session);
+            observed = yield* observe(parent, news.network);
+          }
+
+          return {
+            network: news.network,
+            serviceName: parent,
+            peering: observed?.peering ?? "",
+            reservedPeeringRanges: observed?.reservedPeeringRanges ?? desired,
+          };
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          if (!output.peering) return; // Never fully created.
+          yield* deleteConnection({
+            name: `${output.serviceName}/connections/${output.peering}`,
+            body: { consumerNetwork: output.network },
+          }).pipe(
+            Effect.flatMap((op) =>
+              op.name ? awaitOperation(op.name, session) : Effect.succeed(op),
+            ),
+            Effect.catchTag("NotFound", () => Effect.void),
+            // `BadRequest` may surface when the PSA range is still in
+            // use by a managed service (Parallelstore, Cloud SQL, …)
+            // — that's a real precondition the user must resolve, so
+            // propagate it.
+          );
+        }),
+        read: Effect.fn(function* ({ output, olds }) {
+          const network = output?.network ?? olds?.network;
+          const service = olds?.service ?? DEFAULT_SERVICE;
+          const parent = output?.serviceName ?? serviceParent(service);
+          if (!network) return undefined;
+          const observed = yield* observe(parent, network);
+          if (!observed) return undefined;
+          // No ownership concept: PSA connections are unique per
+          // `(network, service)`, and the operation can only be
+          // performed by the consumer-VPC project owner. Adoption is
+          // permissive — same stance as `ApiEnable`.
+          return {
+            network,
+            serviceName: parent,
+            peering: observed.peering ?? "",
+            reservedPeeringRanges: observed.reservedPeeringRanges ?? [],
+          };
+        }),
+      };
+    }),
+  );

package/src/ServiceNetworking/index.ts

@@ -0,0 +1 @@
+export * from "./PsaConnection.ts";

package/src/ServiceUsage/ApiEnable.ts

@@ -0,0 +1,267 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as su from "@distilled.cloud/gcp/serviceusage-v1";
+import { Resource } from "alchemy";
+import type { ScopedPlanStatusSession } from "alchemy/Cli/Cli";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import type * as GCP from "../Providers.ts";
+
+/**
+ * Enable a Google Cloud API on a project (`serviceusage.googleapis.com`
+ * `services.enable`). Required before any operation against the
+ * underlying API will succeed — e.g. a fresh `GCP.Project` cannot host
+ * a `GCP.Cluster` until `container.googleapis.com` is enabled.
+ *
+ * The resource is keyed by `(project, service)`; both are immutable —
+ * changing either replaces.
+ *
+ * `delete` calls `services.disable`, which GCP rejects with HTTP 400
+ * (`FAILED_PRECONDITION`) if the service is already disabled or has
+ * dependent services in use. We treat "already disabled" as success
+ * (idempotent teardown). Other 400s propagate so the user sees the
+ * real reason (typically: another service depends on this one).
+ */
+export type ApiEnableProps = {
+  /** GCP project ID hosting the API enablement. Immutable — replace. */
+  project: string;
+  /**
+   * Fully-qualified service name, e.g. `container.googleapis.com`,
+   * `compute.googleapis.com`, `iam.googleapis.com`. Immutable — replace.
+   */
+  service: string;
+};
+
+export type ApiEnableAttributes = {
+  /** GCP project ID, threaded through from props. */
+  project: string;
+  /** Service name, threaded through from props. */
+  service: string;
+  /** Resource name in the form `projects/{project}/services/{service}`. */
+  name: string;
+  /** Lifecycle state — `"ENABLED"` once the LRO completes. */
+  state: string;
+};
+
+/**
+ * @section Enabling APIs
+ *
+ * **Dependency edges are explicit.** Alchemy sequences resources by the
+ * Output references they consume. To make a downstream resource (e.g.
+ * `GCP.Cluster`) wait for the API enable, route its `project` prop
+ * through `apiEnable.project` rather than `project.projectId`:
+ *
+ * @example Container API for GKE
+ * ```typescript
+ * const project = yield* GCP.Project("Research", { ... });
+ * const containerApi = yield* GCP.ApiEnable("ContainerApi", {
+ *   project: project.projectId,
+ *   service: "container.googleapis.com",
+ * });
+ * const cluster = yield* GCP.Cluster("Main", {
+ *   project: containerApi.project, // ← edge through ApiEnable, not Project
+ *   location: "us-central1-a",
+ *   // ...
+ * });
+ * ```
+ *
+ * If the cluster instead read `project.projectId`, alchemy would
+ * schedule the cluster create in parallel with the API enable and the
+ * GKE call would fail with `Forbidden: <X> API has not been used in
+ * project ... before or it is disabled.`
+ *
+ * @example Multiple APIs on a project
+ * ```typescript
+ * const containerApi = yield* GCP.ApiEnable("ContainerApi",
+ *   { project: project.projectId, service: "container.googleapis.com" });
+ * const computeApi = yield* GCP.ApiEnable("ComputeApi",
+ *   { project: project.projectId, service: "compute.googleapis.com" });
+ * // Then route downstream resources through the API enables that gate them:
+ * const cluster = yield* GCP.Cluster("Main", { project: containerApi.project, ... });
+ * ```
+ */
+export type ApiEnable = Resource<
+  "GCP.ApiEnable",
+  ApiEnableProps,
+  ApiEnableAttributes,
+  never,
+  GCP.Providers
+>;
+
+export const ApiEnable = Resource<ApiEnable>("GCP.ApiEnable");
+
+const fqServiceName = (project: string, service: string) =>
+  `projects/${project}/services/${service}`;
+
+export const ApiEnableProvider = () =>
+  Provider.effect(
+    ApiEnable,
+    Effect.gen(function* () {
+      const getServices = yield* su.getServices;
+      const enableServices = yield* su.enableServices;
+      const disableServices = yield* su.disableServices;
+      const getOperations = yield* su.getOperations;
+
+      // Service Usage `Operation` carries `.done: boolean` (matching CRM,
+      // NOT Container's `.status: "DONE"`), so we can't reuse the
+      // Container `makeAwaitOperation`. Mirror Project.ts's polling
+      // schedule (cheap polls for fast LROs; service enable usually
+      // resolves in <30s).
+      const awaitOperation = Effect.fn(function* (
+        operationName: string,
+        session: ScopedPlanStatusSession,
+      ) {
+        const op = yield* getOperations({ name: operationName }).pipe(
+          Effect.flatMap((current) =>
+            current.done === true
+              ? Effect.succeed(current)
+              : Effect.fail({ _tag: "OperationPending" as const }),
+          ),
+          Effect.retry({
+            while: (e: { _tag?: string }) => e?._tag === "OperationPending",
+            schedule: Schedule.exponential(Duration.seconds(1), 1.5).pipe(
+              Schedule.either(Schedule.spaced(Duration.seconds(15))),
+              Schedule.both(Schedule.recurs(60)),
+              Schedule.tapOutput(() =>
+                session.note(`Waiting for ServiceUsage operation ${operationName}…`),
+              ),
+            ),
+          }),
+        );
+        if (op.error) {
+          return yield* new ConfigError({
+            message: `ServiceUsage operation ${operationName} failed: ${
+              op.error.message ?? JSON.stringify(op.error)
+            }`,
+          });
+        }
+        return op;
+      });
+
+      return {
+        // No physical-name generation: identity is `(project, service)`.
+        // Both are static strings on `news`/`olds`/`output`.
+        stables: ["project", "service", "name"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            (olds.project !== undefined && olds.project !== news.project) ||
+            (olds.service !== undefined && olds.service !== news.service)
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+          const name = fqServiceName(news.project, news.service);
+
+          // `getServices` returns the service entity even when disabled
+          // (state="DISABLED"), so 404 here means an invalid service
+          // name, not "not enabled". Treat NotFound and Forbidden as
+          // "needs enable attempt" — the enable call will surface the
+          // real error.
+          let observed = yield* getServices({ name }).pipe(
+            Effect.catchTag("NotFound", () =>
+              Effect.succeed(undefined as su.GoogleApiServiceusageV1Service | undefined),
+            ),
+            Effect.catchTag("Forbidden", () =>
+              Effect.succeed(undefined as su.GoogleApiServiceusageV1Service | undefined),
+            ),
+          );
+
+          if (!observed || observed.state !== "ENABLED") {
+            // `Conflict` here covers concurrent enable / state-persistence
+            // race; fall through and re-observe.
+            const op = yield* enableServices({ name, body: {} }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as su.Operation | undefined),
+              ),
+            );
+            if (op?.name) yield* awaitOperation(op.name, session);
+            observed = yield* getServices({ name });
+          }
+
+          return {
+            project: news.project,
+            service: news.service,
+            name: observed.name ?? name,
+            state: observed.state ?? "ENABLED",
+          };
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          const name = fqServiceName(output.project, output.service);
+          yield* disableServices({
+            name,
+            body: { disableDependentServices: false },
+          }).pipe(
+            Effect.flatMap((op) =>
+              op.name ? awaitOperation(op.name, session) : Effect.succeed(op),
+            ),
+            Effect.catchTag("NotFound", () => Effect.void),
+            // GCP returns HTTP 400 in two important cases on disable
+            // that we treat as idempotent success:
+            //
+            // 1. Service already disabled. The resource is gone from
+            //    the user's perspective; alchemy is removing it from
+            //    state.
+            //
+            // 2. "Resources are found when disabling service(s) X.
+            //    Before you can disable, please delete the following
+            //    resources first: …" — this is GCP's eventual-
+            //    consistency lag: a sibling resource (cluster, node
+            //    pool) was deleted via its own API but ServiceUsage's
+            //    "what's still using this service" view hasn't
+            //    propagated yet. The cluster is gone; alchemy state is
+            //    being torn down; if the project itself is also being
+            //    destroyed (the typical case in `stack.destroy`), all
+            //    API state goes with it. Failing here would leave a
+            //    half-torn-down stack the user has to clean up by
+            //    hand.
+            //
+            // Other 400s (e.g. dependent *services* still enabled, or
+            // a true API-level rejection) propagate so the user sees
+            // the real failure.
+            Effect.catchTag("BadRequest", (e) =>
+              /already.*disabled|not.*currently enabled|FAILED_PRECONDITION|Resources are found/i.test(
+                e.message ?? "",
+              )
+                ? Effect.void
+                : Effect.fail(e),
+            ),
+          );
+        }),
+        read: Effect.fn(function* ({ output, olds }) {
+          const project = output?.project ?? olds?.project;
+          const service = output?.service ?? olds?.service;
+          if (!project || !service) return undefined;
+          const name = fqServiceName(project, service);
+          const observed = yield* getServices({ name }).pipe(
+            Effect.catchTag("NotFound", () =>
+              Effect.succeed(undefined as su.GoogleApiServiceusageV1Service | undefined),
+            ),
+            Effect.catchTag("Forbidden", () =>
+              Effect.succeed(undefined as su.GoogleApiServiceusageV1Service | undefined),
+            ),
+          );
+          if (!observed) return undefined;
+          // A DISABLED service is functionally absent from this
+          // resource's perspective — the engine treats `undefined` as
+          // "needs reconcile" and the next plan will re-enable.
+          if (observed.state !== "ENABLED") return undefined;
+          // No `alchemy_*` ownership labels available on services
+          // (no labels field), so we can't gate via `Unowned`.
+          // API enablement is project-scoped state, not a labeled
+          // resource — adoption is fine: any project we can read from
+          // has the API enabled regardless of who turned it on.
+          return {
+            project,
+            service,
+            name: observed.name ?? name,
+            state: observed.state,
+          };
+        }),
+      };
+    }),
+  );

package/src/ServiceUsage/index.ts

@@ -0,0 +1,2 @@
+export { ApiEnable, ApiEnableProvider } from "./ApiEnable.ts";
+export type { ApiEnableAttributes, ApiEnableProps } from "./ApiEnable.ts";

package/src/Tags.ts

@@ -0,0 +1,130 @@
+import * as Effect from "effect/Effect";
+import { Stack } from "alchemy/Stack";
+import { Stage } from "alchemy/Stage";
+
+/**
+ * GCP labels are stricter than AWS tags:
+ *
+ * - **Keys** must match `[a-z][a-z0-9_-]{0,62}`. Alchemy's default
+ *   `createInternalTags` returns keys like `alchemy::stack` — `:` is
+ *   illegal in a GCP label key, so we use `_` separators here.
+ * - **Values** must match `[a-z0-9_-]{0,63}`. We lowercase and replace
+ *   any out-of-range character with `-`.
+ *
+ * The label values together with the keys are what `read` uses to
+ * decide whether a project is owned by this stack/stage/id (returning
+ * plain attrs) or foreign (returning `Unowned(attrs)`).
+ *
+ * @see {@link https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements}
+ */
+
+const LABEL_KEY_APP = "alchemy_app";
+const LABEL_KEY_STAGE = "alchemy_stage";
+const LABEL_KEY_ID = "alchemy_id";
+
+const sanitizeLabelValue = (raw: string): string => {
+  const lowered = raw.toLowerCase();
+  const replaced = lowered.replace(/[^a-z0-9_-]/g, "-");
+  return replaced.slice(0, 63);
+};
+
+/**
+ * Compute the alchemy-internal label set for a Resource. Merge the
+ * result with user-provided labels (user wins on key collision is
+ * deliberately disallowed — alchemy keys are reserved).
+ */
+export const gcpInternalLabels = Effect.fnUntraced(function* (id: string) {
+  const stack = yield* Stack;
+  const stage = yield* Stage;
+  return {
+    [LABEL_KEY_APP]: sanitizeLabelValue(stack.name),
+    [LABEL_KEY_STAGE]: sanitizeLabelValue(stage),
+    [LABEL_KEY_ID]: sanitizeLabelValue(id),
+  } satisfies Record<string, string>;
+});
+
+/**
+ * True when `labels` contains all three alchemy-internal keys with
+ * values matching this stack/stage/id. Used in `read` to decide
+ * adoption ownership.
+ */
+export const hasAlchemyLabels = Effect.fnUntraced(function* (
+  id: string,
+  labels: Record<string, string> | undefined,
+) {
+  if (!labels) return false;
+  const expected = yield* gcpInternalLabels(id);
+  return (
+    labels[LABEL_KEY_APP] === expected[LABEL_KEY_APP] &&
+    labels[LABEL_KEY_STAGE] === expected[LABEL_KEY_STAGE] &&
+    labels[LABEL_KEY_ID] === expected[LABEL_KEY_ID]
+  );
+});
+
+export {
+  LABEL_KEY_APP as ALCHEMY_LABEL_APP,
+  LABEL_KEY_STAGE as ALCHEMY_LABEL_STAGE,
+  LABEL_KEY_ID as ALCHEMY_LABEL_ID,
+};
+
+/**
+ * Some GCP resources (compute Networks, Subnetworks) carry no labels
+ * field, so the label-based adoption gate cannot apply. For these we
+ * encode the same `(app, stage, id)` triple as a sentinel inside the
+ * resource's `description` field — created on insert and read back on
+ * adoption.
+ *
+ * Format: `[alchemy:app=<app>,stage=<stage>,id=<id>] <user description>`.
+ * The leading bracketed segment is what `descriptionHasAlchemyMarker`
+ * matches; everything after the closing `]` is the user-supplied
+ * description and is preserved as-is. We never *update* this marker
+ * because both Network and Subnetwork treat `description` as immutable
+ * after create — the marker is only ever written on insert.
+ */
+const sanitizeMarkerValue = (raw: string): string =>
+  raw.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 63);
+
+const buildMarkerPrefix = (app: string, stage: string, id: string): string =>
+  `[alchemy:app=${sanitizeMarkerValue(app)},stage=${sanitizeMarkerValue(stage)},id=${sanitizeMarkerValue(id)}]`;
+
+/**
+ * Compose `[alchemy:...] <userDescription?>`. Pass through to the
+ * resource's `description` body field at create time.
+ */
+export const gcpAlchemyDescription = Effect.fnUntraced(function* (
+  id: string,
+  userDescription?: string,
+) {
+  const stack = yield* Stack;
+  const stage = yield* Stage;
+  const prefix = buildMarkerPrefix(stack.name, stage, id);
+  return userDescription ? `${prefix} ${userDescription}` : prefix;
+});
+
+/**
+ * True when `description` begins with an alchemy marker matching this
+ * stack/stage/id. Used in `read` for resources that lack a labels
+ * field.
+ */
+export const descriptionHasAlchemyMarker = Effect.fnUntraced(function* (
+  id: string,
+  description: string | undefined,
+) {
+  if (!description) return false;
+  const stack = yield* Stack;
+  const stage = yield* Stage;
+  const expected = buildMarkerPrefix(stack.name, stage, id);
+  return description.startsWith(expected);
+});
+
+/**
+ * Strip the leading alchemy marker (if any) and return what remains —
+ * used when surfacing the user-visible description back through
+ * Attributes. Matches whether the marker was generated by us or not;
+ * if there's no marker, returns the description unchanged.
+ */
+export const stripAlchemyMarker = (description: string | undefined): string | undefined => {
+  if (!description) return description;
+  const m = description.match(/^\[alchemy:[^\]]+\]\s?/);
+  return m ? description.slice(m[0].length) || undefined : description;
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+export { Credentials, fromADC, fromAuthProvider } from "./Auth/Credentials.ts";
+export {
+  GCP_AUTH_PROVIDER_NAME,
+  GCPAuth,
+} from "./Auth/AuthProvider.ts";
+export type {
+  GCPAuthConfig,
+  GCPResolvedCredentials,
+} from "./Auth/AuthProvider.ts";
+export * from "./CloudResourceManager/index.ts";
+export * from "./Compute/index.ts";
+export * from "./Container/index.ts";
+export * from "./Parallelstore/index.ts";
+export * from "./ServiceNetworking/index.ts";
+export * from "./ServiceUsage/index.ts";
+export * from "./Providers.ts";