@homeflare/alchemy 0.29.1 → 0.30.0

package/src/google-workspace/group.ts

@@ -0,0 +1,128 @@
+/**
+ * `GoogleWorkspace.Group` — one Admin SDK Directory group (`admin/directory/v1/groups`).
+ *
+ * ★ WHY A GROUP IS THE FIRST OBJECT CLASS, AND NOT A USER. The estate's own Cloudflare Access
+ *   policies already reference Workspace groups by name ("Schenanigans - Admin", "Schenanigans -
+ *   Google" — `docs/zero-trust-access-applications.md` in homeflare-landscape) as the Google IdP
+ *   groups an Access rule allows. A group is also the one Directory object with no foreign-key
+ *   prerequisite: `email` is the whole identity, the same reasoning `netbox/prefix.ts` gives for
+ *   starting with `Prefix` over `Device`.
+ *
+ * ⛔ USERS ARE OUT OF SCOPE FOR THIS FAMILY. `insertUsers`/`patchUsers`/`updateUsers` all accept a
+ *   `password` field on the wire `User` schema — modelling `GoogleWorkspace.User` here would put a
+ *   credential-shaped field one keystroke away from becoming a prop, and Alchemy persists props
+ *   unencrypted (S25). No stack in this estate declares a Workspace user today (measured
+ *   2026-09-24 — see docs/upstream-conformance.md), so there is no house need forcing the
+ *   question. `GroupMember` (group-member.ts) references a user by email without ever creating,
+ *   reading or storing one.
+ *
+ * ★ ADOPT-FRIENDLY BY CONSTRUCTION. `groupKey` accepts an email, alias or id; this family always
+ *   uses `email` so `fetchLive` binds the live group by the same key a human would type. An
+ *   instance that already has `admin@schenanigans.com`'s "Schenanigans - Admin" group is BOUND,
+ *   never duplicated, and `attributes` maps the full live row — the exact-as-live half of
+ *   `adopt(true)` (resource.ts's own note).
+ *
+ * ⛔ THIS RESOURCE DOES NOT DELETE BY DEFAULT. `defaultRemovalPolicy: 'retain'` — removing a group
+ *   an Access policy still names would break sign-in for everyone that rule allows. `delete` stays
+ *   fully implemented; a caller opts in with `.pipe(RemovalPolicy.destroy())`.
+ *
+ * ⛔ NO CREDENTIAL IS A PROP. `GOOGLE_ACCESS_TOKEN` is read from the environment at call time,
+ *   through `@distilled.cloud/google-workspace`'s `CredentialsFromEnv` (resource.ts) — see
+ *   credentials.ts for where that token comes from.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as directory from '@distilled.cloud/google-workspace/unstable/admin_directory_v1';
+import * as Effect from 'effect/Effect';
+import type { GoogleWorkspaceRequirements, GoogleWorkspaceSpec } from './resource.ts';
+import { googleWorkspaceHandlers } from './resource.ts';
+import { ciEqual, stringArray, text } from './values.ts';
+
+export interface GroupProps {
+  /** The group's email address — the primary key for locate, create and update alike. */
+  email: string;
+  /** Display name. @default the local part of `email` */
+  name?: string;
+  /** Free text, up to 4,096 characters per the Directory API. */
+  description?: string;
+}
+
+export interface GroupAttributes {
+  email: string;
+  name: string;
+  description: string;
+  groupId: string;
+  /** Read-only — direct members, as a decimal string on the wire (Directory's own choice). */
+  directMembersCount: string;
+  /** Read-only. Aliases outside the primary domain/subdomains; edited only via alias endpoints. */
+  nonEditableAliases: string[];
+  /** Read-only. Aliases within the account's domains; edited only via alias endpoints. */
+  aliases: string[];
+  adminCreated: boolean;
+}
+
+export interface GoogleWorkspaceGroup extends Resource<
+  'GoogleWorkspace.Group',
+  GroupProps,
+  GroupAttributes,
+  never,
+  GoogleWorkspaceRequirements
+> {}
+
+export const GoogleWorkspaceGroup = Resource<GoogleWorkspaceGroup>('GoogleWorkspace.Group', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** Un-declared `name` converges here — deterministic, so an undeclared field never drifts. */
+const defaultName = (props: GroupProps): string =>
+  props.name ?? props.email.split('@')[0] ?? props.email;
+
+const attributesOf = (live: directory.Group, props: GroupProps): GroupAttributes | undefined => {
+  if (live.email === undefined || !ciEqual(live.email, props.email)) return undefined;
+  return {
+    adminCreated: live.adminCreated === true,
+    aliases: stringArray(live.aliases),
+    description: text(live.description),
+    directMembersCount: text(live.directMembersCount),
+    email: live.email,
+    groupId: text(live.id),
+    name: text(live.name),
+    nonEditableAliases: stringArray(live.nonEditableAliases),
+  };
+};
+
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see group.test.ts. */
+export const spec: GoogleWorkspaceSpec<
+  GroupProps,
+  directory.Group,
+  GroupAttributes,
+  | directory.GetGroupsError
+  | directory.InsertGroupsError
+  | directory.PatchGroupsError
+  | directory.DeleteGroupsError
+> = {
+  attributes: attributesOf,
+  create: (props) =>
+    directory.insertGroups({
+      body: { description: props.description ?? '', email: props.email, name: defaultName(props) },
+    }),
+  describe: (props) => `groups/${props.email}`,
+  destroy: (_props, live) =>
+    directory.deleteGroups({ groupKey: text(live.id) || text(live.email) }),
+  fetchLive: (props) =>
+    directory
+      .getGroups({ groupKey: props.email })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    attributes.description === (props.description ?? '') && attributes.name === defaultName(props),
+  update: (props, live) =>
+    directory.patchGroups({
+      body: { description: props.description ?? '', name: defaultName(props) },
+      groupKey: text(live.id) || text(live.email),
+    }),
+};
+
+export const handlers = googleWorkspaceHandlers(spec);
+
+export const GoogleWorkspaceGroupProvider = () =>
+  Provider.effect(GoogleWorkspaceGroup, Effect.succeed(GoogleWorkspaceGroup.Provider.of(handlers)));

package/src/google-workspace/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Google Workspace providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. These are
+ *   the symbols a real stack consumes; the rest of the files are internals a provider needs but a
+ *   consumer should not depend on. An `export *` here would publish every helper as API and make
+ *   the next refactor a breaking change.
+ * ★ `credentials.ts`'s re-exports ARE published, because a stack needs `CredentialsFromEnv` (or
+ *   `fromAccessToken` in a test) to build a runtime layer, and `GoogleWorkspaceKeyRef` /
+ *   `describeKeyRef` are the documentation seam credential setup is meant to go through.
+ */
+export {
+  type GoogleWorkspaceConfig,
+  Credentials,
+  CredentialsFromEnv,
+  describeKeyRef,
+  fromAccessToken,
+  GOOGLE_ACCESS_TOKEN_ENV,
+  GOOGLE_PROJECT_ID_ENV,
+  type GoogleWorkspaceKeyRef,
+} from './credentials.ts';
+export {
+  GoogleWorkspaceDomainAlias,
+  GoogleWorkspaceDomainAliasProvider,
+  type DomainAliasAttributes,
+  type DomainAliasProps,
+} from './domain-alias.ts';
+export {
+  GoogleWorkspaceGroup,
+  GoogleWorkspaceGroupProvider,
+  type GroupAttributes,
+  type GroupProps,
+} from './group.ts';
+export {
+  GoogleWorkspaceGroupMember,
+  GoogleWorkspaceGroupMemberProvider,
+  type DeliverySettings,
+  type GroupMemberAttributes,
+  type GroupMemberProps,
+  type MemberRole,
+} from './group-member.ts';
+export {
+  GoogleWorkspaceOrgUnit,
+  GoogleWorkspaceOrgUnitProvider,
+  type OrgUnitAttributes,
+  type OrgUnitProps,
+} from './org-unit.ts';
+export { googleWorkspaceProviders } from './providers.ts';
+export {
+  googleWorkspaceHandlers,
+  googleWorkspaceOperations,
+  type GoogleWorkspaceRequirements,
+  type GoogleWorkspaceSpec,
+} from './resource.ts';

package/src/google-workspace/org-unit.test.ts

@@ -0,0 +1,81 @@
+/**
+ * `GoogleWorkspace.OrgUnit`'s `spec` against a fake Directory API — proves the leading-slash
+ * asymmetry `values.ts`'s `stripLeadingSlash`/`withLeadingSlash` exist for (org-unit.ts's note).
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import {
+  fakeFailure,
+  fakeGoogleWorkspace,
+  fakeGoogleWorkspaceLayer,
+} from './fake-google-workspace.ts';
+import { spec } from './org-unit.ts';
+
+const UNIT_PATH = '/admin/directory/v1/customer/my_customer/orgunits/Contractors/2026';
+const props = {
+  orgUnitPath: '/Contractors/2026',
+  parentOrgUnitPath: '/Contractors',
+  description: '2026 cohort',
+};
+
+const readThrough = (fetchFn: typeof globalThis.fetch) =>
+  Effect.runPromise(
+    spec.fetchLive(props).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+      Effect.provide(fakeGoogleWorkspaceLayer(fetchFn)),
+    ),
+  );
+
+describe('GoogleWorkspace.OrgUnit spec.fetchLive + spec.attributes', () => {
+  test('the path is sent without its leading slash, and read back with one', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === UNIT_PATH
+        ? Response.json({
+            description: '2026 cohort',
+            name: '2026',
+            orgUnitId: 'id:0123',
+            orgUnitPath: '/Contractors/2026',
+            parentOrgUnitPath: '/Contractors',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    expect(await readThrough(fake.fetch)).toEqual({
+      customerId: 'my_customer',
+      description: '2026 cohort',
+      name: '2026',
+      orgUnitId: 'id:0123',
+      orgUnitPath: '/Contractors/2026',
+      parentOrgUnitPath: '/Contractors',
+    });
+    expect(fake.seen).toEqual([{ method: 'GET', path: UNIT_PATH }]);
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(404, 'not found', 'NOT_FOUND'));
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+});
+
+describe('GoogleWorkspace.OrgUnit spec.matches', () => {
+  const live = {
+    customerId: 'my_customer',
+    description: '2026 cohort',
+    name: '2026',
+    orgUnitId: 'id:0123',
+    orgUnitPath: '/Contractors/2026',
+    parentOrgUnitPath: '/Contractors',
+  };
+
+  test('matching name, parent and description is no drift', () => {
+    expect(spec.matches(live, props)).toBe(true);
+  });
+
+  test('a moved parent is drift', () => {
+    expect(spec.matches(live, { ...props, parentOrgUnitPath: '/Employees' })).toBe(false);
+  });
+
+  test('an undeclared parentOrgUnitPath converges to the root, deterministically', () => {
+    const { parentOrgUnitPath: _p, ...rootProps } = props;
+    expect(spec.matches({ ...live, parentOrgUnitPath: '/' }, rootProps)).toBe(true);
+  });
+});

package/src/google-workspace/org-unit.ts

@@ -0,0 +1,143 @@
+/**
+ * `GoogleWorkspace.OrgUnit` — one organizational unit (`admin/directory/v1/customer/{id}/orgunits`).
+ *
+ * ★ `orgUnitPath` IS THE IDENTITY the way `NetboxPrefix.prefix` is. Google's own doc line is
+ *   copied onto `OrgUnitProps.orgUnitPath` below because it is the one field this resource cannot
+ *   get wrong: it is DERIVED on read (`parentOrgUnitPath` + `name`) but AUTHORED as a full path on
+ *   write, and the API's own path-parameter form drops the leading `/` (`GetOrgunitsRequest`'s
+ *   `orgUnitPath` doc: "the full path … minus the leading `/`"). `values.ts`'s
+ *   `stripLeadingSlash`/`withLeadingSlash` are the one place that asymmetry is handled.
+ *
+ * ⛔ THIS RESOURCE DOES NOT REMOVE SUB-UNITS OR MOVE USERS. Deleting an org unit that still has
+ *   children or members fails server-side (Directory refuses rather than cascading) — nothing
+ *   here retries around that refusal, matching S11's "observe before deleting", not "force
+ *   through".
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — an org unit governs which Workspace services a user can
+ *   reach (Google's own doc line on `orgUnitPath`); deleting one out from under live users is
+ *   exactly the kind of hard-to-reverse action this policy exists to require an explicit opt-in
+ *   for.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as directory from '@distilled.cloud/google-workspace/unstable/admin_directory_v1';
+import * as Effect from 'effect/Effect';
+import type { GoogleWorkspaceRequirements, GoogleWorkspaceSpec } from './resource.ts';
+import { googleWorkspaceHandlers } from './resource.ts';
+import { stripLeadingSlash, text, withLeadingSlash } from './values.ts';
+
+export interface OrgUnitProps {
+  /** The unique id for the Workspace account, or `my_customer` for the caller's own account. */
+  customerId?: string;
+  /**
+   * The full path to the organizational unit, e.g. `/Contractors/2026`. Required. In order to
+   * edit an `orgUnitPath`, either update `name` or `parentOrgUnitPath` — this field is derived on
+   * read, not itself patchable, so declaring a different path here plans a `replace`.
+   */
+  orgUnitPath: string;
+  /** The parent's full path, e.g. `/Contractors`. Omit for a top-level unit under `/`. */
+  parentOrgUnitPath?: string;
+  description?: string;
+}
+
+export interface OrgUnitAttributes {
+  customerId: string;
+  orgUnitPath: string;
+  parentOrgUnitPath: string;
+  name: string;
+  description: string;
+  orgUnitId: string;
+}
+
+export interface GoogleWorkspaceOrgUnit extends Resource<
+  'GoogleWorkspace.OrgUnit',
+  OrgUnitProps,
+  OrgUnitAttributes,
+  never,
+  GoogleWorkspaceRequirements
+> {}
+
+export const GoogleWorkspaceOrgUnit = Resource<GoogleWorkspaceOrgUnit>('GoogleWorkspace.OrgUnit', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const customerOf = (props: OrgUnitProps): string => props.customerId ?? 'my_customer';
+/** The path segment the API wants, split from its own leading-name component for `name`/`insert`. */
+const nameOf = (props: OrgUnitProps): string =>
+  props.orgUnitPath.split('/').filter(Boolean).pop() ?? props.orgUnitPath;
+const parentOf = (props: OrgUnitProps): string => props.parentOrgUnitPath ?? '/';
+
+const attributesOf = (
+  live: directory.OrgUnit,
+  props: OrgUnitProps,
+): OrgUnitAttributes | undefined => {
+  const livePath = live.orgUnitPath === undefined ? undefined : withLeadingSlash(live.orgUnitPath);
+  if (livePath === undefined || livePath.toLowerCase() !== props.orgUnitPath.toLowerCase()) {
+    return undefined;
+  }
+  return {
+    customerId: customerOf(props),
+    description: text(live.description),
+    name: text(live.name),
+    orgUnitId: text(live.orgUnitId),
+    orgUnitPath: livePath,
+    parentOrgUnitPath: text(live.parentOrgUnitPath),
+  };
+};
+
+/** ★ EXPORTED for direct testing — see org-unit.test.ts. */
+export const spec: GoogleWorkspaceSpec<
+  OrgUnitProps,
+  directory.OrgUnit,
+  OrgUnitAttributes,
+  | directory.GetOrgunitsError
+  | directory.InsertOrgunitsError
+  | directory.PatchOrgunitsError
+  | directory.DeleteOrgunitsError
+> = {
+  attributes: attributesOf,
+  create: (props) =>
+    directory.insertOrgunits({
+      body: {
+        description: props.description ?? '',
+        name: nameOf(props),
+        parentOrgUnitPath: parentOf(props),
+      },
+      customerId: customerOf(props),
+    }),
+  describe: (props) => `customer/${customerOf(props)}/orgunits${props.orgUnitPath}`,
+  destroy: (props, live) =>
+    directory.deleteOrgunits({
+      customerId: customerOf(props),
+      orgUnitPath: stripLeadingSlash(text(live.orgUnitPath) || props.orgUnitPath),
+    }),
+  fetchLive: (props) =>
+    directory
+      .getOrgunits({
+        customerId: customerOf(props),
+        orgUnitPath: stripLeadingSlash(props.orgUnitPath),
+      })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    attributes.description === (props.description ?? '') &&
+    attributes.parentOrgUnitPath === parentOf(props) &&
+    attributes.name === nameOf(props),
+  update: (props, live) =>
+    directory.patchOrgunits({
+      body: {
+        description: props.description ?? '',
+        name: nameOf(props),
+        parentOrgUnitPath: parentOf(props),
+      },
+      customerId: customerOf(props),
+      orgUnitPath: stripLeadingSlash(text(live.orgUnitPath) || props.orgUnitPath),
+    }),
+};
+
+export const handlers = googleWorkspaceHandlers(spec);
+
+export const GoogleWorkspaceOrgUnitProvider = () =>
+  Provider.effect(
+    GoogleWorkspaceOrgUnit,
+    Effect.succeed(GoogleWorkspaceOrgUnit.Provider.of(handlers)),
+  );

package/src/google-workspace/providers.ts

@@ -0,0 +1,26 @@
+/**
+ * Every Google Workspace provider, wired once — the same role `litellmProviders`/`netboxProviders`-
+ * style helpers play elsewhere in this kit (S16: "a subpath's `providers()` plays the same role" as
+ * upstream's `Providers.ts`).
+ *
+ *     Layer.mergeAll(googleWorkspaceProviders(), …the stack's other providers)
+ *
+ * ⚠️ CREDENTIALS ARE NOT A PARAMETER HERE. Every handler already closes over
+ *   `CredentialsFromEnv` inside `resource.ts` (`GOOGLE_ACCESS_TOKEN`, resolved at call time — see
+ *   credentials.ts), so this layer only wires the four resource providers together. `HttpClient`
+ *   is NOT provided here either — it is ambient in every Alchemy runtime, the same note
+ *   `litellm/providers.ts` makes for its own family.
+ */
+import * as Layer from 'effect/Layer';
+import { GoogleWorkspaceDomainAliasProvider } from './domain-alias.ts';
+import { GoogleWorkspaceGroupProvider } from './group.ts';
+import { GoogleWorkspaceGroupMemberProvider } from './group-member.ts';
+import { GoogleWorkspaceOrgUnitProvider } from './org-unit.ts';
+
+export const googleWorkspaceProviders = () =>
+  Layer.mergeAll(
+    GoogleWorkspaceGroupProvider(),
+    GoogleWorkspaceGroupMemberProvider(),
+    GoogleWorkspaceDomainAliasProvider(),
+    GoogleWorkspaceOrgUnitProvider(),
+  );

package/src/google-workspace/resource.test.ts

@@ -0,0 +1,186 @@
+/**
+ * `googleWorkspaceOperations`'s shared `diff`/`reconcile` engine, exercised end-to-end through a
+ * fake Directory API — not just through a resource's own `spec.matches`/`fetchLive` in isolation.
+ *
+ * 🔴 WHY THIS FILE EXISTS. An adversarial review of this family (2026-09-24) found that every
+ *   other test here calls `spec.fetchLive`/`spec.attributes`/`spec.matches` directly and never
+ *   `googleWorkspaceOperations(spec).diff`/`.reconcile` — so a bug INSIDE `resource.ts` itself
+ *   (shared by all four resources) could invert `diff`'s `noop`/`update` branches, or skip the
+ *   "write returned no error but the object is still absent" die-guard, and no test here would
+ *   catch it. This file closes that gap: it drives the real engine against real specs (`group.ts`,
+ *   whose spec HAS `update`, and `domain-alias.ts`, whose spec does NOT), through the same fake
+ *   HTTP layer every other test in this family uses.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { spec as aliasSpec } from './domain-alias.ts';
+import {
+  fakeFailure,
+  fakeGoogleWorkspace,
+  fakeGoogleWorkspaceLayer,
+} from './fake-google-workspace.ts';
+import { spec as groupSpec } from './group.ts';
+import { googleWorkspaceOperations } from './resource.ts';
+
+const groupOps = googleWorkspaceOperations(groupSpec);
+const groupProps = { email: 'ops@schenanigans.com', name: 'Ops', description: 'ops team' };
+const GROUP_PATH = '/admin/directory/v1/groups/ops%40schenanigans.com';
+
+describe('googleWorkspaceOperations(group spec).reconcile', () => {
+  test('absent → create, then read back — the happy create path', async () => {
+    let created = false;
+    const fake = fakeGoogleWorkspace((method, url) => {
+      if (method === 'POST' && url.pathname === '/admin/directory/v1/groups') {
+        created = true;
+        return Response.json({ email: groupProps.email, name: 'Ops' });
+      }
+      if (method === 'GET' && url.pathname === GROUP_PATH) {
+        return created
+          ? Response.json({ description: 'ops team', email: groupProps.email, name: 'Ops' })
+          : fakeFailure(404, 'not found', 'NOT_FOUND');
+      }
+      return fakeFailure(404, 'not found', 'NOT_FOUND');
+    });
+    const attrs = await Effect.runPromise(
+      groupOps.reconcile(groupProps).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(created).toBe(true);
+    expect(attrs.email).toBe(groupProps.email);
+  });
+
+  test('present and matching → no PATCH is ever sent', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === GROUP_PATH
+        ? Response.json({ description: 'ops team', email: groupProps.email, name: 'Ops' })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    await Effect.runPromise(
+      groupOps.reconcile(groupProps).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((r) => r.method === 'PATCH')).toBe(false);
+  });
+
+  test('present and drifted → PATCH is sent exactly once', async () => {
+    let patched = false;
+    const fake = fakeGoogleWorkspace((method, url) => {
+      if (method === 'PATCH' && url.pathname === GROUP_PATH) {
+        patched = true;
+        return Response.json({ description: 'ops team', email: groupProps.email, name: 'Ops' });
+      }
+      if (method === 'GET' && url.pathname === GROUP_PATH) {
+        return Response.json({
+          description: 'stale description',
+          email: groupProps.email,
+          name: 'Ops',
+        });
+      }
+      return fakeFailure(404, 'not found', 'NOT_FOUND');
+    });
+    await Effect.runPromise(
+      groupOps.reconcile(groupProps).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(patched).toBe(true);
+  });
+
+  test('a write that reports success but leaves the object absent dies — never lies to the plan', async () => {
+    const fake = fakeGoogleWorkspace(
+      (method, url) =>
+        method === 'POST' && url.pathname === '/admin/directory/v1/groups'
+          ? Response.json({})
+          : fakeFailure(404, 'not found', 'NOT_FOUND'), // every GET stays 404, even after "create"
+    );
+    const failed = await Effect.runPromiseExit(
+      groupOps.reconcile(groupProps).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(failed._tag).toBe('Failure');
+  });
+});
+
+describe('googleWorkspaceOperations(group spec).diff', () => {
+  const live = {
+    adminCreated: false,
+    aliases: [],
+    description: 'ops team',
+    directMembersCount: '0',
+    email: groupProps.email,
+    groupId: 'x',
+    name: 'Ops',
+    nonEditableAliases: [],
+  };
+
+  test('output undefined → undefined (engine default: treat as update)', async () => {
+    // ⚠️ `diff` short-circuits on `output === undefined` before it ever reads — no request is
+    //   made — but the Effect's TYPE still carries `GoogleWorkspaceOpContext`, so a layer is
+    //   still required to satisfy `runPromise`. `fake.seen` below proves the short-circuit.
+    const fake = fakeGoogleWorkspace(() => fakeFailure(500, 'must not be called', 'INTERNAL'));
+    const result = await Effect.runPromise(
+      groupOps
+        .diff(groupProps, undefined)
+        .pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('matching live → noop, read through the real fake', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === GROUP_PATH
+        ? Response.json({ description: 'ops team', email: groupProps.email, name: 'Ops' })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    const result = await Effect.runPromise(
+      groupOps.diff(groupProps, live).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  test('drifted live, spec HAS update → action is update, not replace', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === GROUP_PATH
+        ? Response.json({
+            description: 'a different description',
+            email: groupProps.email,
+            name: 'Ops',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    const result = await Effect.runPromise(
+      groupOps.diff(groupProps, live).pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'update' });
+  });
+});
+
+describe('googleWorkspaceOperations(domain-alias spec).diff — spec has NO update', () => {
+  const aliasOps = googleWorkspaceOperations(aliasSpec);
+  const aliasProps = {
+    domainAliasName: 'alias.schenanigans.com',
+    parentDomainName: 'schenanigans.com',
+  };
+  const ALIAS_PATH =
+    '/admin/directory/v1/customer/my_customer/domainaliases/alias.schenanigans.com';
+  const liveAttrs = {
+    creationTime: '0',
+    customer: 'my_customer',
+    domainAliasName: aliasProps.domainAliasName,
+    parentDomainName: aliasProps.parentDomainName,
+    verified: true,
+  };
+
+  test('drifted live, spec has NO update → replace, never update', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === ALIAS_PATH
+        ? Response.json({
+            domainAliasName: aliasProps.domainAliasName,
+            parentDomainName: 'homeflare.dev',
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    const result = await Effect.runPromise(
+      aliasOps
+        .diff(aliasProps, liveAttrs)
+        .pipe(Effect.provide(fakeGoogleWorkspaceLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'replace' });
+  });
+});