@homeflare/alchemy 0.1.0

package/dist/forgejo/values.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Wire coercions shared across Forgejo resources.
+ *
+ * ★ GITEA/ FORGEJO JSON USES snake_case ON THE WIRE and camelCase in props — each resource
+ *   translates at the form boundary; these helpers only normalise values for comparison.
+ */
+export declare const text: (value: unknown, fallback?: string) => string;
+/** Forgejo returns label colours without `#`; declarations may include it. */
+export declare const color: (value: unknown) => string;
+export declare const bool: (value: unknown, fallback?: boolean) => boolean;
+export declare const int: (value: unknown, fallback?: number) => number;
+/** Wire arrays compared in sorted order — Gitea reshuffles nothing but callers should not depend on order. */
+export declare const stringArray: (value: unknown) => string[];
+export declare const stringRecord: (value: unknown) => Record<string, string>;
+export declare const recordEqual: (left: Record<string, string>, right: Record<string, string>) => boolean;
+/** Hook `config` without `secret` — the value must never land in Alchemy attributes. */
+export declare const hookConfigPublic: (value: unknown) => {
+    [x: string]: string;
+};
+/** Env key for a write-only org actions secret — value read at PUT time only, never stored. */
+export declare const orgSecretEnvKey: (org: string, name: string) => string;
+/** Env key for a write-only repo webhook HMAC secret — omitted from attributes and props. */
+export declare const hookSecretEnvKey: (owner: string, repo: string, name: string) => string;
+//# sourceMappingURL=values.d.ts.map

package/dist/forgejo/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/forgejo/values.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,IAAI,UAAW,OAAO,8BACW,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,KAAK,UAAW,OAAO,WAAgD,CAAC;AAErF,eAAO,MAAM,IAAI,UAAW,OAAO,gCACgE,CAAC;AAEpG,eAAO,MAAM,GAAG,UAAW,OAAO,8BAOjC,CAAC;AAEF,8GAA8G;AAC9G,eAAO,MAAM,WAAW,UAAW,OAAO,aAGlC,CAAC;AAET,eAAO,MAAM,YAAY,UAAW,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOlE,CAAC;AAEF,eAAO,MAAM,WAAW,SAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAKtF,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,UAAW,OAAO;;CAI9C,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,eAAe,QAAS,MAAM,QAAQ,MAAM,WACyB,CAAC;AAEnF,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,UAAW,MAAM,QAAQ,MAAM,QAAQ,MAAM,WACmB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @homeflare/alchemy — custom Alchemy providers for systems the vendor has none for.
+ *
+ * ⛔ IMPORT A SUBPATH, NOT THIS FILE. Each system carries its own peers and its own
+ *   client; a root barrel would pull Proxmox into a stack that only wanted Forgejo.
+ *
+ *     import { R2BucketLock } from '@homeflare/alchemy/cloudflare';
+ *     import { BranchProtection } from '@homeflare/alchemy/forgejo';
+ *     import { BaoMount } from '@homeflare/alchemy/openbao';
+ *     import { TalosCluster } from '@homeflare/alchemy/talos';
+ *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
+ *
+ * ★ WHY THESE EXIST AT ALL. When Alchemy has no resource for something, the alternative
+ *   is a runbook step a human runs once — and a plan can never show a missing runbook
+ *   step. A custom provider makes the drift visible in `plan` like everything else.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+
+//# debugId=1B152D275122871864756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "1B152D275122871864756E2164756E21",
+  "names": []
+}

package/dist/openbao/auth-role-form.d.ts

@@ -0,0 +1,38 @@
+export interface BaoAuthRoleProps {
+    /** AppRole name, as `auth/approle/role/{name}` takes it. */
+    name: string;
+    /** Policies bound to tokens minted through this role. Names only — never a secret. */
+    tokenPolicies: readonly string[];
+    /** Token TTL, e.g. `15m`. */
+    tokenTtl: string;
+    /** Token max TTL, e.g. `1h`. */
+    tokenMaxTtl: string;
+    /** Secret ID TTL — `0` means non-expiring, as reconcile.sh and apply-consumers.py set. */
+    secretIdTtl: string;
+    /** Whether login requires a secret_id. Defaults to true when omitted on write. */
+    bindSecretId?: boolean;
+    /** `0` means unlimited uses — the shape reconcile.sh writes for headless roles. */
+    secretIdNumUses?: number;
+}
+export interface BaoAuthRoleAttributes {
+    name: string;
+    tokenPolicies: readonly string[];
+    tokenTtl: string;
+    tokenMaxTtl: string;
+    secretIdTtl: string;
+    bindSecretId: boolean;
+    secretIdNumUses: number;
+    /** SHA-256 of the managed fields — safe to persist; see policy.ts. */
+    digest: string;
+}
+export declare const attributesOf: (props: BaoAuthRoleProps, live: Record<string, unknown>) => BaoAuthRoleAttributes;
+export declare const readPath: (name: string) => string;
+/**
+ * The body for `PUT auth/approle/role/<name>`.
+ *
+ * ★ ALL STRINGS, EXACTLY THE `k=v` PAIRS `bao write` USED TO SEND — see `baoWrite` in bao-http.ts.
+ */
+export declare const writeBody: (props: BaoAuthRoleProps) => Record<string, string>;
+/** True when live already matches the declaration on every managed field. */
+export declare const matches: (attributes: BaoAuthRoleAttributes, props: BaoAuthRoleProps) => boolean;
+//# sourceMappingURL=auth-role-form.d.ts.map

package/dist/openbao/auth-role-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-role-form.d.ts","sourceRoot":"","sources":["../../src/openbao/auth-role-form.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;CAChB;AAwBD,eAAO,MAAM,YAAY,UAChB,gBAAgB,QACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,qBAWF,CAAC;AAEF,eAAO,MAAM,QAAQ,SAAU,MAAM,WAAgC,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,SAAS,UAAW,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAYxE,CAAC;AAWF,6EAA6E;AAC7E,eAAO,MAAM,OAAO,eAAgB,qBAAqB,SAAS,gBAAgB,YAUjF,CAAC"}

package/dist/openbao/auth-role.d.ts

@@ -0,0 +1,20 @@
+/**
+ * An OpenBao AppRole auth role — token_policies, TTLs and bind flags. METADATA ONLY.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES — see policy.ts for why. `role_id` and `secret_id`
+ *   are credential issuance, not configuration, and are OUT OF SCOPE. This declares the
+ *   role shape an approle login inherits — policy names and TTL strings only.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a role revokes every token bound to it.
+ *   Opt in with `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { type BaoAuthRoleAttributes, type BaoAuthRoleProps } from './auth-role-form.ts';
+export type { BaoAuthRoleAttributes, BaoAuthRoleProps };
+export interface BaoAuthRole extends Resource<'Bao.AuthRole', BaoAuthRoleProps, BaoAuthRoleAttributes, never, HttpClient.HttpClient> {
+}
+export declare const BaoAuthRole: import("alchemy").ResourceClass<BaoAuthRole>;
+export declare const BaoAuthRoleProvider: () => import("effect/Layer").Layer<Provider.Provider<BaoAuthRole>, never, HttpClient.HttpClient>;
+//# sourceMappingURL=auth-role.d.ts.map

package/dist/openbao/auth-role.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-role.d.ts","sourceRoot":"","sources":["../../src/openbao/auth-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AACnE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAKtB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,CAAC;AAExD,MAAM,WAAW,WAAY,SAAQ,QAAQ,CAC3C,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,EACL,UAAU,CAAC,UAAU,CACtB;CAAG;AAEJ,eAAO,MAAM,WAAW,8CAEtB,CAAC;AASH,eAAO,MAAM,mBAAmB,kGAsD7B,CAAC"}

package/dist/openbao/bao-address.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Where an OpenBao call goes and which headers it carries — resolved from the environment the way
+ * the `bao` CLI resolves it, so the provider and `bao kv get` can never disagree about which server
+ * or namespace this machine is talking to.
+ *
+ * ★ READ FROM openbao v2.6.2, NOT RECALLED:
+ *   · api/client.go:34-66 — BAO_ADDR, BAO_AGENT_ADDR, BAO_NAMESPACE, BAO_TOKEN, and the header
+ *     names `X-Vault-Namespace` and `X-Vault-Token`.
+ *   · api/client.go:370 — the default address, `https://127.0.0.1:8200`.
+ *   · api/client.go:503-507, 617-618, 761-762 — BAO_AGENT_ADDR, when set, WINS over BAO_ADDR.
+ *   · api/env.go:22-34 — every BAO_* falls back to its VAULT_* twin, but a BAO_* that is present
+ *     and EMPTY still wins over the VAULT_* one.
+ *   · api/client.go:776-785 — the token and namespace are applied only when non-empty, and every
+ *     request carries `X-Vault-Request: true`.
+ *   · api/client.go:1349-1354 — the request path is joined onto the address's own path.
+ *
+ * ⛔ WHAT THE CLI DOES AND THIS DELIBERATELY DOES NOT: with BAO_TOKEN unset, `bao` falls back to its
+ *   token helper (a token file in $HOME). This never reads that file. No BAO_TOKEN means AGENT
+ *   MODE — see `headersFor`.
+ * ⚠️ NOT CARRIED OVER: BAO_CACERT / BAO_SKIP_VERIFY / client certificates, SRV lookup, and the CLI's
+ *   retries on 5xx. An https address needs a certificate the runtime already trusts; a TLS failure
+ *   fails the call loudly rather than being skipped.
+ */
+export type BaoEnvironment = Readonly<Record<string, string | undefined>>;
+export type BaoAddress = {
+    /** Scheme, host and any path prefix, no trailing slash. `http://localhost` for a socket. */
+    readonly base: string;
+    /** The socket path when the address is `unix:///path`, otherwise undefined. */
+    readonly socket: string | undefined;
+    /** The namespace to send, when there is one. */
+    readonly namespace: string | undefined;
+};
+export declare const DEFAULT_ADDRESS = "https://127.0.0.1:8200";
+/** api/env.go ReadBaoVariable: present (even empty) BAO_* wins, else the VAULT_* twin. */
+export declare const readBaoVariable: (env: BaoEnvironment, name: `BAO_${string}`) => string;
+/**
+ * The address and namespace for this environment. Carries no token, so it is safe to log.
+ *
+ * ★ UNIX SOCKETS, BECAUSE AN AGENT LISTENER CAN BE ONE. OpenBao Agent's `listener "unix"` serves
+ *   the same API on a socket (website/content/docs/agent-and-proxy/agent/index.mdx:382-384), and the
+ *   agent advertises such a listener as `unix://<path>` (command/agent.go:565-566). The CLI handles
+ *   that address by dialling the socket and speaking plain HTTP to host `localhost`
+ *   (api/client.go:654-667); `base` and `socket` are exactly those two halves.
+ */
+export declare const resolveAddress: (env: BaoEnvironment) => BaoAddress;
+/**
+ * The headers one call sends.
+ *
+ * ★ AGENT MODE IS "NO TOKEN HEADER AT ALL", AND THAT IS THE AGENT'S OWN CONTRACT. Read in openbao
+ *   v2.6.2 command/agentproxyshared/cache/handler.go:29-38: the proxy handler takes the request's
+ *   `X-Vault-Token`, and only when it is EMPTY and an auto-auth sink exists does it substitute the
+ *   agent's own token. command/agent.go:517-541 creates that sink exactly when
+ *   `api_proxy { use_auto_auth_token = true }` is set; command/agent/config/config.go:288-292 and
+ *   635-637 map the older `cache { use_auto_auth_token }` onto the same setting; and
+ *   command/proxy.go:495-518 wires OpenBao Proxy identically. The docs say the same in words
+ *   (website/content/docs/agent-and-proxy/agent/apiproxy.mdx:57-62): a request without a token is
+ *   forwarded with the auto-auth token, a request that bears one keeps its own, and `"force"`
+ *   overwrites it.
+ *   ⛔ SO AN EMPTY `X-Vault-Token: ` WOULD BE WRONG IN BOTH DIRECTIONS: harmless to the agent,
+ *     which reads empty as absent, but an explicit unauthenticated request to a server. The header
+ *     is omitted, never blanked.
+ * ★ THE NAMESPACE RIDES THROUGH THE AGENT UNTOUCHED. The proxy clones its client and replaces that
+ *   client's headers with the incoming request's (cache/api_proxy.go:50-54 and :78), so the
+ *   `X-Vault-Namespace` sent here is the one OpenBao sees.
+ * ⚠️ `X-Vault-Request: true` IS NOT DECORATION. An agent listener with `require_request_header`
+ *   refuses any request without it (command/agent.go:544-548); the CLI always sends it.
+ *
+ * ⛔ THE RETURN VALUE HOLDS THE TOKEN. Hand it to the request and nowhere else: never to an error,
+ *   a log line, an attribute, or a span — bao-http.ts adds the header to the redacted names.
+ */
+export declare const headersFor: (address: BaoAddress, env: BaoEnvironment) => Record<string, string>;
+//# sourceMappingURL=bao-address.d.ts.map

package/dist/openbao/bao-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bao-address.d.ts","sourceRoot":"","sources":["../../src/openbao/bao-address.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAE1E,MAAM,MAAM,UAAU,GAAG;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF,eAAO,MAAM,eAAe,2BAA2B,CAAC;AAIxD,0FAA0F;AAC1F,eAAO,MAAM,eAAe,QAAS,cAAc,QAAQ,OAAO,MAAM,EAAE,KAAG,MACf,CAAC;AAE/D;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,QAAS,cAAc,KAAG,UAWpD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU,YAAa,UAAU,OAAO,cAAc,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAM1F,CAAC"}

package/dist/openbao/bao-http.d.ts

@@ -0,0 +1,71 @@
+/**
+ * One call to OpenBao's HTTP API through Effect's `HttpClient` — the transport every Bao.* family
+ * uses since it stopped shelling out to `bao`.
+ *
+ * ★ `HttpClient`, THE SAME PATTERN house/proxmox and house/forgejo USE AGAINST THEIR APIs, decided
+ *   2026-09-14. It buys a typed error channel, interruption when a plan is cancelled, the runtime's
+ *   tracing, and a client a test can point at a fake server — and it needs no Alchemy session, so
+ *   every call here works from all four operations. (`CommandExecutor.run` was tried on Bao.Policy
+ *   first and blocked read/diff: Alchemy passes a session to reconcile/delete but NOT to read/diff,
+ *   Provider.ts:258-289. The ChildProcessSpawner that fixed that is gone with the CLI.)
+ * ⚠️ THE STACK MUST PROVIDE `FetchHttpClient.layer`. alchemy.run.ts does, the way
+ *   house/proxmox/alchemy.run.ts does.
+ */
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Semaphore from 'effect/Semaphore';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { BaoError, type BaoIntent } from './bao-status.ts';
+/**
+ * The environment a call resolves BAO_ADDR, BAO_NAMESPACE and BAO_TOKEN from — `process.env`,
+ * read at call time, unless a test provides another.
+ */
+export declare const BaoEnv: Context.Reference<Readonly<Record<string, string | undefined>>>;
+/**
+ * ⛔ AT MOST EIGHT EXCHANGES WITH OPENBAO AT ONCE — ACROSS EVERY Bao.* FAMILY, IN ONE PROCESS.
+ *
+ * 🔴 MEASURED 2026-09-14 10:41: A DEPLOY OF THIS STACK TOOK OPENBAO's API OFF THE MINI. Alchemy fans
+ *   resources out with a hard-coded `concurrency: "unbounded"` (alchemy Plan.ts:476, Apply.ts:259,
+ *   :263, :303 — no option reaches it), and 555 Bao.CloudflareRole resources each read, diff,
+ *   reconcile and read back: well over a thousand requests at one loopback listener within seconds.
+ *   OpenBao logged
+ *     HTTP server (listening on 127.0.0.1:8200) exited with error: set tcp
+ *     127.0.0.1:8200->127.0.0.1:57974: setsockopt: invalid argument
+ *   and KEPT RUNNING with 8200 closed. launchd saw a live process and restarted nothing. Everything
+ *   on the mini that talks to 127.0.0.1:8200 was cut off, starting with the agent's templates, until
+ *   a manual restart.
+ * ★ THE LISTENER DYING IS A GO-ON-DARWIN FAILURE, NOT OURS TO FIX. Traefik lost its entrypoints the
+ *   same way on darwin/arm64 (traefik issue 8841). The BURST is ours. The adoption deploy an hour
+ *   earlier made the same calls and survived, so a cap narrows a race; it does not prove it closed.
+ * ★ A SEMAPHORE, NOT `HttpClient.withRateLimiter`. That limits requests per window and needs a
+ *   RateLimiter service. The failure is simultaneous connections, and only a cap on in-flight
+ *   exchanges bounds those whatever each one's latency.
+ * ⚠️ A Context.Reference SO A TEST CAN PROVIDE ITS OWN GATE. The default is built ONCE and cached on
+ *   the reference (effect Context.ts:1582-1588), so every call in the process shares one gate.
+ * ⚠️ EIGHT IS A CHOICE, NOT A MEASUREMENT OF WHAT THE LISTENER TOLERATES. Nothing here can find that
+ *   number without re-running the failure against production.
+ */
+export declare const MAX_IN_FLIGHT = 8;
+export declare const BaoGate: Context.Reference<Semaphore.Semaphore>;
+/** One exchange, classified. The body is the parsed JSON object, or undefined for absent / 204. */
+export declare const baoCall: (intent: BaoIntent, method: 'DELETE' | 'GET' | 'POST' | 'PUT', path: string, body?: Readonly<Record<string, unknown>>) => Effect.Effect<Record<string, unknown> | undefined, BaoError, HttpClient.HttpClient>;
+/**
+ * The `data` of a read, or undefined when OpenBao says the object is ABSENT (404).
+ *
+ * ★ `bao read -format=json` printed this same response body; the old helper took `data` when it was
+ *   an object and the whole body otherwise, and so does this.
+ */
+export declare const baoRead: (path: string) => Effect.Effect<Record<string, unknown> | undefined, BaoError, HttpClient.HttpClient>;
+/**
+ * A write whose SUCCESS MATTERS. Any non-2xx fails, 404 included.
+ *
+ * ★ `PUT` IS WHAT `bao write` SENT (openbao v2.6.2 api/logical.go Write); `sys/mounts` enable and
+ *   tune are `POST` in the same client (api/sys_mounts.go:57, :201).
+ * ⚠️ ROLE BODIES STAY ALL-STRING ON PURPOSE. `bao write k=v` put every value in the JSON body as a
+ *   string — MEASURED with `-output-curl-string`, see ssh-role-form.ts — and the form files still
+ *   build exactly that body, so the server parses the same request it was always sent.
+ */
+export declare const baoWrite: (method: 'POST' | 'PUT', path: string, body: Readonly<Record<string, unknown>>) => Effect.Effect<void, BaoError, HttpClient.HttpClient>;
+/** A delete: idempotent — already gone (404) is success — and refused (403, 5xx) is a failure. */
+export declare const baoDelete: (path: string) => Effect.Effect<void, BaoError, HttpClient.HttpClient>;
+//# sourceMappingURL=bao-http.d.ts.map

package/dist/openbao/bao-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bao-http.d.ts","sourceRoot":"","sources":["../../src/openbao/bao-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAG9C,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAG9D,OAAO,EAAE,QAAQ,EAAE,KAAK,SAAS,EAAU,MAAM,iBAAiB,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,MAAM,iEAEjB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,eAAO,MAAM,OAAO,wCAElB,CAAC;AAoDH,mGAAmG;AACnG,eAAO,MAAM,OAAO,WACV,SAAS,UACT,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,QACnC,MAAM,SACL,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,wFAkCtC,CAAC;AAEL;;;;;GAKG;AACH,eAAO,MAAM,OAAO,SAAU,MAAM,wFAOhC,CAAC;AAEL;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,WACX,MAAM,GAAG,KAAK,QAChB,MAAM,QACN,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,yDACe,CAAC;AAEzD,kGAAkG;AAClG,eAAO,MAAM,SAAS,SAAU,MAAM,yDAAqD,CAAC"}

package/dist/openbao/bao-status.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 declare class BaoError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly errors: readonly string[];
+    constructor(status: number, method: string, path: string, errors: readonly string[]);
+}
+export type Settled = {
+    readonly body: Record<string, unknown> | undefined;
+} | {
+    readonly error: BaoError;
+};
+/**
+ * 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 declare const settle: (intent: BaoIntent, method: string, path: string, status: number, text: string) => Settled;
+//# sourceMappingURL=bao-status.d.ts.map

package/dist/openbao/bao-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bao-status.d.ts","sourceRoot":"","sources":["../../src/openbao/bao-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpD;;;;;;;;GAQG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE;IAJpC,YACW,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,MAAM,EAAE,EAKnC;CACF;AAED,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AA+BjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,MAAM,WACT,SAAS,UACT,MAAM,QACR,MAAM,UACJ,MAAM,QACR,MAAM,KACX,OAsBF,CAAC"}

package/dist/openbao/cloudflare-group-scope.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 declare const zoneResource: (zoneId: string) => string;
+export declare const accountResource: (accountId: string) => string;
+/**
+ * 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 declare const bucketResource: (accountId: string, jurisdiction: string, bucket: string) => string;
+/**
+ * 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 declare const GROUP_SCOPES: {
+    readonly account: 'com.cloudflare.api.account';
+    readonly bucket: 'com.cloudflare.edge.r2.bucket';
+    readonly zone: 'com.cloudflare.api.account.zone';
+};
+/**
+ * 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 declare const groupScopeNamed: (word: string) => string | undefined;
+/**
+ * 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 declare const scopeOfResource: (resource: string) => string;
+/**
+ * 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 declare const groupKey: (name: string, scope: string) => string;
+//# sourceMappingURL=cloudflare-group-scope.d.ts.map

package/dist/openbao/cloudflare-group-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-group-scope.d.ts","sourceRoot":"","sources":["../../src/openbao/cloudflare-group-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uBAAuB;AACvB,eAAO,MAAM,YAAY,WAAY,MAAM,WAAgD,CAAC;AAC5F,eAAO,MAAM,eAAe,cAAe,MAAM,WAA8C,CAAC;AAEhG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,cAAe,MAAM,gBAAgB,MAAM,UAAU,MAAM,WACd,CAAC;AAEzE;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;aACvB,OAAO,EAAE,4BAA4B;aACrC,MAAM,EAAE,+BAA+B;aACvC,IAAI,EAAE,iCAAiC;CAC/B,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,SAAU,MAAM,KAAG,MAAM,GAAG,SACW,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,aAAc,MAAM,WAG/C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,SAAU,MAAM,SAAS,MAAM,WAAuB,CAAC"}

package/dist/openbao/cloudflare-parity-catalog.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { ExpandedRole } from './cloudflare-roles-expand.ts';
+export declare const catalogProblems: (mount: string, declared: readonly ExpandedRole[], snapshot: SnapshotMount | undefined) => string[];
+/**
+ * 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 declare const descriptionProblem: (mount: string, declared: readonly ExpandedRole[], snapshot: SnapshotMount | undefined, observedCount?: number) => string | undefined;
+//# sourceMappingURL=cloudflare-parity-catalog.d.ts.map

package/dist/openbao/cloudflare-parity-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-parity-catalog.d.ts","sourceRoot":"","sources":["../../src/openbao/cloudflare-parity-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,8BAA8B,CAAC;AA0B9E,eAAO,MAAM,eAAe,UACnB,MAAM,YACH,SAAS,YAAY,EAAE,YACvB,aAAa,GAAG,SAAS,KAClC,MAAM,EAkCR,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,UACtB,MAAM,YACH,SAAS,YAAY,EAAE,YACvB,aAAa,GAAG,SAAS,6BAElC,MAAM,GAAG,SAQX,CAAC"}

package/dist/openbao/cloudflare-parity-snapshot.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 } 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;
+}
+/** Load every `cloudflare-*` mount directory under `dir`. */
+export declare const loadSnapshot: (dir: string) => Promise<SnapshotMount[]>;
+export {};
+//# sourceMappingURL=cloudflare-parity-snapshot.d.ts.map

package/dist/openbao/cloudflare-parity-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-parity-snapshot.d.ts","sourceRoot":"","sources":["../../src/openbao/cloudflare-parity-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,KAAK,kBAAkB,EAAc,MAAM,2BAA2B,CAAC;AAEhF,KAAK,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACxD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CAAC;IAC9C,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AA0BD,6DAA6D;AAC7D,eAAO,MAAM,YAAY,QAAe,MAAM,KAAG,OAAO,CAAC,aAAa,EAAE,CA2BvE,CAAC"}

package/dist/openbao/cloudflare-parity.d.ts

@@ -0,0 +1,14 @@
+import type { SnapshotMount } from './cloudflare-parity-snapshot.ts';
+import type { ExpandedRole } from './cloudflare-roles-expand.ts';
+export interface ParityReport {
+    readonly lines: string[];
+    readonly problems: number;
+}
+/**
+ * ★ `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 declare const parityReport: (declared: ReadonlyMap<string, readonly ExpandedRole[]>, snapshot: readonly SnapshotMount[], observedPrefixes?: readonly string[]) => ParityReport;
+//# sourceMappingURL=cloudflare-parity.d.ts.map

package/dist/openbao/cloudflare-parity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-parity.d.ts","sourceRoot":"","sources":["../../src/openbao/cloudflare-parity.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAQrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAiDD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,aACb,WAAW,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC,YAC5C,SAAS,aAAa,EAAE,qBAChB,SAAS,MAAM,EAAE,KAClC,YAkEF,CAAC"}

package/dist/openbao/cloudflare-permission-groups-solve.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ⚠️ TEMPORARY — DELETE WITH `permissionGroupsFromLiveRoles` (cloudflare-permission-groups.ts) ONCE
+ *   `GET <mount>/permission-groups` IS DEPLOYED ON THE CLOUDFLARE ENGINE.
+ *
+ * The pure half of the bootstrap: recover permission-group name → ID from roles whose names are
+ * declared (roles.yaml) and whose IDs are live (the engine).
+ *
+ * ★ WHY IT EXISTS AT ALL. apply-roles.py resolved names with
+ *   `GET /accounts/<id>/tokens/permission_groups` (cfhf.py:147-148) under a Cloudflare parent
+ *   credential, which agents may not use. The engine is gaining an endpoint that answers under its
+ *   own credential; until it ships, the only other witness is the roles apply-roles.py already
+ *   wrote, each pairing a list of names with a list of IDs.
+ *
+ * ⛔ NEVER A GUESS.
+ *   1. Every entry with exactly one name and one ID binds that pair.
+ *   2. Then, until nothing changes: an entry left with exactly ONE name and ONE ID not yet known
+ *      binds those two.
+ *   3. Once settled, every entry is checked against the map: one that declares a known name without
+ *      carrying that name's ID CONTRADICTS it.
+ *   POSITIONS ARE NEVER USED, even where the Python kept yaml order — a hand-edited role would
+ *   otherwise teach the map a wrong pair in silence. A name bound to two IDs, or an ID bound to two
+ *   names, is AMBIGUOUS; a name nothing isolates is UNRESOLVED; and a contradiction is exactly
+ *   that. Each is an error for the whole account, not a best effort.
+ *
+ * ⛔ THE CONTRADICTION CHECK IS THE ONE THAT BITES, AND IT WAS FOUND BY A TEST, NOT BY DESIGN. When a
+ *   name has ONE single-group witness and that role was edited by hand, step 1 learns the edited ID,
+ *   and the multi-group roles carrying the real one merely fail to eliminate. Unchecked, diff would
+ *   then plan every one of those roles as an update TO THE EDITED ID — a hand edit propagated by the
+ *   tool meant to catch it. Which side is wrong is unknowable here; only Cloudflare knows.
+ * ⚠️ THE PRICE: SOURCE (b) CANNOT PLAN A GROUP ADDED TO, OR SWAPPED IN, AN EXISTING ROLE. That edit
+ *   looks exactly like the hand edit above — declared names disagreeing with live IDs — so it fails
+ *   the account. New roles and removed groups still plan. (b) is for ADOPTION; changes wait for (a).
+ *
+ * ⛔ IT KEYS BY NAME AND THE ENGINE SOURCE KEYS BY (NAME, SCOPE) — DELIBERATELY UNCHANGED, 2026-09-15.
+ *   A live role is a list of ids with no scopes, so a name is all this can key on; seven names the
+ *   engine lists TWICE (once account-scoped, once zone-scoped) are one entry here, holding whichever
+ *   id the estate happens to carry. cloudflare-policy.ts `atEveryScope` is where that map is widened
+ *   to the scoped key the resolver now uses, and it is the honest shape of this blind spot: this file
+ *   is the OFFLINE PARITY PROOF against a production export, and rewriting it to a key it cannot
+ *   observe would make it agree with the engine by construction instead of by measurement.
+ *
+ * ⚠️ WHAT IT CANNOT CATCH. The names come from roles.yaml itself, so a group misnamed CONSISTENTLY
+ *   — every use of `DNS Read` spelled `DNS Reed` — pairs the wrong name with the right ID and
+ *   resolves cleanly, where Cloudflare would have refused it. cloudflare/parity.ts cross-checks the
+ *   catalog documents apply-roles.py wrote, which hold names that DID resolve against Cloudflare at
+ *   the last apply, for exactly that reason. The engine endpoint has no such blind spot.
+ */
+import type { WirePolicy } from './cloudflare-policy.ts';
+import type { ExpandedRole } from './cloudflare-roles-expand.ts';
+export interface Observation {
+    /** `<mount>/<role>[<entry>]`, for messages. */
+    readonly where: string;
+    readonly names: readonly string[];
+    readonly ids: readonly string[];
+}
+export interface Conflict {
+    /** `name` bound to several IDs, or `id` bound to several names. */
+    readonly kind: 'id' | 'name';
+    readonly value: string;
+    readonly bound: readonly string[];
+}
+/** An entry declaring `name`, whose ID the map knows as `id`, without carrying `id`. */
+export interface Contradiction {
+    readonly where: string;
+    readonly name: string;
+    readonly id: string;
+}
+export interface Solved {
+    readonly groups: ReadonlyMap<string, string>;
+    readonly ambiguous: readonly Conflict[];
+    readonly unresolved: readonly string[];
+    readonly contradicted: readonly Contradiction[];
+}
+/**
+ * One observation per declared entry whose resource matches exactly one live entry of that role.
+ *
+ * ★ PAIRED BY RESOURCE, NOT BY POSITION. A zone role's account groups sit on the account resource
+ *   and nowhere else, whatever order the entries were stored in. An entry that shares its resource
+ *   with a sibling, or finds no single live match, observes nothing — the diff reports it instead.
+ */
+export declare const observationsOf: (declared: readonly ExpandedRole[], live: ReadonlyMap<string, readonly WirePolicy[]>) => Observation[];
+export declare const solveGroups: (observations: readonly Observation[]) => Solved;
+/** Every conflict, unresolved name and contradiction, one line each. */
+export declare const describeProblems: (solved: Solved) => string[];
+//# sourceMappingURL=cloudflare-permission-groups-solve.d.ts.map