@homeflare/alchemy 0.1.0

package/src/openbao/cloudflare-permission-groups.test.ts

@@ -0,0 +1,369 @@
+/**
+ * Both permission-group sources against fake-bao: (a) the engine endpoint — resolved and cached per
+ * mount, the seven live two-id names separated by scope, the bucket-scoped R2 pair, unknown, a
+ * two-id name asked at a scope it is not listed at, DENIED, undeployed and still-ambiguous;
+ * (b) ⚠️ the live-roles bootstrap — resolved across an account's mounts, unknown, and ambiguous
+ * when a live role contradicts the rest.
+ *
+ * ★ (a)'s FIXTURE IS THE LIVE LIST'S SHAPE, ids and all, transcribed from `bao read
+ *   cloudflare-<account>-platform/permission-groups` on 2026-09-15 — the seven pairs are the
+ *   reason this file's key is (name, scope) and not name.
+ *
+ * ⚠️ (b)'s CASES STAY, AND ARE NOT VACUOUS, THOUGH THE STACK STOPPED WIRING IT ON 2026-09-15.
+ *   `permissionGroupsBootstrapLayer` is kept as the only source that works while the
+ *   `permission-groups` grant is unapplied (cloudflare-roles.ts), so these four are the proof it
+ *   still works when it is reached for. They retire with the function, not before.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import { GROUP_SCOPES, groupKey } from './cloudflare-group-scope.ts';
+import {
+  CloudflareGroupsError,
+  type GroupRef,
+  permissionGroupsFromEngine,
+  permissionGroupsFromLiveRoles,
+} from './cloudflare-permission-groups.ts';
+import type { ExpandedRole } from './cloudflare-roles-expand.ts';
+import { type Reply, type Seen, run, runFailure, withFake } from './fake-bao.ts';
+
+const MOUNT = 'cloudflare-acme-dns';
+
+const engine =
+  (groups: unknown[]) =>
+  (seen: Seen): Reply =>
+    seen.path === `/v1/${MOUNT}/permission-groups`
+      ? { json: { data: { permission_groups: groups } }, status: 200 }
+      : { json: { errors: [] }, status: 404 };
+
+const resolveWith = <E>(
+  source: Effect.Effect<{ resolve: (m: string, r: readonly GroupRef[]) => E }>,
+) => source;
+
+const at = (scope: string) => (name: string) => ({ name, scope });
+const zone = at(GROUP_SCOPES.zone);
+const account = at(GROUP_SCOPES.account);
+const bucket = at(GROUP_SCOPES.bucket);
+
+describe('permissionGroupsFromEngine', () => {
+  const GROUPS = [
+    { id: 'id-read', name: 'DNS Read', scopes: ['com.cloudflare.api.account.zone'] },
+    { id: 'id-write', name: 'DNS Write', scopes: ['com.cloudflare.api.account.zone'] },
+  ];
+
+  it('resolves names from GET <mount>/permission-groups, asking once per mount', async () => {
+    await withFake(engine(GROUPS), async (bao) => {
+      const resolved = await run(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(resolveWith(permissionGroupsFromEngine()), (groups) =>
+          Effect.zip(
+            groups.resolve(MOUNT, [zone('DNS Read')]),
+            groups.resolve(`${MOUNT}/`, [zone('DNS Write')]),
+          ),
+        ),
+      );
+      assert.deepEqual(
+        resolved.map((map) => Object.fromEntries(map)),
+        [
+          { [groupKey('DNS Read', GROUP_SCOPES.zone)]: 'id-read' },
+          { [groupKey('DNS Write', GROUP_SCOPES.zone)]: 'id-write' },
+        ],
+      );
+      assert.equal(bao.seen.length, 1);
+    });
+  });
+
+  /**
+   * ⛔ THE SEVEN LIVE PAIRS, TRANSCRIBED FROM `bao read cloudflare-<account>-platform/
+   *   permission-groups` ON 2026-09-15: each name listed twice, one account-scoped id and one
+   *   zone-scoped id. Keyed by name this is the failure that stopped the first engine plan; keyed
+   *   by (name, scope) each entry asks for the one its resource is gated at.
+   */
+  const AMBIGUOUS = [
+    [
+      'Access: Apps and Policies Read',
+      '7ea222f6d5064cfa89ea366d7c1fee89',
+      'eb258a38ea634c86a0c89da6b27cb6b6',
+    ],
+    [
+      'Access: Apps and Policies Revoke',
+      '6c9d1cfcfc6840a987d1b5bfb880a841',
+      '6db4e222e21248ac96a3f4c2a81e3b41',
+    ],
+    [
+      'Access: Apps and Policies Write',
+      '1e13c5124ca64b72b1969a67e8829049',
+      '959972745952452f8be2452be8cbb9f2',
+    ],
+    ['Disable ESC Read', '29eefa0805f94fdfae2b058b5b52f319', 'e199d584e69344eba202452019deafe3'],
+    ['Disable ESC Write', '18555e39c5ba40d284dde87eda845a90', '9110d9dd749e464fb9f3961a2064efc5'],
+    ['Logs Read', '6a315a56f18441e59ed03352369ae956', 'c4a30cd58c5d42619c86a3c36c441e2d'],
+    ['Logs Write', '96163bd1b0784f62b3e44ed8c2ab1eb6', '3e0b5820118e47f3922f7c989e673882'],
+  ] as const;
+
+  const LIVE_SHAPED = [
+    ...AMBIGUOUS.flatMap(([name, accountId, zoneId]) => [
+      { id: accountId, name, scopes: [GROUP_SCOPES.account] },
+      { id: zoneId, name, scopes: [GROUP_SCOPES.zone] },
+    ]),
+    // The two bucket-scoped groups the pgBackRest role needs, and their account-scoped namesakes.
+    {
+      id: 'r2-item-read',
+      name: 'Workers R2 Storage Bucket Item Read',
+      scopes: [GROUP_SCOPES.bucket],
+    },
+    {
+      id: 'r2-item-write',
+      name: 'Workers R2 Storage Bucket Item Write',
+      scopes: [GROUP_SCOPES.bucket],
+    },
+    { id: 'r2-read', name: 'Workers R2 Storage Read', scopes: [GROUP_SCOPES.account] },
+    ...GROUPS,
+  ];
+
+  it('separates the seven two-id names by the scope the asking entry is gated at', async () => {
+    await withFake(engine(LIVE_SHAPED), async (bao) => {
+      const resolved = await run(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(resolveWith(permissionGroupsFromEngine()), (groups) =>
+          groups.resolve(MOUNT, [
+            ...AMBIGUOUS.map(([name]) => account(name)),
+            ...AMBIGUOUS.map(([name]) => zone(name)),
+          ]),
+        ),
+      );
+      assert.deepEqual(
+        AMBIGUOUS.map(([name]) => [
+          resolved.get(groupKey(name, GROUP_SCOPES.account)),
+          resolved.get(groupKey(name, GROUP_SCOPES.zone)),
+        ]),
+        AMBIGUOUS.map(([, accountId, zoneId]) => [accountId, zoneId]),
+      );
+    });
+  });
+
+  /**
+   * ⛔ r2-backup-mini's ENTRY IS BUCKET-SCOPED (`bucket: homeflare-pg-mini`), and the two groups it
+   *   names are the only two the account lists at `com.cloudflare.edge.r2.bucket` — MEASURED
+   *   2026-09-15: 2 of 399. A unique name still resolves whatever scope asks, which is why the
+   *   account-scoped `Workers R2 Storage Read` here answers a bucket-scoped question too.
+   */
+  it('resolves the bucket-scoped R2 item groups, and a unique name at any scope', async () => {
+    await withFake(engine(LIVE_SHAPED), async (bao) => {
+      const resolved = await run(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(resolveWith(permissionGroupsFromEngine()), (groups) =>
+          groups.resolve(MOUNT, [
+            bucket('Workers R2 Storage Bucket Item Write'),
+            bucket('Workers R2 Storage Bucket Item Read'),
+            bucket('Workers R2 Storage Read'),
+          ]),
+        ),
+      );
+      assert.deepEqual(Object.fromEntries(resolved), {
+        [groupKey('Workers R2 Storage Bucket Item Read', GROUP_SCOPES.bucket)]: 'r2-item-read',
+        [groupKey('Workers R2 Storage Bucket Item Write', GROUP_SCOPES.bucket)]: 'r2-item-write',
+        [groupKey('Workers R2 Storage Read', GROUP_SCOPES.bucket)]: 'r2-read',
+      });
+    });
+  });
+
+  /** ⛔ A TWO-ID NAME ASKED AT A SCOPE IT IS NOT LISTED AT IS UNKNOWN, never the other id. */
+  it('fails a two-id name at a scope neither of its ids carries', async () => {
+    await withFake(engine(LIVE_SHAPED), async (bao) => {
+      const error = await runFailure(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(permissionGroupsFromEngine(), (groups) =>
+          groups.resolve(MOUNT, [bucket('Logs Write')]),
+        ),
+      );
+      assert.match(
+        String(error),
+        /unknown group "Logs Write" at scope com\.cloudflare\.edge\.r2\.bucket/,
+      );
+    });
+  });
+
+  it('fails an unknown name rather than dropping it', async () => {
+    await withFake(engine(GROUPS), async (bao) => {
+      const error = await runFailure(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(permissionGroupsFromEngine(), (groups) =>
+          groups.resolve(MOUNT, [zone('DNS Reed')]),
+        ),
+      );
+      assert.ok(error instanceof CloudflareGroupsError);
+      assert.match(error.message, /unknown group "DNS Reed"/);
+    });
+  });
+
+  /**
+   * ⛔ THE FAILURE EVERY PLAN HITS UNTIL THE OPERATOR DEPLOYS THE GRANT. A bare `403: permission
+   *   denied` names the path and nothing to do about it; this asserts the message carries the
+   *   stanza and the file, because that is the whole difference between a five-minute fix and a
+   *   re-investigation of a deployed, working endpoint.
+   */
+  it('names the missing policy grant on 403, not a bare permission denied', async () => {
+    await withFake(
+      () => ({ json: { errors: ['permission denied'] }, status: 403 }),
+      async (bao) => {
+        const error = await runFailure(
+          { BAO_ADDR: bao.address },
+          Effect.flatMap(permissionGroupsFromEngine(), (groups) =>
+            groups.resolve(MOUNT, [zone('DNS Read')]),
+          ),
+        );
+        assert.ok(error instanceof CloudflareGroupsError);
+        assert.match(error.message, /answered 403/);
+        assert.match(
+          error.message,
+          /path "cloudflare-acme-dns\/permission-groups" \{ capabilities = \["read"\] \}/,
+        );
+        assert.match(error.message, /20-cloudflare-permission-groups\.hcl/);
+      },
+    );
+  });
+
+  it('fails when the endpoint is not deployed (404), never reading it as no groups', async () => {
+    await withFake(
+      () => ({ json: { errors: [] }, status: 404 }),
+      async (bao) => {
+        const error = await runFailure(
+          { BAO_ADDR: bao.address },
+          Effect.flatMap(permissionGroupsFromEngine(), (groups) =>
+            groups.resolve(MOUNT, [zone('DNS Read')]),
+          ),
+        );
+        assert.match(String(error), /not deployed/);
+      },
+    );
+  });
+
+  /**
+   * ⛔ TWO IDS SHARING ONE SCOPE IS STILL AMBIGUOUS, and fails the whole mount rather than the one
+   *   role — the scope is the only thing that can tell a name's ids apart, and here it does not.
+   */
+  it('fails a name listed with two ids at the same scope', async () => {
+    await withFake(
+      engine([...GROUPS, { id: 'id-other', name: 'DNS Read', scopes: [GROUP_SCOPES.zone] }]),
+      async (bao) => {
+        const error = await runFailure(
+          { BAO_ADDR: bao.address },
+          Effect.flatMap(permissionGroupsFromEngine(), (groups) =>
+            groups.resolve(MOUNT, [zone('DNS Write')]),
+          ),
+        );
+        assert.match(
+          String(error),
+          /ambiguous: "DNS Read" is listed with two ids at scope com\.cloudflare\.api\.account\.zone/,
+        );
+      },
+    );
+  });
+});
+
+const ZONE = 'com.cloudflare.api.account.zone.z1';
+
+const declared = (mount: string, name: string, groups: string[]): ExpandedRole => ({
+  account: 'acme',
+  accountId: 'acct',
+  catalog: { description: '', maxTtl: '1h', permissions: groups, ttl: '5m', zone: 'example.com' },
+  description: '',
+  maxTtl: '1h',
+  mount,
+  name,
+  policies: [{ effect: 'allow', groupOrder: 'declared', groups, resource: ZONE }],
+  surface: mount.split('-').at(-1) ?? '',
+  ttl: '5m',
+});
+
+/** Live roles, keyed by API path; everything else is a 404. */
+const liveRoles =
+  (roles: Record<string, string[]>) =>
+  (seen: Seen): Reply => {
+    const ids = roles[seen.path];
+    if (ids === undefined) return { json: { errors: [] }, status: 404 };
+    const policies = JSON.stringify([
+      { effect: 'allow', resources: { [ZONE]: '*' }, permission_groups: ids.map((id) => ({ id })) },
+    ]);
+    return {
+      json: { data: { description: '', max_ttl: 3600, name: 'x', policies, ttl: 300 } },
+      status: 200,
+    };
+  };
+
+/**
+ * One account, two mounts. `Email Routing` is isolated only by combining them — the shape that
+ * made source (b) per account rather than per mount.
+ */
+const DECLARED = new Map([
+  [MOUNT, [declared(MOUNT, 'dns-read', ['DNS Read'])]],
+  [
+    'cloudflare-acme-platform',
+    [declared('cloudflare-acme-platform', 'create', ['DNS Read', 'Email Routing'])],
+  ],
+]);
+
+describe('permissionGroupsFromLiveRoles', () => {
+  const LIVE = {
+    '/v1/cloudflare-acme-dns/roles/dns-read': ['id-read'],
+    '/v1/cloudflare-acme-platform/roles/create': ['id-email', 'id-read'],
+  };
+
+  it('resolves a name only a sibling mount of the same account can isolate', async () => {
+    await withFake(liveRoles(LIVE), async (bao) => {
+      const groups = await run(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(permissionGroupsFromLiveRoles(DECLARED), (source) =>
+          source.resolve('cloudflare-acme-platform', [zone('Email Routing'), zone('DNS Read')]),
+        ),
+      );
+      assert.deepEqual(Object.fromEntries(groups), {
+        [groupKey('DNS Read', GROUP_SCOPES.zone)]: 'id-read',
+        [groupKey('Email Routing', GROUP_SCOPES.zone)]: 'id-email',
+      });
+    });
+  });
+
+  it('fails a name no live role carries — a new group needs the engine endpoint', async () => {
+    await withFake(liveRoles(LIVE), async (bao) => {
+      const error = await runFailure(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(permissionGroupsFromLiveRoles(DECLARED), (source) =>
+          source.resolve(MOUNT, [zone('Zone WAF Write')]),
+        ),
+      );
+      assert.ok(error instanceof CloudflareGroupsError);
+      assert.match(error.message, /unknown group "Zone WAF Write".*engine endpoint/);
+    });
+  });
+
+  it('fails the whole account when a live role contradicts the rest', async () => {
+    const contradicted = { ...LIVE, '/v1/cloudflare-acme-dns/roles/dns-read': ['id-write'] };
+    await withFake(liveRoles(contradicted), async (bao) => {
+      const error = await runFailure(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(permissionGroupsFromLiveRoles(DECLARED), (source) =>
+          source.resolve(MOUNT, [zone('DNS Read')]),
+        ),
+      );
+      // dns-read now teaches `DNS Read` → id-write, and `create` carries id-read instead.
+      assert.match(
+        String(error),
+        /account acme: .*contradicted: cloudflare-acme-platform\/create\[0\] declares "DNS Read" but lacks its id id-write/,
+      );
+    });
+  });
+
+  it('fails a mount nothing is declared on', async () => {
+    await withFake(liveRoles(LIVE), async (bao) => {
+      const error = await runFailure(
+        { BAO_ADDR: bao.address },
+        Effect.flatMap(permissionGroupsFromLiveRoles(DECLARED), (source) =>
+          source.resolve('cloudflare-acme-security', [zone('DNS Read')]),
+        ),
+      );
+      assert.match(String(error), /no declared role on this mount/);
+    });
+  });
+});

package/src/openbao/cloudflare-permission-groups.ts

@@ -0,0 +1,299 @@
+/**
+ * Permission-group (name, SCOPE) → ID, behind ONE interface with two sources.
+ *
+ * ⛔ THE KEY IS THE PAIR, AND THAT IS NOT PEDANTRY. MEASURED 2026-09-15 the hour the grant went
+ *   live: of the account's 401 groups, SEVEN names are listed twice — `Access: Apps and Policies
+ *   Read`/`Revoke`/`Write`, `Disable ESC Read`/`Write`, `Logs Read`/`Write` — each pair one id
+ *   scoped `com.cloudflare.api.account` and one scoped `com.cloudflare.api.account.zone`. Keyed by
+ *   name alone the whole plan fails as ambiguous; keyed by name alone and forgiving, cfhf.py:148's
+ *   last-one-wins picks a group gated at the wrong scope and the token is refused at first use.
+ *   The asking ENTRY says which: its `scope` (roles.yaml `groups_scope:`), else its resource.
+ *
+ * ★ A SERVICE, NOT A TABLE. roles.yaml names groups (`DNS Read`); a role stores IDs. apply-roles.py
+ *   resolved them per account with a Cloudflare parent credential (cfhf.py:147-148), which agents
+ *   may not use. So Bao.CloudflareRole asks this service, and the stack chooses the source:
+ *
+ *   a) `permissionGroupsFromEngine` — `GET <mount>/permission-groups` on the Cloudflare engine,
+ *      answered under the mount's own parent. ★ DEPLOYED AND WIRED 2026-09-15: `bao path-help
+ *      cloudflare-<account>-platform` lists `^permission-groups$` on plugin v0.0.0-dev, and
+ *      cloudflare-roles.ts now provides this source to the stack.
+ *   b) `permissionGroupsFromLiveRoles` — ⚠️ TEMPORARY, AND STILL HERE ON PURPOSE. 2026-09-15: no
+ *      longer the stack's source, and NOT yet deletable. Two things gate that — (1) the live
+ *      `result_info` envelope pinned in ../../platform/secrets/vault/plugin/cloudflare/
+ *      client_result_info.go, whose own header names this deletion as what it gates, and (2)
+ *      cloudflare-parity.ts, which calls cloudflare-permission-groups-solve.ts directly for the
+ *      OFFLINE proof against a production export and has no engine to ask. So (b) and the solver
+ *      stay, one import from being the layer again (cloudflare-roles.ts), until the last step of
+ *      docs/ledger/openbao-permission-groups-engine-2026-09-15.md is done.
+ *
+ * ⛔ AN UNKNOWN NAME FAILS THE OPERATION. Dropping it would write a policy one group short, and the
+ *   engine refuses an empty ID (path_roles.go:181-185) but not a SHORTER list: the minted token is
+ *   quietly narrower than declared, and the consumer finds out at 403.
+ */
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoRead } from './bao-http.ts';
+import type { BaoError } from './bao-status.ts';
+import { groupKey } from './cloudflare-group-scope.ts';
+import {
+  describeProblems,
+  observationsOf,
+  solveGroups,
+} from './cloudflare-permission-groups-solve.ts';
+import { type WirePolicy, atEveryScope } from './cloudflare-policy.ts';
+import { readCloudflareRole } from './cloudflare-role-wire.ts';
+import type { ExpandedRole } from './cloudflare-roles-expand.ts';
+import { mountPath } from './mount-form.ts';
+
+export class CloudflareGroupsError extends Error {
+  constructor(
+    readonly scope: string,
+    readonly problems: readonly string[],
+  ) {
+    super(`Cloudflare permission groups for ${scope}: ${problems.join('; ')}`);
+    this.name = 'CloudflareGroupsError';
+  }
+}
+
+/** ⛔ Keyed by `groupKey(name, scope)` throughout — see cloudflare-group-scope.ts. */
+type Groups = ReadonlyMap<string, string>;
+type Lookup = Effect.Effect<Groups, BaoError | CloudflareGroupsError, HttpClient.HttpClient>;
+
+/** One group a role asks for: its name, and the scope the entry naming it is gated at. */
+export interface GroupRef {
+  readonly name: string;
+  readonly scope: string;
+}
+
+export class CloudflarePermissionGroups extends Context.Service<
+  CloudflarePermissionGroups,
+  {
+    /** The ID of every ref, keyed by `groupKey` — or a failure naming what did not resolve. */
+    readonly resolve: (
+      mount: string,
+      refs: readonly GroupRef[],
+    ) => Effect.Effect<Groups, BaoError | CloudflareGroupsError, HttpClient.HttpClient>;
+  }
+>()('homeflare/openbao/CloudflarePermissionGroups') {}
+
+const pick = (mount: string, groups: Groups, refs: readonly GroupRef[], hint: string) => {
+  const unknown = refs.filter((ref) => !groups.has(groupKey(ref.name, ref.scope)));
+  if (unknown.length > 0) {
+    const problems = unknown.map(
+      (ref) => `unknown group ${JSON.stringify(ref.name)} at scope ${ref.scope} — ${hint}`,
+    );
+    return Effect.fail(new CloudflareGroupsError(mount, problems));
+  }
+  return Effect.succeed(
+    new Map(
+      refs.flatMap((ref) => {
+        const key = groupKey(ref.name, ref.scope);
+        const id = groups.get(key);
+        return id === undefined ? [] : [[key, id] as const];
+      }),
+    ),
+  );
+};
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * ⛔ A 403 IS A MISSING GRANT, AND IT SAYS SO. `BaoError` alone reports `GET /v1/<mount>/
+ *   permission-groups -> 403: permission denied` — true, and it points nowhere: the path is
+ *   deployed, the token is valid, and the one thing to change is a policy file. MEASURED 2026-09-15
+ *   10:19 on the macmini-admin lane, where `bao write sys/capabilities-self` answered `[deny]` on
+ *   this exact path. bao-status.ts argues that a failure must name what it is; this is that
+ *   argument one level up.
+ */
+const deniedHint = (mount: string) =>
+  `GET ${mountPath(mount)}/permission-groups answered 403 — this token's policy carries no ` +
+  `\`path "${mountPath(mount)}/permission-groups" { capabilities = ["read"] }\` grant. ` +
+  'It is declared in ../platform/secrets/vault/policies/homeflare-admin/' +
+  '20-cloudflare-permission-groups.hcl and applies with `alchemy deploy` of this stack';
+
+const deniedNamed = <A, R>(mount: string, read: Effect.Effect<A, BaoError, R>) =>
+  Effect.catchIf(
+    read,
+    (error) => error.status === 403,
+    () => Effect.fail(new CloudflareGroupsError(mount, [deniedHint(mount)])),
+  );
+
+/**
+ * a) The engine's list, parsed.
+ *
+ * ★ THE SHAPE IS THE PLUGIN'S OWN, READ FROM ITS SOURCE 2026-09-15:
+ *   `{"permission_groups":[{"id","name","scopes"}]}` built row by row in
+ *   ../../platform/secrets/vault/plugin/cloudflare/path_permission_groups.go:42-54. baoRead takes
+ *   `data` when the body has one and the whole body otherwise (bao-http.ts:160-167), so either
+ *   envelope parses.
+ * ⚠️ PAGINATION IS THE PLUGIN'S PROBLEM, NOT THIS PARSER'S. client_permission_groups.go:52-119 walks
+ *   Cloudflare's pages and ends every guard in an error rather than a shorter list, so what arrives
+ *   here is complete or absent. ⛔ ITS `result_info` GUARDS ARE STILL UNMEASURED against a live
+ *   envelope (client_result_info.go:22-28) — that capture, not this file, is what gates deleting (b).
+ * ⛔ ONE NAME WITH TWO IDS IS NOT AN ERROR; ONE (NAME, SCOPE) WITH TWO IDS IS. cfhf.py:148 built
+ *   `{g["name"]: g["id"]}` and the LAST duplicate won in silence. MEASURED 2026-09-15 on the live
+ *   list: seven names ARE listed twice, each pair one account-scoped id and one zone-scoped id, so
+ *   the plugin's "does not choose between them" (path_permission_groups.go:69-70) is the shape in
+ *   front of us, not a hypothetical. `scopes` tells them apart; the header above says who picks.
+ * ⚠️ AN EMPTY `scopes` IS NOT AN ERROR. Such a group is reachable only by the one-id rule below —
+ *   a name nothing else claims answers wherever it is asked — so a group Cloudflare ships without
+ *   a scope resolves, and never holds the other 398 hostage.
+ */
+const engineGroups = (mount: string): Lookup =>
+  Effect.flatMap(deniedNamed(mount, baoRead(`${mountPath(mount)}/permission-groups`)), (data) => {
+    const list = data?.['permission_groups'];
+    if (data === undefined) {
+      // ⚠️ 404 IS NOW A MOUNT-SHAPED ANSWER, NOT THE EXPECTED ONE. The path IS deployed
+      //   estate-wide (measured 2026-09-15), so a 404 here means this mount is served by an older
+      //   plugin binary or BAO_ADDR is not the mini — never "no groups".
+      const why = 'GET <mount>/permission-groups answered 404 — the endpoint is not deployed here';
+      return Effect.fail(new CloudflareGroupsError(mount, [why]));
+    }
+    if (!Array.isArray(list)) {
+      return Effect.fail(new CloudflareGroupsError(mount, ['no permission_groups array in reply']));
+    }
+    const scoped = new Map<string, string>();
+    const idsOf = new Map<string, Set<string>>();
+    const problems: string[] = [];
+    for (const item of list) {
+      const name = isRecord(item) ? item['name'] : undefined;
+      const id = isRecord(item) ? item['id'] : undefined;
+      const scopes = isRecord(item) ? item['scopes'] : undefined;
+      if (
+        typeof name !== 'string' ||
+        typeof id !== 'string' ||
+        !Array.isArray(scopes) ||
+        !scopes.every((scope) => typeof scope === 'string')
+      ) {
+        problems.push('an entry without a string name, id and scopes');
+        continue;
+      }
+      idsOf.set(name, (idsOf.get(name) ?? new Set()).add(id));
+      for (const scope of scopes) {
+        const key = groupKey(name, scope);
+        if (scoped.has(key) && scoped.get(key) !== id) {
+          problems.push(
+            `ambiguous: ${JSON.stringify(name)} is listed with two ids at scope ${scope}`,
+          );
+        } else {
+          scoped.set(key, id);
+        }
+      }
+    }
+    /**
+     * ★ A NAME WITH ONE ID NEEDS NO SCOPE, and answers at every scope an entry can ask for: there
+     *   is nothing to choose between, and 385 of the list's 392 names are in that case. It is only
+     *   the seven two-id names the asking scope has to separate — and for those, a scope the name
+     *   is not listed at resolves to nothing and fails by name, never to the other scope's id.
+     */
+    const sole = new Map(
+      [...idsOf].flatMap(([name, ids]) => {
+        const only = [...ids];
+        return ids.size === 1 && only[0] !== undefined ? [[name, only[0]] as const] : [];
+      }),
+    );
+    return problems.length > 0
+      ? Effect.fail(new CloudflareGroupsError(mount, problems))
+      : Effect.succeed(new Map([...atEveryScope(sole), ...scoped]));
+  });
+
+/**
+ * ★ ONE FETCH PER MOUNT PER RUN, not one per role — 586 roles would otherwise ask 586 times.
+ * ⚠️ A FAILURE IS CACHED TOO (Effect.cached keeps the Exit), so one sealed-vault 503 fails every
+ *   role on that mount for the rest of the run. That is the honest outcome for a plan: retrying
+ *   586 times against a sealed server would only make the failure slower.
+ */
+export const permissionGroupsFromEngine = () =>
+  Effect.sync(() => {
+    const cache = new Map<string, Lookup>();
+    const cachedFor = (mount: string) =>
+      Effect.suspend(() => {
+        const hit = cache.get(mountPath(mount));
+        if (hit !== undefined) return hit;
+        return Effect.flatMap(Effect.cached(engineGroups(mount)), (lookup) => {
+          cache.set(mountPath(mount), lookup);
+          return lookup;
+        });
+      });
+    return CloudflarePermissionGroups.of({
+      resolve: (mount, refs) =>
+        Effect.flatMap(cachedFor(mount), (groups) =>
+          pick(mount, groups, refs, 'the engine does not list it for this account at that scope'),
+        ),
+    });
+  });
+
+/**
+ * b) ⚠️ TEMPORARY, AND NO LONGER THE STACK'S SOURCE SINCE 2026-09-15 — see the header for the two
+ *   things that gate deleting it. Reads every DECLARED role of an account — no LIST, because an
+ *   undeclared live role carries IDs with no names to pair them with — and solves the account at
+ *   once.
+ * 🔴 WHAT RETIRED IT, 2026-09-15 10:13: `alchemy deploy` could not create
+ *   `cloudflare-{<account>,testing}-platform/roles/r2-backup-mini` — `unknown group "Workers R2
+ *   Storage Bucket Item Write" — no live role on account <account> carries it; a NEW group needs
+ *   the engine endpoint`. That is this source's documented blind spot arriving, not a bug in it.
+ *
+ * ★ PER ACCOUNT, NOT PER MOUNT, BECAUSE ONE MOUNT CANNOT SOLVE ITSELF. MEASURED on the snapshot:
+ *   `aimto-app-alchemy-os-create` on the platform mount pairs `Email Routing Rules Write` and
+ *   `DNS Write` with two unknown IDs, and neither group appears alone on that mount. The dns and
+ *   security mounts of the same account isolate them. apply-roles.py's map was per account too
+ *   (apply-roles.py:117).
+ */
+export const permissionGroupsFromLiveRoles = (
+  declared: ReadonlyMap<string, readonly ExpandedRole[]>,
+) =>
+  Effect.gen(function* () {
+    const accountOf = new Map<string, string>();
+    const byAccount = new Map<string, ExpandedRole[]>();
+    for (const [mount, roles] of declared) {
+      for (const role of roles) {
+        accountOf.set(mount, role.account);
+        byAccount.set(role.account, [...(byAccount.get(role.account) ?? []), role]);
+      }
+    }
+    const solved = new Map<string, Lookup>();
+    for (const [account, roles] of byAccount) {
+      const solve = Effect.gen(function* () {
+        const live = new Map<string, readonly WirePolicy[]>();
+        // ★ `Effect.all` over mapped reads, not `Effect.forEach`: oxlint's unicorn/no-array-for-each
+        //   matches the method NAME and cannot tell Effect's from Array's.
+        yield* Effect.all(
+          roles.map((role) =>
+            Effect.map(readCloudflareRole(role.mount, role.name), (read) => {
+              if (read?.policies !== undefined) {
+                live.set(`${role.mount}/${role.name}`, read.policies);
+              }
+            }),
+          ),
+          { concurrency: 8, discard: true },
+        );
+        const result = solveGroups(observationsOf(roles, live));
+        const problems = describeProblems(result);
+        if (problems.length > 0) {
+          return yield* Effect.fail(new CloudflareGroupsError(`account ${account}`, problems));
+        }
+        /**
+         * ⚠️ IT ANSWERS AT EVERY SCOPE BECAUSE IT CANNOT SEE ONE. A live role carries ids and no
+         *   scopes, so the solver learns `name → id` and nothing more; the seven two-id names
+         *   resolve here to whichever id the estate happens to carry, at whatever scope is asked.
+         *   That is this source's blind spot, not a second opinion — (a) keys by (name, scope).
+         */
+        return atEveryScope(result.groups);
+      });
+      solved.set(account, yield* Effect.cached(solve));
+    }
+    return CloudflarePermissionGroups.of({
+      resolve: (mount, refs) => {
+        const account = accountOf.get(mountPath(mount));
+        const lookup = account === undefined ? undefined : solved.get(account);
+        if (account === undefined || lookup === undefined) {
+          const why = 'no declared role on this mount, so no live role can vouch for its groups';
+          return Effect.fail(new CloudflareGroupsError(mount, [why]));
+        }
+        const hint = `no live role on account ${account} carries it; a NEW group needs the engine endpoint`;
+        return Effect.flatMap(lookup, (groups) => pick(mount, groups, refs, hint));
+      },
+    });
+  });