@homeflare/alchemy 0.29.0 → 0.30.0

package/src/github/declare-repo-baseline.ts

@@ -18,6 +18,24 @@
  * ⛔ NO IMPORT FROM `@homeflare/config`, either direction — see `renderRepoShape`'s own header
  *   in `packages/config/src/repo-shape/render.ts`. A caller spreads `renderRepoShape(shape)
  *   .policy` into these options itself; `checks` only needs to be `readonly string[]`.
+ *
+ * ⛔ APPLY ORDER: `allowAutoMerge` NEVER GOES LIVE BEFORE THE RULESET IT WAITS ON. When `checks`
+ *   is non-empty, the ruleset is declared and applied FIRST, and the repository's `allowAutoMerge`
+ *   is threaded through `gateAutoMergeOnRuleset` (repo-auto-merge-gate.ts) so Alchemy's own
+ *   Output-in-props ordering — not declaration order — makes the engine wait for it. See that
+ *   file's header for the full mechanism, the K5 hazard it closes, and why the reverse direction
+ *   (checks removed) needs no matching edge.
+ * ⚠️ A REPOSITORY THAT DOES NOT YET EXIST: `adopt(true)` above does NOT refuse to create — with
+ *   nothing live to adopt, Alchemy creates from scratch regardless (`AdoptPolicy`'s own contract:
+ *   `undefined` observed state means create, adopt policy or not). The paragraph above says this
+ *   baseline is "never for creating one out from under a caller who forgot the flag", but nothing
+ *   enforces that; it is the caller's discipline, not this function's. If it IS ever called for a
+ *   repo+ruleset that do not exist yet with `checks` non-empty from day one, the forced
+ *   ruleset-first order above now makes the ruleset's create fail — GitHub's own ruleset API
+ *   404s on a repository that does not exist — instead of racing. That failure is explicit and
+ *   tested (declare-repo-baseline-apply-order.test.ts's "created together" case), not a silent
+ *   fail-open, but it is still a real usability regression for that one scenario: create the bare
+ *   repository first (a prior deploy, or a separate `GitHub.Repository` call).
  */
 import { adopt } from 'alchemy/AdoptPolicy';
 import * as GitHub from 'alchemy/GitHub';
@@ -28,6 +46,7 @@ import {
   repoBaselineRuleset,
   repoBaselineSettings,
 } from './repo-baseline-data.ts';
+import { gateAutoMergeOnRuleset } from './repo-auto-merge-gate.ts';
 import { RepositoryRuleset } from './repository-ruleset.ts';
 
 export interface DeclareRepoBaselineOptions extends RepoBaselineInput {}
@@ -36,7 +55,21 @@ export const declareRepoBaseline = (id: string, options: DeclareRepoBaselineOpti
   Effect.gen(function* () {
     const owned = <A, R>(resource: Effect.Effect<A, never, R>) =>
       resource.pipe(RemovalPolicy.retain(), adopt(true));
-    const repository = yield* owned(GitHub.Repository(id, repoBaselineSettings(options)));
+    const settings = repoBaselineSettings(options);
+
+    // Auto-merge is turning on (or staying on): declare and apply the ruleset FIRST, so its
+    // rulesetId is available to gate the repository's allowAutoMerge — see the file header.
+    if (settings.allowAutoMerge) {
+      const ruleset = yield* owned(
+        RepositoryRuleset(`${id}-ruleset`, repoBaselineRuleset(options)),
+      );
+      const repository = yield* owned(
+        GitHub.Repository(id, gateAutoMergeOnRuleset(settings, ruleset)),
+      );
+      return { repository, ruleset };
+    }
+
+    const repository = yield* owned(GitHub.Repository(id, settings));
     const ruleset = yield* owned(RepositoryRuleset(`${id}-ruleset`, repoBaselineRuleset(options)));
     return { repository, ruleset };
   });

package/src/github/repo-apply-order-fake-providers.ts

@@ -0,0 +1,119 @@
+/**
+ * Fully in-memory `Provider.succeed(...)` fakes for `GitHub.Repository` and `RepositoryRuleset`
+ * — no octokit, no `GitHubCredentials`, no network. Unlike `repository-ruleset-fake-octokit.ts`
+ * (a fake HTTP client fed into the REAL provider's `reconcile`), these fakes replace the provider
+ * entirely, because what `declare-repo-baseline-apply-order.test.ts` and
+ * `repo-policy-apply-order.test.ts` measure is the ENGINE's own scheduling — which resource's
+ * `reconcile` runs first, and whether one's failure reaches the other — not GitHub's wire
+ * protocol. `Provider.succeed`'s runtime lookup (`tryFindProviderRegistrationByType`,
+ * `node_modules/alchemy/src/Provider.ts`) checks the INDIVIDUAL `Provider<R>` tag before falling
+ * back to a `GitHub.Providers` collection, so registering these two standalone providers is
+ * enough regardless of `GitHub.Repository`'s own declared `Providers` slot — the same shortcut
+ * `RepositoryRulesetProvider()` already relies on.
+ *
+ * ⚠️ NO LIVE NETWORK, EVER. Nothing here imports `octokit`/`GitHubCredentials`, so a test built
+ *   on this file cannot make a real GitHub call even by accident — required by this PR's own
+ *   "no live GitHub writes" rule.
+ *
+ * ⚠️ THE FAKE RULESET REFUSES A REPO THAT DOESN'T EXIST YET, ON PURPOSE — mirroring GitHub's own
+ *   `POST /repos/{owner}/{repo}/rulesets`, which 404s on a repo that hasn't been created. A first
+ *   ADVERSARIAL REVIEW pass (2026-09-24) on this PR found that the ordering fix forces the
+ *   ruleset to apply before the repository whenever auto-merge turns on — safe for an UPDATE
+ *   (the repo already exists), but a real hazard for a repo+ruleset created together for the
+ *   FIRST time with checks set from day one, and the original version of this fake modeled no
+ *   such constraint, so its own tests could not have caught that regression. It now can — see
+ *   `declare-repo-baseline-apply-order.test.ts`'s "a repo and ruleset created together" test.
+ */
+import * as GitHub from 'alchemy/GitHub';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { RepositoryRuleset, type RepositoryRulesetProps } from './repository-ruleset.ts';
+
+/** One resource type's name, in the order its fake `reconcile` was actually invoked. */
+export type CallLog = ('repository' | 'ruleset')[];
+
+export interface World {
+  readonly calls: CallLog;
+  /** `owner/name` of every repository the fake repository provider has reconciled at least
+   * once — what the fake ruleset provider checks before allowing a create. */
+  readonly liveRepositories: Set<string>;
+  /** Set before `deploy` to make the ruleset's `reconcile` fail instead of succeeding, even
+   * against a repository already in `liveRepositories`. */
+  rulesetShouldFail: boolean;
+  /** `news.allowAutoMerge` as the repository's fake `reconcile` last observed it — `undefined`
+   * until (unless) the repository's `reconcile` actually runs. */
+  repositoryAllowAutoMerge: boolean | undefined;
+}
+
+export const makeWorld = (): World => ({
+  calls: [],
+  liveRepositories: new Set(),
+  rulesetShouldFail: false,
+  repositoryAllowAutoMerge: undefined,
+});
+
+let sequence = 0;
+const nextId = () => {
+  sequence += 1;
+  return sequence;
+};
+
+const fakeRepositoryProvider = (world: World) =>
+  Provider.succeed(GitHub.Repository, {
+    list: () => Effect.succeed([]),
+    reconcile: ({ news }: { readonly news: GitHub.RepositoryProps }) =>
+      Effect.sync(() => {
+        world.calls.push('repository');
+        world.repositoryAllowAutoMerge = news.allowAutoMerge;
+        const id = nextId();
+        const fullName = `${news.owner}/${news.name}`;
+        world.liveRepositories.add(fullName);
+        return {
+          repoId: id,
+          nodeId: `repo-node-${id}`,
+          fullName,
+          htmlUrl: `https://github.com/${fullName}`,
+          gitUrl: `git://github.com/${fullName}.git`,
+          sshUrl: `git@github.com:${fullName}.git`,
+          cloneUrl: `https://github.com/${fullName}.git`,
+          defaultBranch: 'main',
+          createdAt: new Date(0).toISOString(),
+          updatedAt: new Date(0).toISOString(),
+        };
+      }),
+    delete: () => Effect.void,
+  });
+
+const fakeRulesetProvider = (world: World) =>
+  Provider.succeed(RepositoryRuleset, {
+    list: () => Effect.succeed([]),
+    reconcile: ({ news }: { readonly news: RepositoryRulesetProps }) =>
+      Effect.gen(function* () {
+        world.calls.push('ruleset');
+        if (world.rulesetShouldFail) {
+          return yield* Effect.fail(new Error('fake ruleset apply failure'));
+        }
+        const fullName = `${news.owner}/${news.repository}`;
+        if (!world.liveRepositories.has(fullName)) {
+          // The real `POST /repos/{owner}/{repo}/rulesets` 404s here — the target repository
+          // does not exist yet. See this file's header.
+          return yield* Effect.fail(
+            new Error(`fake GitHub 404: repository '${fullName}' does not exist yet`),
+          );
+        }
+        const id = nextId();
+        return {
+          rulesetId: id,
+          nodeId: `ruleset-node-${id}`,
+          name: news.name,
+          createdAt: new Date(0).toISOString(),
+          updatedAt: new Date(0).toISOString(),
+        };
+      }),
+    delete: () => Effect.void,
+  });
+
+/** Both fakes, merged — everything `declareRepoBaseline`/`declareRepoPolicy` need. */
+export const fakeGithubProviders = (world: World) =>
+  Layer.mergeAll(fakeRepositoryProvider(world), fakeRulesetProvider(world));

package/src/github/repo-apply-order-fake-stack.ts

@@ -0,0 +1,74 @@
+/**
+ * Alchemy's own `Plan.make`/`apply`, run in-process over an in-memory state store, for
+ * `declare-repo-baseline-apply-order.test.ts` and `repo-policy-apply-order.test.ts`.
+ *
+ * ★ SAME SHAPE AS `litellm/fake-stack.ts` AND `openbao/fake-stack.ts` — copied, not
+ *   reinvented: those two files' own headers explain why the ENGINE has to run (a `diff`/`props`
+ *   answer proves nothing about what Apply actually schedules) rather than calling provider
+ *   handlers directly, which is exactly what this PR needs to prove about apply ORDER. The casts
+ *   below sit at the same typed boundary theirs do — `Alchemy.Stack` types its body against
+ *   every service a CLI run provides; this harness's body only ever needs the providers given.
+ */
+import * as Alchemy from 'alchemy';
+import { AdoptPolicy } from 'alchemy/AdoptPolicy';
+import { provideFreshArtifactStore } from 'alchemy/Artifacts';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+export type Planned = Readonly<Record<string, string>>;
+export type StackBody = Effect.Effect<unknown, unknown, unknown>;
+export type DeployOptions = { readonly adopt?: boolean };
+
+export interface FakeStack {
+  /** Plan, then apply, `body`. Resolves to the plan; rejects with the apply's failure. */
+  readonly deploy: (body: StackBody, options?: DeployOptions) => Promise<Planned>;
+}
+
+type Node = { readonly action: string };
+type PlanView = {
+  readonly resources: Readonly<Record<string, Node>>;
+  readonly deletions: Readonly<Record<string, Node | undefined>>;
+};
+
+const actionsOf = (plan: PlanView): Planned => {
+  const out: Record<string, string> = {};
+  for (const [fqn, node] of Object.entries(plan.resources)) out[fqn] = node.action;
+  for (const [fqn, node] of Object.entries(plan.deletions)) {
+    if (node !== undefined) out[fqn] = node.action;
+  }
+  return out;
+};
+
+export const fakeStack = <ROut, E, RIn>(
+  providers: Layer.Layer<ROut, E, RIn>,
+  name = 'RepoApplyOrderStack',
+): FakeStack => {
+  const state = Alchemy.inMemoryState();
+  const stack = Alchemy.Stack as unknown as (
+    stackName: string,
+    options: { providers: typeof providers; state: typeof state },
+    body: StackBody,
+  ) => Effect.Effect<{ readonly services: never }, unknown, never>;
+  const plan = Alchemy.Plan.make as unknown as (
+    compiled: unknown,
+  ) => Effect.Effect<PlanView, unknown, never>;
+  const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+
+  const deploy = (body: StackBody, options: DeployOptions = {}) =>
+    Effect.gen(function* () {
+      const compiled = yield* stack(name, { providers, state }, body);
+      return yield* Effect.gen(function* () {
+        const planned = yield* plan(compiled);
+        yield* apply(planned);
+        return actionsOf(planned);
+      }).pipe(provideFreshArtifactStore, Effect.provide(Layer.succeedContext(compiled.services)));
+    }).pipe(
+      options.adopt === undefined ? (e) => e : Effect.provideService(AdoptPolicy, options.adopt),
+      Effect.provideService(Alchemy.Stage, 'test'),
+      Effect.scoped,
+    );
+
+  return {
+    deploy: (body, options) => Effect.runPromise(deploy(body, options) as Effect.Effect<Planned>),
+  };
+};

package/src/github/repo-auto-merge-gate.ts

@@ -0,0 +1,57 @@
+/**
+ * `gateAutoMergeOnRuleset` — the one place `declareRepoBaseline` and `declareRepoPolicy` thread
+ * a real apply-ordering edge from `GitHub.Repository`'s `allowAutoMerge` to the sibling
+ * `RepositoryRuleset`, so a deploy can never turn auto-merge on before the ruleset's required
+ * checks/approvals are actually live.
+ *
+ * ⛔ K5 (kit PR 216, 2026-09-24): both callers declare `GitHub.Repository` and `RepositoryRuleset`
+ *   as two INDEPENDENT resources with no dependency edge between them. When a repo moves from
+ *   `checks:[]` to `checks:['x']`, `allowAutoMerge` flips to `true` in the very same deploy that
+ *   adds the required check. If the Repository apply lands before the Ruleset apply — or the
+ *   Ruleset apply fails outright — the repo ends up with auto-merge on and nothing required: `gh
+ *   pr merge --auto` merges a CLEAN pull request immediately (memory `gh-auto-merge-merges-now`).
+ *   That fail-open state is exactly what K5 exists to prevent.
+ *
+ * ★ THE MECHANISM — ALCHEMY ORDERS BY OUTPUT REFERENCES IN PROPS, NOT DECLARATION ORDER.
+ *   `Plan.ts` (~l.1031-1038): a resource's upstream deps are `Output.upstreamAny(resource.Props)`.
+ *   `Apply.ts` (~l.760-762, ~l.909): `waitForDeps(allUpstreamFqns())` — built the same way from
+ *   `Output.resolveUpstream(node.props)` — runs before `reconcile`. See the kit's own
+ *   `alchemy-output-refs-order-resources` memory. `GitHub.Repository`'s upstream `RepositoryProps`
+ *   has no spare field: `reconcile` (`node_modules/alchemy/src/GitHub/Repository.ts`) sends every
+ *   declared prop straight to Octokit's create/update calls, so there is nothing to smuggle an
+ *   unrelated Output into. `allowAutoMerge` itself is the vehicle instead: its value is still
+ *   exactly `true` whenever this function is called with it already `true` — only now computed
+ *   AFTER `ruleset.rulesetId` resolves via `Output.map`, instead of written as a literal. That
+ *   single Output reference is enough for `Output.upstreamAny` to record the ruleset as this
+ *   Repository's upstream dependency, so the engine applies the ruleset first.
+ *
+ * ★ WHY THIS NEEDS NO REVERSE-DIRECTION EDGE. The opposite transition — checks/approvals
+ *   REMOVED, so `allowAutoMerge` turns off — cannot silently race the other way. Neither caller
+ *   ever declares `rules.requiredStatusChecks: false` or omits `rules.pullRequest` on purpose;
+ *   dropping `checks`/`requiredApprovals` from the options just OMITS the corresponding rule key.
+ *   `requiredChecksOmissionRefusal` and `undeclaredLiveRuleRefusal` (repository-ruleset-guards.ts)
+ *   both refuse — unconditionally, regardless of apply order — to drop a rule that is still LIVE
+ *   by omission. So the worst reachable state, whichever resource applies first, is: Repository
+ *   succeeds (auto-merge off, the correct direction anyway) and Ruleset refuses (the live rule
+ *   stays required) — never fail-open. Proved by the ordering/failure tests beside this file.
+ */
+import * as Output from 'alchemy/Output';
+
+/** The one attribute this gate needs from a declared `RepositoryRuleset`. */
+export interface AutoMergeGateSource {
+  readonly rulesetId: Output.Output<number, never>;
+}
+
+/**
+ * Returns `settings` unchanged when `allowAutoMerge` is falsy — nothing to gate, and every
+ * existing declaration with auto-merge off keeps its exact prior props (no diff, no replan).
+ * Otherwise returns `settings` with `allowAutoMerge` recomputed as an Output.map over
+ * `ruleset.rulesetId` — still resolves to `true`, now with a real dependency edge attached.
+ */
+export function gateAutoMergeOnRuleset<P extends { readonly allowAutoMerge?: boolean }>(
+  settings: P,
+  ruleset: AutoMergeGateSource,
+): P | (Omit<P, 'allowAutoMerge'> & { readonly allowAutoMerge: Output.Output<boolean, never> }) {
+  if (!settings.allowAutoMerge) return settings;
+  return { ...settings, allowAutoMerge: Output.map(ruleset.rulesetId, () => true) };
+}

package/src/github/repo-policy-apply-order.test.ts

@@ -0,0 +1,72 @@
+/**
+ * `declareRepoPolicy` through Alchemy's own Plan+Apply (repo-apply-order-fake-stack.ts) — the
+ * same K5 apply-ordering proof as declare-repo-baseline-apply-order.test.ts, for the OTHER
+ * caller of `gateAutoMergeOnRuleset`. See that file's header for why the "turning on" tests
+ * deploy twice (K5's own scenario is an update to an already-live repo+ruleset, not a cold
+ * create) and for the cold-create limitation this suite also tests explicitly.
+ */
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { type World, fakeGithubProviders, makeWorld } from './repo-apply-order-fake-providers.ts';
+import { fakeStack } from './repo-apply-order-fake-stack.ts';
+import { declareRepoPolicy } from './repo-policy.ts';
+
+let world: World;
+let stack: ReturnType<typeof fakeStack>;
+beforeEach(() => {
+  world = makeWorld();
+  stack = fakeStack(fakeGithubProviders(world));
+});
+
+const declare = (checks: readonly string[]) =>
+  declareRepoPolicy('api', { owner: 'taslabs-net', repository: 'api', checks });
+
+const declareOff = () =>
+  declareRepoPolicy('api', {
+    owner: 'taslabs-net',
+    repository: 'api',
+    checks: [],
+    autoMerge: false,
+  });
+
+describe('an existing repo moving from checks: [] to checks: ["ci"]', () => {
+  beforeEach(async () => {
+    await stack.deploy(declareOff());
+    world.calls.length = 0;
+  });
+
+  test('the update that turns auto-merge on applies the ruleset before the repository', async () => {
+    const planned = await stack.deploy(declare(['ci']));
+
+    expect(planned).toEqual({ api: 'update', 'api-ruleset': 'update' });
+    expect(world.calls).toEqual(['ruleset', 'repository']);
+    expect(world.repositoryAllowAutoMerge).toBe(true);
+  });
+
+  test('a ruleset apply failure leaves allowAutoMerge untouched', async () => {
+    world.rulesetShouldFail = true;
+
+    await expect(stack.deploy(declare(['ci']))).rejects.toBeDefined();
+
+    expect(world.calls).toEqual(['ruleset']);
+    expect(world.repositoryAllowAutoMerge).toBe(false);
+  });
+});
+
+describe('auto-merge off (autoMerge: false, no checks)', () => {
+  test('declares both with no ordering edge forced between them', async () => {
+    const planned = await stack.deploy(declareOff());
+
+    expect(planned).toEqual({ api: 'create', 'api-ruleset': 'create' });
+    expect(world.calls.sort()).toEqual(['repository', 'ruleset']);
+    expect(world.repositoryAllowAutoMerge).toBe(false);
+  });
+});
+
+describe('a repo and ruleset created together for the first time, checks from day one', () => {
+  test('fails clearly instead of silently fail-open (known, documented limit)', async () => {
+    await expect(stack.deploy(declare(['ci']))).rejects.toThrow(/does not exist yet/);
+
+    expect(world.calls).toEqual(['ruleset']);
+    expect(world.repositoryAllowAutoMerge).toBeUndefined();
+  });
+});

package/src/github/repo-policy.ts

@@ -25,11 +25,27 @@
  * ⛔ BOTH RESOURCES RETAIN. `retain` is already the vendor default for each of them; it
  *   is piped anyway so that a vendor change cannot quietly turn "drop this call from the
  *   stack" into "delete the repository" or "unprotect the default branch".
+ *
+ * ⛔ APPLY ORDER: `allowAutoMerge` NEVER GOES LIVE BEFORE THE RULESET IT WAITS ON — see
+ *   repo-auto-merge-gate.ts's header for the mechanism (Alchemy orders by Output references in
+ *   props, not declaration order), the K5 hazard it closes, and why checks/approvals being
+ *   REMOVED needs no matching reverse edge. `assertAutoMergeWaits` (repo-policy-guards.ts)
+ *   already guarantees `policy.repository.allowAutoMerge` is only ever `true` when the ruleset
+ *   carries something outstanding (checks, approvals, or both), so that one flag is the gate.
+ * ⚠️ A REPOSITORY THAT DOES NOT YET EXIST: gating on the ruleset only matters once there are open
+ *   pull requests to prematurely merge, and `GitHub.Repository`'s own `reconcile` sets
+ *   `allowAutoMerge` atomically in the SAME create call that makes the repo — no window where a
+ *   PR could exploit it. This helper's documented use (`builds`, above) is always a repo that
+ *   already converged before its ruleset's first deploy; a caller declaring both fresh in one
+ *   deploy, with checks/approvals from day one, must create the bare repository first (a prior
+ *   deploy, or a separate `GitHub.Repository` call) — GitHub's ruleset API 404s on a repo that
+ *   does not exist yet, and this gate now makes the ruleset apply before the repository.
  */
 import { adopt } from 'alchemy/AdoptPolicy';
 import * as GitHub from 'alchemy/GitHub';
 import * as RemovalPolicy from 'alchemy/RemovalPolicy';
 import * as Effect from 'effect/Effect';
+import { gateAutoMergeOnRuleset } from './repo-auto-merge-gate.ts';
 import { type RepoPolicyOptions, repoPolicy } from './repo-policy-form.ts';
 import { RepositoryRuleset } from './repository-ruleset.ts';
 
@@ -58,9 +74,20 @@ export const declareRepoPolicy = (id: string, options: DeclareRepoPolicyOptions)
       const kept = resource.pipe(RemovalPolicy.retain());
       return options.adopt === undefined ? kept : kept.pipe(adopt(options.adopt));
     };
-    const repository = yield* owned(GitHub.Repository(id, policy.repository));
     // `policy.ruleset` is a plain `RulesetProps` — every field `RepositoryRulesetProps` adds
     // over it is optional, so it needs no translation to satisfy the bridge's props.
+
+    // Auto-merge is turning on (or staying on): declare and apply the ruleset FIRST, so its
+    // rulesetId is available to gate the repository's allowAutoMerge — see the file header.
+    if (policy.repository.allowAutoMerge) {
+      const ruleset = yield* owned(RepositoryRuleset(`${id}-ruleset`, policy.ruleset));
+      const repository = yield* owned(
+        GitHub.Repository(id, gateAutoMergeOnRuleset(policy.repository, ruleset)),
+      );
+      return { policy, repository, ruleset };
+    }
+
+    const repository = yield* owned(GitHub.Repository(id, policy.repository));
     const ruleset = yield* owned(RepositoryRuleset(`${id}-ruleset`, policy.ruleset));
     return { policy, repository, ruleset };
   });

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

@@ -0,0 +1,40 @@
+/**
+ * `describeKeyRef` — proves it formats a plain reference and refuses anything key-shaped, so the
+ * one place this family turns a `GoogleWorkspaceKeyRef` into text (docs, the census handoff
+ * header) cannot be handed a real credential by mistake.
+ */
+import { describe, expect, test } from 'bun:test';
+import { type GoogleWorkspaceKeyRef, describeKeyRef } from './credentials.ts';
+
+const REF: GoogleWorkspaceKeyRef = {
+  delegatedAdmin: 'admin@schenanigans.com',
+  openBaoPath: 'kv/google-workspace/service-accounts/directory-admin',
+  scopes: ['https://www.googleapis.com/auth/admin.directory.group.readonly'],
+};
+
+describe('describeKeyRef', () => {
+  test('formats a plain reference — path, delegated admin, scopes', () => {
+    const line = describeKeyRef(REF);
+    expect(line).toContain('kv/google-workspace/service-accounts/directory-admin');
+    expect(line).toContain('admin@schenanigans.com');
+    expect(line).toContain('admin.directory.group.readonly');
+  });
+
+  test('refuses an openBaoPath that looks like a PEM private key', () => {
+    expect(() =>
+      describeKeyRef({ ...REF, openBaoPath: '-----BEGIN PRIVATE KEY-----\nMIIE...' }),
+    ).toThrow(/looks like key material/);
+  });
+
+  test('refuses a scopes entry that looks like a service-account JSON blob', () => {
+    expect(() =>
+      describeKeyRef({ ...REF, scopes: ['{"type": "service_account", "private_key": "x"}'] }),
+    ).toThrow(/looks like key material/);
+  });
+
+  test('refuses a delegatedAdmin field carrying a private_key fragment', () => {
+    expect(() => describeKeyRef({ ...REF, delegatedAdmin: 'private_key leaked here' })).toThrow(
+      /looks like key material/,
+    );
+  });
+});

package/src/google-workspace/credentials.ts

@@ -0,0 +1,75 @@
+/**
+ * Google Workspace credentials for the house — a lazy reference, never the key.
+ *
+ * ⛔ THE DISTILLED SDK'S OWN `Credentials` SERVICE TAKES ONE THING: an already-minted OAuth2
+ *   bearer access token (`@distilled.cloud/google-workspace/Credentials` — read at
+ *   `node_modules/@distilled.cloud/google-workspace/src/credentials.ts`, 2026-09-24: "API-compatible
+ *   port of the distilled gcp credentials module … no ADC, no service-account signing, no refresh
+ *   flow"). It has no service-account JSON shape and no domain-wide-delegation JWT exchange built
+ *   in — minting the token is entirely outside the SDK's surface.
+ *
+ * ★ SO THE HOUSE PATTERN IS H8'S, UNCHANGED: a short-lived credential is minted from OpenBao and
+ *   exported into the DEPLOY PROCESS's environment only, by a Bun wrapper the operator runs — the
+ *   same shape the kit's Proxmox subpath already uses for its own OpenBao-sourced token. This
+ *   family adds nothing that signs a JWT or talks to Google's token endpoint; that stays Tim's
+ *   wrapper script, documented in the README, because building it here would be a second,
+ *   hand-rolled auth flow next to the one the SDK already exposes (S23).
+ *
+ * ⛔ NEVER THE KEY. `GoogleWorkspaceKeyRef` below is a REFERENCE to where a service-account key
+ *   lives — an OpenBao path, a delegated admin subject and the scopes the wrapper requests — not
+ *   the key itself. Nothing in this family reads, parses or holds private key material; `describeKeyRef`
+ *   is pure string formatting for docs and the census handoff header, and it is tested (below) to
+ *   never accept or echo anything shaped like a key.
+ *
+ * Re-exported so a consumer imports one module for both the distilled service and the house
+ * reference type: `import { CredentialsFromEnv, fromAccessToken, type GoogleWorkspaceKeyRef } from
+ * '@homeflare/alchemy/google-workspace'`.
+ */
+export {
+  type Config as GoogleWorkspaceConfig,
+  Credentials,
+  CredentialsFromEnv,
+  fromAccessToken,
+} from '@distilled.cloud/google-workspace/Credentials';
+
+/** Env var the SDK's `CredentialsFromEnv` reads — the wrapper mints into THIS var, nothing else. */
+export const GOOGLE_ACCESS_TOKEN_ENV = 'GOOGLE_ACCESS_TOKEN';
+/** Optional — only meaningful if a resource ever needs to scope a call to a GCP project. */
+export const GOOGLE_PROJECT_ID_ENV = 'GOOGLE_PROJECT_ID';
+
+/**
+ * Where the service-account key that a wrapper exchanges for `GOOGLE_ACCESS_TOKEN` lives —
+ * documentation and typing only. A stack file may keep one of these next to its declarations so
+ * the OpenBao path, delegated admin and scopes are reviewable in the same diff as the resources
+ * they authorize — nothing here reads OpenBao or Google, and no field may hold a key, a token or
+ * a private key fragment.
+ */
+export interface GoogleWorkspaceKeyRef {
+  /** OpenBao KV path, e.g. `kv/google-workspace/service-accounts/directory-admin`. */
+  readonly openBaoPath: string;
+  /** The Workspace admin the service account impersonates via domain-wide delegation. */
+  readonly delegatedAdmin: string;
+  /** OAuth scopes the wrapper requests — keep this the least the declared resources need. */
+  readonly scopes: readonly string[];
+}
+
+/** Substrings that must never appear in a `GoogleWorkspaceKeyRef` field — this is a reference. */
+const KEY_SHAPED = /-----BEGIN|private_key|"type":\s*"service_account"/i;
+
+/**
+ * A one-line, key-free description for docs and the census handoff header. Throws rather than
+ * formatting a ref whose fields look like they hold key material — a `GoogleWorkspaceKeyRef` is
+ * a pointer, and this is the one place that assumption is checked instead of assumed.
+ */
+export const describeKeyRef = (ref: GoogleWorkspaceKeyRef): string => {
+  for (const [field, value] of Object.entries(ref)) {
+    const text = Array.isArray(value) ? value.join(',') : String(value);
+    if (KEY_SHAPED.test(text)) {
+      throw new Error(`GoogleWorkspaceKeyRef.${field} looks like key material, not a reference`);
+    }
+  }
+  return (
+    `service account at OpenBao:${ref.openBaoPath}, delegating as ${ref.delegatedAdmin}, ` +
+    `scopes: ${ref.scopes.join(' ')}`
+  );
+};

package/src/google-workspace/domain-alias.test.ts

@@ -0,0 +1,69 @@
+/**
+ * `GoogleWorkspace.DomainAlias`'s `spec` against a fake Directory API — no `update` operation
+ * exists (domain-alias.ts's own note), so this only proves `fetchLive`/`attributes`/`matches`.
+ */
+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 './domain-alias.ts';
+
+const ALIAS_PATH = '/admin/directory/v1/customer/my_customer/domainaliases/alias.schenanigans.com';
+const props = { domainAliasName: 'alias.schenanigans.com', parentDomainName: 'schenanigans.com' };
+
+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.DomainAlias spec.fetchLive + spec.attributes', () => {
+  test('a live alias decodes with the default my_customer scope', async () => {
+    const fake = fakeGoogleWorkspace((method, url) =>
+      method === 'GET' && url.pathname === ALIAS_PATH
+        ? Response.json({
+            creationTime: '1700000000000',
+            domainAliasName: 'alias.schenanigans.com',
+            parentDomainName: 'schenanigans.com',
+            verified: true,
+          })
+        : fakeFailure(404, 'not found', 'NOT_FOUND'),
+    );
+    expect(await readThrough(fake.fetch)).toEqual({
+      creationTime: '1700000000000',
+      customer: 'my_customer',
+      domainAliasName: 'alias.schenanigans.com',
+      parentDomainName: 'schenanigans.com',
+      verified: true,
+    });
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGoogleWorkspace(() => fakeFailure(404, 'not found', 'NOT_FOUND'));
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+});
+
+describe('GoogleWorkspace.DomainAlias spec.matches and spec.update', () => {
+  const live = {
+    creationTime: '1700000000000',
+    customer: 'my_customer',
+    domainAliasName: 'alias.schenanigans.com',
+    parentDomainName: 'schenanigans.com',
+    verified: true,
+  };
+
+  test('the same parentDomainName is no drift', () => {
+    expect(spec.matches(live, props)).toBe(true);
+  });
+
+  test('a different parentDomainName is drift — and since there is no update, diff replaces', () => {
+    expect(spec.matches(live, { ...props, parentDomainName: 'homeflare.dev' })).toBe(false);
+    expect(spec.update).toBeUndefined();
+  });
+});