@homeflare/alchemy 0.1.0

package/src/openbao/bao-status.ts

@@ -0,0 +1,137 @@
+/**
+ * How a finished OpenBao HTTP exchange reads: a body, a genuinely absent object, or an error.
+ *
+ * ★ STATUS CODES, NEVER WORDS. The `bao` CLI this replaced reported every outcome as stderr text,
+ *   and deciding by that text broke twice: every failure once read as absent (a bad token planned 33
+ *   updates), and then `bao policy read` turned out to say "absent" in different words from
+ *   `bao read`, so a new policy could not be created (b3c18a33e). The API itself answers 404 for
+ *   absent, 403 for denied and 503 for sealed — openbao v2.6.2 sdk/logical/response_util.go:
+ *   RespondErrorCommon (a read that finds nothing is 404; ErrPermissionDenied is 403) and
+ *   AdjustErrorStatusCode (ErrSealed is 503).
+ */
+
+export type BaoIntent = 'read' | 'write' | 'delete';
+
+/**
+ * A failed call, naming the method, the path and OpenBao's own `errors` array.
+ *
+ * ⛔ IT NEVER CARRIES THE TOKEN, AND IT NEVER CARRIES A RESPONSE BODY IT DID NOT PARSE. It is built
+ *   from the method, the API path and OpenBao's error strings only — no request, no headers, no
+ *   `cause` — because an Effect `HttpClientRequest` inspects its headers through a redaction list
+ *   that does not name `x-vault-token`. A 2xx body can hold a credential, and a foreign error page
+ *   can echo the request back, so a body that is not OpenBao's is described, never quoted.
+ */
+export class BaoError extends Error {
+  constructor(
+    readonly status: number,
+    readonly method: string,
+    readonly path: string,
+    readonly errors: readonly string[],
+  ) {
+    const code = status === 0 ? 'no response' : String(status);
+    super(`OpenBao ${method} /v1/${path} -> ${code}: ${errors.join('; ') || '(no errors given)'}`);
+    this.name = 'BaoError';
+  }
+}
+
+export type Settled =
+  | { readonly body: Record<string, unknown> | undefined }
+  | { readonly error: BaoError };
+
+const objectOf = (text: string): Record<string, unknown> | undefined => {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * OpenBao's `errors` array, or undefined for a body that is not OpenBao's.
+ *
+ * ★ EVERY ERROR OPENBAO WRITES IS `{"errors": [...]}` WITH A JSON CONTENT TYPE, 404 included —
+ *   sdk/logical/response_util.go RespondError:180-196 — and every entry is a STRING.
+ * ⛔ AN ARRAY WITH ANY NON-STRING ENTRY IS NOT OPENBAO. The first version filtered the non-strings
+ *   out, which turned a JSON gateway's `{"errors":[{"code":1000,"message":"Not Found"}]}` into an
+ *   empty OpenBao error list — and a 404 carrying it into "absent" on a read and "done" on a delete,
+ *   the plan-CREATE-over-something-that-exists failure arriving through a wrong BAO_ADDR. Found by
+ *   grok's review on 2026-09-14. An EMPTY array is still OpenBao's: a plain 404 carries exactly that.
+ */
+const errorsOf = (text: string): readonly string[] | undefined => {
+  const raw = objectOf(text)?.['errors'];
+  return Array.isArray(raw) && raw.every((entry) => typeof entry === 'string')
+    ? (raw as string[])
+    : undefined;
+};
+
+/**
+ * Classify one exchange.
+ *
+ * ★ PURE AND EXPORTED SO THE ONE DECISION EVERY READ AND DELETE HERE RESTS ON CAN BE TESTED WITHOUT
+ *   A VAULT. It has been wrong in both directions already — every failure once read as absent, and
+ *   one command's absence wording was assumed for another's — see bao-status.test.ts.
+ *
+ * ⛔ 404 IS ABSENCE ONLY ON A READ, AND ONLY WHEN OPENBAO SAID IT. MEASURED 2026-09-13 with the CLI,
+ *   and the discriminator is real but NARROW: a genuinely absent object, read by a token that IS
+ *   allowed to read that path, is a 404. ⛔ AND THE SAME READ UNDER A NARROWER TOKEN IS A DENIAL:
+ *   under the agent lane the identical read answered `Code: 403 … permission denied`, because the
+ *   policy grants named paths and an unnamed one is refused rather than reported missing. So
+ *   "absent" is only knowable to a caller that could have read it — which is exactly why 403 is an
+ *   ERROR rather than a shrug. A resource that cannot tell absence from denial plans CREATE for
+ *   something that exists, which is the failure this estate has now found four separate times.
+ *   ⚠️ A 404 WHOSE BODY IS NOT `{"errors": […strings]}` IS NOT OPENBAO. A BAO_ADDR pointing at the
+ *     wrong server — a reverse proxy's HTML 404, a gateway's JSON one — must not read as "nothing".
+ *
+ * 🔴 THE SHELL HELPER USED TO RETURN `''` FOR EVERY NON-ZERO EXIT, AND THAT IS A LIE WITH
+ *   CONSEQUENCES. An expired BAO_TOKEN, a sealed server or a missing grant all came back as "the
+ *   mount is not there", so `diff` answered `update`, `reconcile` ran `secrets enable`, and the plan
+ *   reported a CREATE on infrastructure that exists. The failure the operator sees is about the
+ *   wrong thing entirely, at the worst possible moment — a sealed vault. ⚠️ SO 403, 5xx AND ANYTHING
+ *   ELSE THAT IS NOT 2xx FAILS. The cost is that a genuinely-absent read under a too-narrow token
+ *   becomes an error instead of a create, and that is the right way round: "I could not tell" is a
+ *   true statement, and "it is not there" was not.
+ *
+ * 🔴 THE DELETES ALL USED THE READ HELPER, WHICH DISCARDED THE EXIT CODE. A refused
+ *   `secrets disable` was reported as a successful delete: the resource left Alchemy's state while
+ *   the mount stayed live, so the next plan showed nothing and the object was orphaned in silence.
+ *   ⚠️ ABSENCE IS STILL NOT AN ERROR FOR A DELETE, because a delete must be idempotent: Alchemy
+ *   retries, and the second attempt legitimately finds nothing. So a delete's 404 is success and
+ *   its 403 is not.
+ * ★ DISABLING A MOUNT THAT IS ALREADY GONE IS NOT EVEN A 404. A review on 2026-09-14 said it failed
+ *   with `no matching mount` and would wedge a retried delete. The server says otherwise: it answers
+ *   success for a missing mount so as not to reveal whether one existed — openbao v2.6.2
+ *   vault/logical_system.go:1211-1216 — and the CLI printed "Disabled the secrets engine (if it
+ *   existed)" (command/secrets_disable.go:87).
+ */
+export const settle = (
+  intent: BaoIntent,
+  method: string,
+  path: string,
+  status: number,
+  text: string,
+): Settled => {
+  const fail = (errors: readonly string[]) => ({
+    error: new BaoError(status, method, path, errors),
+  });
+  if (status < 200 || status >= 300) {
+    const errors = errorsOf(text);
+    if (errors === undefined) {
+      // ⛔ DESCRIBED, NEVER QUOTED. A proxy or gateway error page can echo the request back, headers
+      //   and all, so quoting it could carry X-Vault-Token into an error that Alchemy logs (grok,
+      //   2026-09-14). mint in house/proxmox/src/credentials.ts already did it this way.
+      return fail([`not an OpenBao error body (${String(text.length)} bytes)`]);
+    }
+    if (status === 404 && intent !== 'write') return { body: undefined };
+    return fail(errors);
+  }
+  // ★ A write or delete answering 204 has nothing to say. A READ with no body has told us nothing,
+  //   and OpenBao never does that — a read that finds nothing is a 404 (RespondErrorCommon).
+  if (text.trim() === '') {
+    return intent === 'read' ? fail(['a successful read with an empty body']) : { body: undefined };
+  }
+  const body = objectOf(text);
+  return body === undefined ? fail(['a success body that is not a JSON object']) : { body };
+};

package/src/openbao/cloudflare-group-scope.test.ts

@@ -0,0 +1,103 @@
+/**
+ * `groups_scope:` — the one thing roles.yaml can say that its RESOURCE cannot.
+ *
+ * ⛔ THE POINT OF EVERY CASE BELOW IS THAT THE KEY IS LOAD-BEARING. One declaration is expanded
+ *   twice, with the key and without it, against ONE map that holds BOTH ids of `Logs Read`. If the
+ *   two runs ever resolve to the same id the key is decoration, and a test that only asserted the
+ *   override would still pass — so the negative case is asserted beside it, every time.
+ *
+ * ★ THE IDS ARE THE LIVE ONES, MEASURED 2026-09-15 on `cloudflare-<account>-platform/
+ *   permission-groups`: `Logs Read` is listed twice, `6a315a56…` at `com.cloudflare.api.account`
+ *   and `c4a30cd5…` at `com.cloudflare.api.account.zone`. The second is what the four live
+ *   security roles carry on their ACCOUNT resource, and what
+ *   house/nix/homeflare-config/scripts/cf-mint-analytics-tokens.py:80 pins as PG_LOGS_ZONE.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  GROUP_SCOPES,
+  accountResource,
+  groupKey,
+  groupScopeNamed,
+  scopeOfResource,
+} from './cloudflare-group-scope.ts';
+import { resolvePolicies } from './cloudflare-policy.ts';
+import { RolesConfigError, parseRolesConfig } from './cloudflare-roles-config.ts';
+import { type CloudflareZone, expandAll } from './cloudflare-roles-expand.ts';
+
+const LOGS_READ_ACCOUNT = '6a315a56f18441e59ed03352369ae956';
+const LOGS_READ_ZONE = 'c4a30cd58c5d42619c86a3c36c441e2d';
+
+/** Both ids of the one name, filed the way the engine source files them. */
+const IDS = new Map([
+  [groupKey('Logs Read', GROUP_SCOPES.account), LOGS_READ_ACCOUNT],
+  [groupKey('Logs Read', GROUP_SCOPES.zone), LOGS_READ_ZONE],
+]);
+
+const ZONES: Record<string, readonly CloudflareZone[]> = {
+  acme: [{ id: 'zone-com', internal: false, name: 'example.com' }],
+};
+
+const yaml = (scope: string) => `
+defaults: { namespace: homeflare }
+surfaces:
+  security:
+    account_roles:
+      - { name: logs-read, groups: [Logs Read],${scope} ttl: 15m, max_ttl: 1h, desc: 'L.' }
+accounts:
+  acme: { id: acct-acme, zones: all, surfaces: [security] }
+`;
+
+/** The single declaration, expanded with whatever `groups_scope:` text is given. */
+const resolved = (scope: string) => {
+  const roles = expandAll(parseRolesConfig(yaml(scope)), ZONES).get('cloudflare-acme-security');
+  const role = roles?.find((r) => r.name === 'logs-read');
+  assert.ok(role, 'logs-read was not expanded');
+  const { missing, policies } = resolvePolicies(role.policies, IDS);
+  assert.deepEqual(missing, []);
+  return policies;
+};
+
+describe('groups_scope', () => {
+  it('resolves the ZONE id on an ACCOUNT resource when the key says so', () => {
+    const [entry] = resolved(' groups_scope: zone,');
+    assert.ok(entry);
+    // ⛔ THE RESOURCE IS STILL THE ACCOUNT. The key moves the lookup, never the binding — that is
+    //   Cloudflare's "all zones from an account" (cf-mint-analytics-tokens.py:155-158).
+    assert.deepEqual(Object.keys(entry.resources), [accountResource('acct-acme')]);
+    assert.deepEqual(entry.groupIds, [LOGS_READ_ZONE]);
+  });
+
+  it('resolves the ACCOUNT id from the same declaration without the key', () => {
+    const [entry] = resolved('');
+    assert.ok(entry);
+    assert.deepEqual(Object.keys(entry.resources), [accountResource('acct-acme')]);
+    assert.deepEqual(entry.groupIds, [LOGS_READ_ACCOUNT]);
+    assert.notEqual(LOGS_READ_ACCOUNT, LOGS_READ_ZONE);
+  });
+
+  /**
+   * ⚠️ THE FIELD IS ABSENT, NOT `undefined`-VALUED, WHEN THE yaml IS SILENT. The declaration is
+   *   Alchemy props: a key that appeared on all 594 roles would rewrite every stored prop set to
+   *   restate what the resource already says.
+   */
+  it('leaves `scope` off every entry that does not declare it', () => {
+    const roles = expandAll(parseRolesConfig(yaml('')), ZONES).get('cloudflare-acme-security');
+    const entry = roles?.[0]?.policies[0];
+    assert.ok(entry);
+    assert.equal('scope' in entry, false);
+    assert.equal(scopeOfResource(accountResource('acct-acme')), GROUP_SCOPES.account);
+  });
+
+  it('refuses a word that is not one of the three scopes', () => {
+    assert.throws(() => parseRolesConfig(yaml(' groups_scope: zonee,')), RolesConfigError);
+    // ⛔ AND REFUSES THE NAMESPACE ITSELF. roles.yaml writes the short word; a namespace typed
+    //   there would be a string any looser check would wave through.
+    assert.throws(
+      () => parseRolesConfig(yaml(" groups_scope: 'com.cloudflare.api.account.zone',")),
+      RolesConfigError,
+    );
+    assert.equal(groupScopeNamed('bucket'), GROUP_SCOPES.bucket);
+    assert.equal(groupScopeNamed('zonee'), undefined);
+  });
+});

package/src/openbao/cloudflare-group-scope.ts

@@ -0,0 +1,83 @@
+/**
+ * The three resources a Cloudflare policy entry can name, and the SCOPE its permission groups are
+ * looked up at — one vocabulary, both directions.
+ *
+ * ★ EXTRACTED FROM cloudflare-roles-expand.ts 2026-09-15, which had reached 270 lines (AGENTS.md
+ *   rule 5, code ≤250). The split is by CONCERN, not by size: expand.ts turns roles.yaml into
+ *   roles, this answers "which of the two ids named `Logs Read` does this entry mean".
+ */
+
+/** cfhf.py:172-173. */
+export const zoneResource = (zoneId: string) => `com.cloudflare.api.account.zone.${zoneId}`;
+export const accountResource = (accountId: string) => `com.cloudflare.api.account.${accountId}`;
+
+/**
+ * One R2 bucket, which is a DIFFERENT RESOURCE NAMESPACE from the two above.
+ *
+ * ⛔ `com.cloudflare.edge.r2.bucket.…`, NOT `com.cloudflare.api.account.…`, and the three parts are
+ *   joined by UNDERSCORES inside the last segment — `<accountId>_<jurisdiction>_<bucket>`. Getting
+ *   the separator wrong produces a syntactically fine resource that matches no bucket, and the
+ *   token mints successfully and is refused on first use, which reads exactly like a missing
+ *   permission group. Per Cloudflare's R2 API-token documentation, read 2026-09-15.
+ * ⚠️ AND IT ONLY BINDS THE `Bucket Item` GROUPS. `Workers R2 Storage Write` / `… Read` are gated at
+ *   the ACCOUNT scope; the bucket-scoped pair is `Workers R2 Storage Bucket Item Write` / `… Read`.
+ *   Pairing an account group with this resource is the same silent 403.
+ */
+export const bucketResource = (accountId: string, jurisdiction: string, bucket: string) =>
+  `com.cloudflare.edge.r2.bucket.${accountId}_${jurisdiction}_${bucket}`;
+
+/**
+ * The three scopes this expansion can ask for — the namespaces of the three resources above, which
+ * is exactly what the engine reports as a group's `scopes`.
+ *
+ * ★ MEASURED on `cloudflare-<account>-platform/permission-groups`, 2026-09-15 12:10: 401 groups,
+ *   every one with exactly ONE scope, over five values — 297 `com.cloudflare.api.account`, 94
+ *   `com.cloudflare.api.account.zone`, 2 `com.cloudflare.edge.r2.bucket` and four each of
+ *   `…account.flagship.app` and `com.cloudflare.edge.worker.script`, which no resource here builds.
+ *   The testing account's list is byte-identical, so the ids are Cloudflare's, not an account's.
+ */
+export const GROUP_SCOPES = {
+  account: 'com.cloudflare.api.account',
+  bucket: 'com.cloudflare.edge.r2.bucket',
+  zone: 'com.cloudflare.api.account.zone',
+} as const;
+
+/**
+ * The short word roles.yaml writes in `groups_scope:` → the namespace: `zone` becomes
+ * `com.cloudflare.api.account.zone`. Undefined for a word that is not one of the three KEYS above.
+ *
+ * ⛔ THE yaml SAYS THE SHORT WORD AND NEVER THE NAMESPACE. A namespace typed into roles.yaml would
+ *   be accepted by any check that only asked for a string, and a misspelt one resolves no group at
+ *   all — an unknown-group failure naming a scope nobody wrote on purpose, instead of the line.
+ * ⚠️ `Object.entries(…).find`, NOT an index with a narrowing `as`: codex standard 2 bans the cast,
+ *   and the lookup has three entries.
+ */
+export const groupScopeNamed = (word: string): string | undefined =>
+  Object.entries(GROUP_SCOPES).find(([name]) => name === word)?.[1];
+
+/**
+ * The scope the groups of one policy entry are gated at: its resource namespace, the instance id
+ * dropped. A zone entry asks for zone groups, an account entry for account groups, a bucket entry
+ * for the two `com.cloudflare.edge.r2.bucket` ones.
+ *
+ * ⛔ ZONE IS TESTED BEFORE ACCOUNT, because `com.cloudflare.api.account.zone.<id>` also starts with
+ *   the account namespace, and the wrong order would call every zone entry an account one.
+ * ⚠️ A RESOURCE IN NO KNOWN NAMESPACE BECOMES ITS OWN SCOPE, which matches no group, so it fails as
+ *   an unresolvable name naming the scope it asked for — never by borrowing another scope's id.
+ * ⚠️ IT IS THE DEFAULT, NOT THE LAST WORD. An entry carrying an explicit `scope` overrides it —
+ *   see DeclaredPolicy.scope (cloudflare-roles-expand.ts) and resolvePolicies.
+ */
+export const scopeOfResource = (resource: string) => {
+  const scopes = [GROUP_SCOPES.zone, GROUP_SCOPES.bucket, GROUP_SCOPES.account];
+  return scopes.find((scope) => resource.startsWith(`${scope}.`)) ?? resource;
+};
+
+/**
+ * What a resolved group is filed under.
+ *
+ * ⛔ A NAME ALONE IS NOT A KEY. MEASURED 2026-09-15 on the live list: SEVEN names are listed twice,
+ *   once at `com.cloudflare.api.account` and once at `com.cloudflare.api.account.zone` — `Access:
+ *   Apps and Policies Read` / `… Revoke` / `… Write`, `Disable ESC Read` / `… Write`, `Logs Read`
+ *   and `Logs Write`. cfhf.py:148 keyed by name and the last one read won in silence.
+ */
+export const groupKey = (name: string, scope: string) => `${scope} ${name}`;

package/src/openbao/cloudflare-parity-catalog.ts

@@ -0,0 +1,104 @@
+/**
+ * The two things apply-roles.py wrote BESIDE the roles, checked against the expansion: each mount's
+ * KV catalog document (apply-roles.py:48-82) and each mount's description (apply-roles.py:85-95).
+ *
+ * ★ WHY THE CATALOG IS CHECKED AT ALL: IT IS THE BOOTSTRAP'S INDEPENDENT WITNESS. Its `permissions`
+ *   are the NAMES apply-roles.py resolved against Cloudflare's own permission-group list at its last
+ *   --apply — resolve_groups fails the role on any name Cloudflare does not know
+ *   (apply-roles.py:29-45, :144-149). So a catalog that agrees with roles.yaml means the names the
+ *   bootstrap pairs with live IDs were real Cloudflare names then, which closes the blind spot
+ *   cloudflare-permission-groups-solve.ts names.
+ *
+ * ⚠️ `generated` IS NOT COMPARED. It is the wall-clock time of the last --apply
+ *   (apply-roles.py:55), so it differs on every run by construction — a note for whoever declares
+ *   the catalog next: as written it can never plan noop.
+ */
+import type { SnapshotMount } from './cloudflare-parity-snapshot.ts';
+import type { CatalogView, ExpandedRole } from './cloudflare-roles-expand.ts';
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+
+/** The catalog entry apply-roles.py:58-62 would write for a role, in the document's own keys. */
+const catalogEntry = (view: CatalogView) => ({
+  description: view.description,
+  max_ttl: view.maxTtl,
+  permissions: view.permissions,
+  ttl: view.ttl,
+  zone: view.zone,
+});
+
+/** The whole document's non-role fields (apply-roles.py:65-67, :72-76). */
+const expectedFields = (mount: string, declared: readonly ExpandedRole[], count: number) => {
+  const [first] = declared;
+  return {
+    account: first?.account,
+    account_id: first?.accountId,
+    mint_path: `${mount}/creds/<role>`,
+    mount,
+    role_count: String(count),
+    surface: mount.split('-').at(-1),
+  };
+};
+
+export const catalogProblems = (
+  mount: string,
+  declared: readonly ExpandedRole[],
+  snapshot: SnapshotMount | undefined,
+): string[] => {
+  const catalog = snapshot?.catalog;
+  if (catalog === undefined) return ['no catalog document in the snapshot'];
+  const problems: string[] = [];
+  const live = snapshot?.roles ?? new Map();
+  for (const name of [...live.keys()].sort()) {
+    if (!catalog.roles.has(name)) problems.push(`live but not in the catalog: ${name}`);
+  }
+  for (const name of [...catalog.roles.keys()].sort()) {
+    if (!live.has(name)) problems.push(`in the catalog but not live: ${name}`);
+  }
+  for (const role of declared) {
+    const entry = catalog.roles.get(role.name);
+    if (entry === undefined) {
+      problems.push(`in roles.yaml but not in the catalog: ${role.name}`);
+      continue;
+    }
+    for (const [field, want] of Object.entries(catalogEntry(role.catalog))) {
+      if (!same(entry[field], want)) {
+        const have = JSON.stringify(entry[field]);
+        problems.push(
+          `${role.name}: catalog ${field}: want ${JSON.stringify(want)} / have ${have}`,
+        );
+      }
+    }
+  }
+  const fields = expectedFields(mount, declared, catalog.roles.size);
+  for (const [field, want] of Object.entries(fields)) {
+    if (!same(catalog.fields[field], want)) {
+      const have = JSON.stringify(catalog.fields[field]);
+      problems.push(`catalog field ${field}: want ${JSON.stringify(want)} / have ${have}`);
+    }
+  }
+  return problems;
+};
+
+/**
+ * apply-roles.py:91-95 — `Cloudflare <surface> credentials, <n> roles. Catalog: …`, n being the
+ * EXPANDED count, not the live one.
+ *
+ * ⚠️ `observedCount` IS ADDED BACK IN. The Python expanded over every zone, anyauth included, so its
+ *   count carries the roles Alchemy now only observes (OBSERVED_ROLE_PREFIXES in cloudflare-zones.ts).
+ *   Leaving them out would report a description drift that is really a scope decision.
+ */
+export const descriptionProblem = (
+  mount: string,
+  declared: readonly ExpandedRole[],
+  snapshot: SnapshotMount | undefined,
+  observedCount = 0,
+): string | undefined => {
+  const surface = mount.split('-').at(-1) ?? '';
+  const count = declared.length + observedCount;
+  const want = `Cloudflare ${surface} credentials, ${String(count)} roles. Catalog: kv/cloudflare/catalog/${mount}`;
+  const have = snapshot?.description;
+  return have === want
+    ? undefined
+    : `mount description: want ${JSON.stringify(want)} / have ${JSON.stringify(have)}`;
+};

package/src/openbao/cloudflare-parity-snapshot.ts

@@ -0,0 +1,84 @@
+/**
+ * A directory of `bao read` exports, loaded — the offline stand-in for production that
+ * cloudflare/parity.ts checks the declaration against.
+ *
+ * The layout, as exported on 2026-09-14 (all of it non-secret):
+ *   <dir>/<mount>/<role>.json     `bao read <mount>/roles/<role>` data, `policies` a JSON string
+ *   <dir>/<mount>/_catalog.json   the `kv/cloudflare/catalog/<mount>` document apply-roles.py wrote
+ *   <dir>/_sys-mounts.json        `sys/mounts`, for each mount's description
+ *
+ * ⛔ READ-ONLY AND OFFLINE. Nothing here opens a socket or reads a credential; every other `_*`
+ *   file in a mount directory is ignored, whatever it holds.
+ */
+import { type LiveCloudflareRole, liveRoleOf } from './cloudflare-role-form.ts';
+
+type Json = Readonly<Record<string, unknown>>;
+
+export interface CatalogDocument {
+  /** Every field of the KV document except `roles`. */
+  readonly fields: Json;
+  /** `roles`, which apply-roles.py stored as a JSON string (apply-roles.py:68-76), parsed. */
+  readonly roles: ReadonlyMap<string, Json>;
+}
+
+export interface SnapshotMount {
+  readonly mount: string;
+  readonly roles: ReadonlyMap<string, LiveCloudflareRole>;
+  readonly catalog: CatalogDocument | undefined;
+  /** `sys/mounts/<mount>/` description, when the export has one. */
+  readonly description: string | undefined;
+}
+
+const isJson = (value: unknown): value is Json =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const readJson = async (path: string): Promise<Json | undefined> => {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return undefined;
+  const parsed: unknown = await file.json();
+  if (!isJson(parsed)) throw new Error(`${path}: not a JSON object`);
+  return parsed;
+};
+
+const catalogOf = (doc: Json, path: string): CatalogDocument => {
+  const raw = doc['roles'];
+  const parsed: unknown = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  if (!isJson(parsed)) throw new Error(`${path}: roles is not a JSON object`);
+  const roles = new Map<string, Json>();
+  for (const [name, entry] of Object.entries(parsed)) {
+    if (!isJson(entry)) throw new Error(`${path}: roles.${name} is not an object`);
+    roles.set(name, entry);
+  }
+  const { roles: _roles, ...fields } = doc;
+  return { fields, roles };
+};
+
+/** Load every `cloudflare-*` mount directory under `dir`. */
+export const loadSnapshot = async (dir: string): Promise<SnapshotMount[]> => {
+  const roles = new Map<string, Map<string, LiveCloudflareRole>>();
+  for await (const path of new Bun.Glob('cloudflare-*/*.json').scan({ cwd: dir })) {
+    const [mount, file] = path.split('/');
+    if (mount === undefined || file === undefined || file.startsWith('_')) continue;
+    const data = await readJson(`${dir}/${path}`);
+    if (data === undefined) continue;
+    const byName = roles.get(mount) ?? new Map<string, LiveCloudflareRole>();
+    byName.set(file.replace(/\.json$/, ''), liveRoleOf(data));
+    roles.set(mount, byName);
+  }
+  const sys = await readJson(`${dir}/_sys-mounts.json`);
+  const mounts = isJson(sys?.['data']) ? sys['data'] : sys;
+  const out: SnapshotMount[] = [];
+  for (const mount of [...roles.keys()].sort()) {
+    const catalogPath = `${dir}/${mount}/_catalog.json`;
+    const catalog = await readJson(catalogPath);
+    const entry = mounts?.[`${mount}/`];
+    const description = isJson(entry) ? entry['description'] : undefined;
+    out.push({
+      catalog: catalog === undefined ? undefined : catalogOf(catalog, catalogPath),
+      description: typeof description === 'string' ? description : undefined,
+      mount,
+      roles: roles.get(mount) ?? new Map(),
+    });
+  }
+  return out;
+};

package/src/openbao/cloudflare-parity.ts

@@ -0,0 +1,152 @@
+/**
+ * The parity report: roles.yaml's expansion against a snapshot of production, field by field, with
+ * names resolved to IDs through source (b) — the same solver `permissionGroupsFromLiveRoles` runs.
+ *
+ * ★ PURE, SO THE CHECK IS THE PROVIDER'S OWN CODE AND NOT A SECOND OPINION. `differences` is the
+ *   function diff and reconcile call, `solveGroups` is the function source (b) calls, and the
+ *   expansion is the one declareCloudflareRoles declares. A report that re-implemented any of them
+ *   could agree with production while the provider did not.
+ *
+ * ⛔ EVERY LINE IS A PROBLEM OR SAYS `(none)`. An empty section is printed as `(none)` rather than
+ *   omitted, so a report that silently skipped a mount cannot pass for one that found nothing.
+ */
+import { catalogProblems, descriptionProblem } from './cloudflare-parity-catalog.ts';
+import type { SnapshotMount } from './cloudflare-parity-snapshot.ts';
+import {
+  describeProblems,
+  observationsOf,
+  solveGroups,
+} from './cloudflare-permission-groups-solve.ts';
+import { type WirePolicy, atEveryScope, resolvePolicies } from './cloudflare-policy.ts';
+import { differences } from './cloudflare-role-form.ts';
+import type { ExpandedRole } from './cloudflare-roles-expand.ts';
+
+export interface ParityReport {
+  readonly lines: string[];
+  readonly problems: number;
+}
+
+const section = (lines: string[], title: string, items: readonly string[]) => {
+  if (items.length === 0) {
+    lines.push(`  ${title}: (none)`);
+    return;
+  }
+  lines.push(`  ${title}:`);
+  for (const item of items) lines.push(`    ${item}`);
+};
+
+/** Source (b) over the snapshot, per account — groups by account, and a summary line each. */
+const solveAccounts = (
+  declared: ReadonlyMap<string, readonly ExpandedRole[]>,
+  snapshot: readonly SnapshotMount[],
+  lines: string[],
+) => {
+  const live = new Map<string, readonly WirePolicy[]>();
+  for (const mount of snapshot) {
+    for (const [name, role] of mount.roles) {
+      if (role.policies !== undefined) live.set(`${mount.mount}/${name}`, role.policies);
+    }
+  }
+  const byAccount = new Map<string, ExpandedRole[]>();
+  for (const roles of declared.values()) {
+    for (const role of roles) {
+      byAccount.set(role.account, [...(byAccount.get(role.account) ?? []), role]);
+    }
+  }
+  const groups = new Map<string, ReadonlyMap<string, string>>();
+  let problems = 0;
+  lines.push('permission groups — source (b), bootstrapped from live roles:');
+  for (const [account, roles] of [...byAccount].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    const observations = observationsOf(roles, live);
+    const solved = solveGroups(observations);
+    const found = describeProblems(solved);
+    problems += found.length;
+    groups.set(account, solved.groups);
+    lines.push(
+      `  ${account}: ${String(solved.groups.size)} names resolved from ` +
+        `${String(observations.length)} policy entries; ${String(solved.ambiguous.length)} ` +
+        `ambiguous, ${String(solved.unresolved.length)} unresolved, ` +
+        `${String(solved.contradicted.length)} contradicted`,
+    );
+    for (const problem of found) lines.push(`    ${problem}`);
+  }
+  return { groups, problems };
+};
+
+/**
+ * ★ `observedPrefixes` NAMES ROLES THAT ARE READ, NEVER DECLARED OR WRITTEN — anyauth's, by Tim's
+ *   call on 2026-09-14 ("read only, in case we decide to adopt it later"). A live role under one of
+ *   them is listed in its own section and is not a problem; one that is NOT under a prefix and not
+ *   declared still is, so the carve-out cannot hide an unrelated stray.
+ */
+export const parityReport = (
+  declared: ReadonlyMap<string, readonly ExpandedRole[]>,
+  snapshot: readonly SnapshotMount[],
+  observedPrefixes: readonly string[] = [],
+): ParityReport => {
+  const lines: string[] = [];
+  const solved = solveAccounts(declared, snapshot, lines);
+  let problems = solved.problems;
+  let compared = 0;
+  let identical = 0;
+  let observedTotal = 0;
+  const isObserved = (name: string) => observedPrefixes.some((prefix) => name.startsWith(prefix));
+  const mounts = [...new Set([...declared.keys(), ...snapshot.map((m) => m.mount)])].sort();
+  for (const mount of mounts) {
+    const roles = declared.get(mount) ?? [];
+    const live = snapshot.find((m) => m.mount === mount);
+    const liveRoles = live?.roles ?? new Map();
+    const names = new Set(roles.map((role) => role.name));
+    const onlyDeclared = roles.map((role) => role.name).filter((name) => !liveRoles.has(name));
+    const undeclared = [...liveRoles.keys()].filter((name) => !names.has(name)).sort();
+    const observed = undeclared.filter(isObserved);
+    const onlyLive = undeclared.filter((name) => !isObserved(name));
+    observedTotal += observed.length;
+    const differing: string[] = [];
+    for (const role of roles) {
+      const have = liveRoles.get(role.name);
+      if (have === undefined) continue;
+      compared += 1;
+      // ⚠️ `atEveryScope`: the solver reads live roles, which carry ids and no scopes, so the only
+      //   thing it can say about a name is one id — offered at whatever scope an entry asks for.
+      const ids = solved.groups.get(role.account) ?? new Map<string, string>();
+      const { missing, policies } = resolvePolicies(role.policies, atEveryScope(ids));
+      if (missing.length > 0) {
+        differing.push(`${role.name}: unresolved groups ${missing.join(', ')}`);
+        continue;
+      }
+      const found = differences(role, policies, have);
+      if (found.length === 0) identical += 1;
+      for (const d of found)
+        differing.push(`${role.name}: ${d.field}: want ${d.want} / have ${d.have}`);
+    }
+    const catalog = catalogProblems(mount, roles, live);
+    const description = descriptionProblem(mount, roles, live, observed.length);
+    const catalogCount = live?.catalog?.roles.size;
+    lines.push(
+      '',
+      `${mount}: ${String(roles.length)} declared, ${String(liveRoles.size)} live, ` +
+        `${catalogCount === undefined ? 'no' : String(catalogCount)} in catalog`,
+    );
+    section(lines, 'only in roles.yaml', onlyDeclared);
+    section(lines, 'only live', onlyLive);
+    // ★ Listed, never counted: these are read-only by decision, not drift.
+    section(lines, 'observed read-only (not declared, never written)', observed);
+    section(lines, 'fields differing', differing);
+    section(lines, 'catalog', catalog);
+    section(lines, 'mount description', description === undefined ? [] : [description]);
+    problems +=
+      onlyDeclared.length +
+      onlyLive.length +
+      differing.length +
+      catalog.length +
+      (description === undefined ? 0 : 1);
+  }
+  lines.push(
+    '',
+    `roles compared: ${String(compared)}, identical after resolution: ${String(identical)}`,
+    `observed read-only: ${String(observedTotal)}`,
+    `${String(problems)} problem(s)`,
+  );
+  return { lines, problems };
+};