@homeflare/alchemy 0.31.0 → 0.31.2

package/dist/proxmox/user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/proxmox/user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAe,MAAM,eAAe,CAAC;AAGnF,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,WAAY,SAAQ,QAAQ,CAC3C,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,eAAO,MAAM,WAAW,8CAAwC,CAAC;AAmGjE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,iIACiD,CAAC"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/proxmox/user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAI7C,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AActE,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,WAAY,SAAQ,QAAQ,CAC3C,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,eAAO,MAAM,WAAW,8CAAwC,CAAC;AAEjE,eAAO,MAAM,mBAAmB,iIAgG7B,CAAC"}

package/dist/proxmox/zfs-pool-write.d.ts

@@ -110,7 +110,7 @@ export declare const createForm: (props: ZfsPoolProps) => Record<string, string>
  *   here is the same `Effect.die` idiom as every other refusal in this package, and it costs
  *   nothing this pool did not already lack.
  */
-export declare const createPool: <E, R>(props: ZfsPoolProps, collection: string, path: string, read: (props: ZfsPoolProps) => Effect.Effect<ZfsPoolAttributes | undefined, E, R>) => Effect.Effect<ZfsPoolAttributes, E | Error, R | import("effect/unstable/http/HttpClient").HttpClient>;
+export declare const createPool: <E, R>(props: ZfsPoolProps, collection: string, path: string, read: (props: ZfsPoolProps) => Effect.Effect<ZfsPoolAttributes | undefined, E, R>) => Effect.Effect<ZfsPoolAttributes, E | Error | import("./credential-errors.ts").PveCredentialDenied, R | import("effect/unstable/http/HttpClient").HttpClient>;
 /**
  * ⛔ `DELETE /nodes/{node}/disks/zfs/{name}` RUNS `zpool destroy` AND THE DATASETS GO WITH IT. Per
  *   S14 (alchemy-provider-standard), it is implemented rather than stubbed — a `delete` that
@@ -124,5 +124,5 @@ export declare const createPool: <E, R>(props: ZfsPoolProps, collection: string,
  *   resource reaching over to delete another's is how a stack ends up with state describing
  *   something that is gone.
  */
-export declare const destroyPool: (olds: ZfsPoolProps, path: string) => Effect.Effect<unknown, Error, import("effect/unstable/http/HttpClient").HttpClient>;
+export declare const destroyPool: (olds: ZfsPoolProps, path: string) => Effect.Effect<unknown, Error | import("./credential-errors.ts").PveCredentialDenied, import("effect/unstable/http/HttpClient").HttpClient>;
 //# sourceMappingURL=zfs-pool-write.d.ts.map

package/dist/proxmox/zfs-pool-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zfs-pool-write.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAA6D,CAAC;AAE9F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,UAAW,YAAY,KAAG,YACiC,CAAC;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,UAAW,YAAY,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOpE,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SACtB,YAAY,cACP,MAAM,QACZ,MAAM,QACN,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,0GA8C/E,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,wFACb,CAAC"}
+{"version":3,"file":"zfs-pool-write.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAA6D,CAAC;AAE9F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,UAAW,YAAY,KAAG,YACiC,CAAC;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,UAAW,YAAY,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOpE,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SACtB,YAAY,cACP,MAAM,QACZ,MAAM,QACN,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,iKA8C/E,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,+IACb,CAAC"}

package/dist/verify/fake-engine.d.ts

@@ -48,11 +48,25 @@ export declare const writesOf: (cloud: Cloud) => string[];
 export declare const thingProviders: (cloud: Cloud) => Layer.Layer<Alchemy.Provider<Blind> | Alchemy.Provider<Recorded> | Alchemy.Provider<Thing>, never, never>;
 /** A stack body: resource declarations, as an `alchemy.run.ts` would write them. */
 export type Body = Effect.Effect<unknown, unknown, unknown>;
+/** One row of `Alchemy.Drift.detect`'s dry-run report — the fields `drift` below asserts on. */
+export type DriftRow = {
+    readonly action: string;
+};
 export interface FakeEngine {
     /** Plan and apply `body`, as `alchemy deploy --adopt` would; resolves to the planned actions. */
     readonly deploy: (body: Body) => Promise<Record<string, string>>;
     /** Verify `body` against what the earlier deploys recorded. */
     readonly verify: (body: Body, options?: VerifyOptions) => Promise<AdoptReport>;
+    /**
+     * `alchemy drift`'s own dry-run (`Alchemy.Drift.detect`) over whatever `deploy` already
+     * persisted — `body` is used only to resolve the stack's name/stage/providers, exactly as
+     * `verify` does; drift itself reads the state store, not `body`'s declarations. ⚠️ A DIFFERENT
+     * ENGINE PATH FROM `verify`'s `--all` READ, proxmox/read-failure-propagation.test.ts's own ⛔:
+     * `Drift.ts` calls a provider's `read` with `output` set to the PERSISTED attributes, and folds
+     * a `read` that resolves `undefined` into `{action: 'missing'}` with no error — silent, unlike
+     * `verify.ts`'s `readWithState`, which already wraps that same call in `Effect.catchCause`.
+     */
+    readonly drift: (body: Body) => Promise<Record<string, DriftRow>>;
     /**
      * Every state row the store holds, as JSON — what a Postgres store would persist. ★ For tests
      * that must prove a value NEVER reaches state (proxmox/pbs-notification-target-state.test.ts).

package/dist/verify/fake-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-engine.d.ts","sourceRoot":"","sources":["../../src/verify/fake-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAKnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAiB,MAAM,aAAa,CAAC;AAElF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAM,SAAQ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AAC7F,eAAO,MAAM,KAAK,8BAAwC,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,KAAM,SAAQ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AAC7F,eAAO,MAAM,KAAK,8BAAwC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,QAAS,SAAQ,OAAO,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AACnG,eAAO,MAAM,QAAQ,iCAA8C,CAAC;AAEpE,gGAAgG;AAChG,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,OAAO,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAQ,KAI1D,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,UAAW,KAAK,KAAG,MAAM,EAC2C,CAAC;AAyB1F,4FAA4F;AAC5F,eAAO,MAAM,cAAc,UAAW,KAAK,8GAmCxC,CAAC;AAEJ,oFAAoF;AACpF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAK5D,MAAM,WAAW,UAAU;IACzB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,KAAG,UAyC3E,CAAC;AAEF,oCAAoC;AACpC,eAAO,MAAM,UAAU,UAAW,KAAK,KAAG,UAA+C,CAAC"}
+{"version":3,"file":"fake-engine.d.ts","sourceRoot":"","sources":["../../src/verify/fake-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAKnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAiB,MAAM,aAAa,CAAC;AAElF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAM,SAAQ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AAC7F,eAAO,MAAM,KAAK,8BAAwC,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,KAAM,SAAQ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AAC7F,eAAO,MAAM,KAAK,8BAAwC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,QAAS,SAAQ,OAAO,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AACnG,eAAO,MAAM,QAAQ,iCAA8C,CAAC;AAEpE,gGAAgG;AAChG,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,OAAO,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAQ,KAI1D,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,UAAW,KAAK,KAAG,MAAM,EAC2C,CAAC;AAyB1F,4FAA4F;AAC5F,eAAO,MAAM,cAAc,UAAW,KAAK,8GAmCxC,CAAC;AAEJ,oFAAoF;AACpF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAK5D,gGAAgG;AAChG,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAClE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,KAAG,UAmD3E,CAAC;AAEF,oCAAoC;AACpC,eAAO,MAAM,UAAU,UAAW,KAAK,KAAG,UAA+C,CAAC"}

package/docs/grafana.md

@@ -8,32 +8,61 @@ publicly at `tesla.homeflare.dev/dash/`.
 
 ## The SDK gap — why only `Datasource` ships
 
+✅ **SDK-level gap fixed 2026-09-24** (`@distilled.cloud/grafana`, aliased onto
+`@homeflare/distilled-grafana` — 0.1.0 pre-release, 0.2.0 once its `minor` changeset publishes it;
+see [docs/distilled-interim.md](./distilled-interim.md)).
+The gap below is otherwise unchanged and left as evidence of what was measured and why; only its
+status line moved. **Still true today:** only `Grafana.Datasource` ships as a house _resource_ —
+`Grafana.Folder`, `Grafana.Dashboard`, `Grafana.AlertRule` and friends are follow-up work on top of
+the now-available SDK operations, not part of this fix.
+
 Measured 2026-09-24 against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball (its
-`lib/services/grafana.d.ts`, 4,938 lines): the package has **no create/read/update/delete
-operations for folders, dashboards, alert rules or contact points**. It covers datasources in
+`lib/services/grafana.d.ts`, 4,938 lines): the package had **no create/read/update/delete
+operations for folders, dashboards, alert rules or contact points**. It covered datasources in
 full (`addDataSource`, `getDataSourceByUID`, `updateDataSourceByUID`, `deleteDataSourceByUID`,
 `getDataSources`), plus org/user/team/role/report/annotation/library-element/public-dashboard/
 snapshot management — but:
 
-- **Folders:** only `updateFolderPermissions` exists. No `createFolder`, `getFolder` or
-  `deleteFolder` — Grafana's `/api/folders` and `/api/folders/{uid}` routes are entirely absent.
-- **Dashboards:** only snapshot and public-dashboard routes exist (`createDashboardSnapshot`,
+- **Folders:** only `updateFolderPermissions` existed. No `createFolder`, `getFolder` or
+  `deleteFolder` — Grafana's `/api/folders` and `/api/folders/{uid}` routes were entirely absent.
+- **Dashboards:** only snapshot and public-dashboard routes existed (`createDashboardSnapshot`,
   `getPublicDashboard`, …). No `POST /api/dashboards/db`, no `GET /api/dashboards/uid/{uid}`, no
-  `DELETE /api/dashboards/uid/{uid}` — the plain dashboard CRUD route family is absent.
+  `DELETE /api/dashboards/uid/{uid}` — the plain dashboard CRUD route family was absent.
 - **Alert rules:** only `routeGetAlertRuleExport`/`routeGetAlertRuleGroupExport`/
-  `routeGetAlertRulesExport` exist — export (read-only) endpoints under `/api/v1/provisioning/`.
+  `routeGetAlertRulesExport` existed — export (read-only) endpoints under `/api/v1/provisioning/`.
   No create/update/delete for `/api/v1/provisioning/alert-rules{,/{uid}}`.
-- **Contact points:** only `routeGetContactpointsExport` exists, same story — no
+- **Contact points:** only `routeGetContactpointsExport` existed, same story — no
   `/api/v1/provisioning/contact-points{,/{uid}}` CRUD.
 
-This is recorded in [`docs/upstream-conformance.md`](./upstream-conformance.md) rather than worked
+**Root cause, measured (not the spec lacking the paths):** Grafana's own OpenAPI document has
+every one of the routes above — the converter dropped them. `skipDeprecated: true` (the distilled
+converter's v0 default) skips any operation the spec marks `deprecated: true`, and Grafana marks
+its entire classic folder/dashboard/alerting-provisioning WRITE surface deprecated, each
+operation's `description` pointing at a `/apis/<group>.grafana.app/v1/...` Kubernetes-apiserver
+route that is a separate API server with its own OpenAPI document — absent from this spec
+entirely, and not what this family's `Grafana.Datasource` (or any planned `Grafana.Folder`/
+`Grafana.Dashboard`/etc.) targets. The fix patches `deprecated` back to `false` on exactly the 32
+operations this gap named (leaving the other 32 deprecated operations — playlists, org/user
+preferences, datasources-by-name, licensing, reports, dashboard stars/tags/versions — excluded, as
+before): see the distilled clone's `packages/grafana/scripts/convert.ts` header and
+`patches/*.patch.json` for the exact list and reasoning, and
+`packages/distilled-grafana/README.md` in this kit for the copied result. `Grafana.Datasource`'s
+own operations (`addDataSource`/`getDataSourceByUID`/`updateDataSourceByUID`/
+`deleteDataSourceByUID`) were never deprecated and are untouched — same props, same attributes,
+same generated code, confirmed by diffing the distilled clone's regenerated output against its
+prior commit operation-by-operation.
+
+This was recorded in [`docs/upstream-conformance.md`](./upstream-conformance.md) rather than worked
 around. Per S23, the fix is a distilled PR (regenerate against a spec that includes these routes,
-or patch them in per S22), not a hand-rolled `HttpClient` client in this package for the missing
-pieces alone — that would put half a family through the SDK and half through a second, parallel
-client, exactly what S23 exists to prevent.
-
-`teslamate-grafana` itself is consistent with this gap being real, not merely unexploited: its one
-datasource is API-manageable and already exists; its dashboards ship baked into the
+or patch them in per S22) — not a hand-rolled `HttpClient` client in this package for the missing
+pieces alone, which would put half a family through the SDK and half through a second, parallel
+client, exactly what S23 exists to prevent. It shipped as a kit interim package
+(`@homeflare/distilled-grafana`), the same S22 route `@homeflare/distilled-netbox` established,
+because `alchemy-run/distilled` is upstream and this house never pushes to it (decision 42) — see
+docs/distilled-interim.md.
+
+`teslamate-grafana` itself is consistent with this gap having been real, not merely unexploited:
+its one datasource is API-manageable and already exists; its dashboards ship baked into the
 `teslamate/grafana` image and are provisioned by the container, not by any API call; it has no
 folders, alert rules or contact points configured at all (measured over ssh, read-only, 2026-09-24).
 
@@ -96,7 +125,8 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
 
 ## Not covered
 
-- **Folders, dashboards, alert rules, contact points.** Blocked on the SDK gap above — a
-  maintainer decision on whether to patch distilled or wait for upstream to add the routes.
+- **Folders, dashboards, alert rules, contact points, notification policies, mute timings.** The
+  SDK-level blocker is fixed (above); no house `Resource` calls these operations yet — follow-up
+  work, not blocked on anything.
 - **`read` never answers `Unowned`** — the same open gap forgejo's and netbox's own families
   still carry (see upstream-conformance.md); a maintainer decision on the ownership-check shape.

package/docs/upstream-conformance.md

@@ -249,10 +249,20 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     `GET/DELETE /dashboards/uid/{uid}`), alert rules or contact points (both have only a
     `routeGet*Export` read-only route under `/v1/provisioning/`, no create/update/delete). S1
     found no upstream `Alchemy` family for any of these either. Full detail:
-    [grafana.md](./grafana.md#the-sdk-gap--why-only-datasource-ships). **Decision:** maintainer,
-    on whether the kit patches distilled (S22) or waits for upstream to add the routes — S23
-    forbids a hand-rolled `HttpClient` client for the missing pieces alone, half a family through
-    the SDK and half through a second client.
+    [grafana.md](./grafana.md#the-sdk-gap--why-only-datasource-ships).
+
+    ✅ **S22 fixed 2026-09-24** (branch `claude2/distilled-grafana`): root cause measured to be
+    `skipDeprecated: true` dropping 64 operations Grafana's own spec marks `deprecated: true` in
+    favor of a separate, undocumented-here Kubernetes-apiserver route — not a spec omission. RFC-6902
+    patches un-deprecate exactly the 32 operations this finding named (folders, dashboards,
+    alerting-provisioning writes); the other 32 stay excluded. Shipped as
+    `@homeflare/distilled-grafana` (0.1.0 pre-release, 0.2.0 once this PR's `minor` changeset
+    releases it), aliased onto `@distilled.cloud/grafana` the same S22 route
+    `@homeflare/distilled-netbox` established. `Grafana.Datasource`'s props/attributes/generated code
+    are unchanged (diffed operation-by-operation against the prior commit). **Still open, and not
+    this PR's scope:** no `Grafana.Folder`/`Dashboard`/`AlertRule`/`ContactPoint`/
+    `NotificationPolicy`/`MuteTiming` resource calls the newly-available operations yet — follow-up
+    PRs, no longer blocked on the SDK.
     - ⛔ **Same open gaps as `forgejo/*` and `netbox/*` above:** `read` never answers `Unowned`
       (H1), and credentials come from an explicit env var NAME at call time rather than an
       `alchemy/Auth` provider (S24) — here the house's own `grafanaCredentials(target)`, not the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.31.0",
+  "version": "0.31.2",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -107,6 +107,7 @@
   },
   "dependencies": {
     "@distilled.cloud/caddy": "npm:@homeflare/distilled-caddy@0.2.2",
+    "@distilled.cloud/grafana": "npm:@homeflare/distilled-grafana@0.2.0",
     "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
@@ -118,7 +119,6 @@
     "@distilled.cloud/discord": "1.0.0-rc.12",
     "@distilled.cloud/forgejo": "1.0.0-rc.12",
     "@distilled.cloud/google-workspace": "1.0.0-rc.12",
-    "@distilled.cloud/grafana": "1.0.0-rc.12",
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/sql-pg": "4.0.0-rc.115",
     "alchemy": "2.0.0-beta.79",

package/src/grafana/index.ts

@@ -5,11 +5,12 @@
  *   the symbols a real stack consumes; the rest of the files (resource.ts's engine, fake-grafana.ts)
  *   are internals a provider needs but a consumer should not depend on.
  *
- * ⛔ ONLY `Grafana.Datasource` SHIPS HERE. `@distilled.cloud/grafana@1.0.0-rc.12` has no folder,
- *   dashboard, alert-rule or contact-point CRUD operations — see docs/grafana.md and
- *   docs/upstream-conformance.md for the measured gap. Adding those resources now would mean
- *   hand-rolling an `HttpClient` client for them, which S23 forbids for a vendor distilled
- *   already covers in part; the right fix is upstream, in distilled, not a house workaround here.
+ * ⛔ ONLY `Grafana.Datasource` SHIPS HERE. `@distilled.cloud/grafana` (aliased onto
+ *   `@homeflare/distilled-grafana` — see docs/distilled-interim.md) now HAS folder, dashboard and
+ *   alerting-provisioning CRUD operations — the SDK-level gap docs/grafana.md and
+ *   docs/upstream-conformance.md recorded is fixed. Building `Grafana.Folder`, `Grafana.Dashboard`,
+ *   `Grafana.AlertRule` etc. on top of them is follow-up work this PR deliberately does not do —
+ *   see docs/grafana.md for what changed and what is still open.
  */
 export {
   type DatasourceAttributes,

package/src/proxmox/acl-wire.ts

@@ -0,0 +1,83 @@
+/**
+ * `Proxmox.Acl`'s wire shape: PVE's PUT form, identity, and how a live row becomes attributes.
+ * Split out of acl.ts (2026-09-24) to keep that file under the 250-line cap once the cries-wolf
+ * fix needed real space — the api-token.ts/api-token-form.ts seam, same reasoning: this file
+ * answers "what does PVE store", acl.ts answers "when has it changed" and drives the provider.
+ */
+import type * as access from '@distilled.cloud/proxmox/access';
+import { guardForm } from './constraint-guard.ts';
+import type { AclAttributes, AclProps } from './acl.ts';
+
+/** ⚠️ PVE normalises ACL paths (collapses repeated slashes, strips the trailing one, adds a leading one). */
+export const normalize = (raw: string) => `/${raw.split('/').filter(Boolean).join('/')}`;
+
+/** The write names the subject with a plural key that differs per kind; the read answers singular. */
+const SUBJECT_FIELD = { group: 'groups', token: 'tokens', user: 'users' } as const;
+
+/** The vendor endpoint every write and every constraint check runs against. */
+const ENDPOINT = 'pve:PUT /access/acl';
+
+/** The tuple PVE keys a grant by, as PUT's fields. */
+export const tuple = (props: AclProps): access.PutAccessAclRequest => ({
+  path: normalize(props.path),
+  roles: props.roleid,
+  [SUBJECT_FIELD[props.type]]: props.ugid,
+});
+
+/** Create and update are one call: the tuple plus the single mutable field. */
+export const bind = (props: AclProps): access.PutAccessAclRequest => ({
+  ...tuple(props),
+  propagate: props.propagate === false ? '0' : '1',
+});
+
+/** `guardForm` wants a plain string-valued form; distilled's request type carries `?` instead. */
+const asForm = (body: access.PutAccessAclRequest): Record<string, string> =>
+  Object.fromEntries(Object.entries(body).filter((e): e is [string, string] => e[1] !== undefined));
+
+/**
+ * ⚠️ ALWAYS PRESENCE-CHECKED. `bind`'s output IS the create form (there is no separate,
+ *   narrower update form for this family — see acl.ts's header), so the vendor's
+ *   required-parameter check is never wrong to run; the two separate create/update passes the
+ *   generic factory ran elsewhere collapse to one call here without losing coverage.
+ */
+export const guardWrite = (props: AclProps) => guardForm(ENDPOINT, asForm(bind(props)), true);
+
+/** What a change of this string means: not an edit, a different grant. */
+export const identity = (grant: Pick<AclAttributes, 'path' | 'roleid' | 'type' | 'ugid'>) =>
+  [normalize(grant.path), grant.type, grant.ugid, grant.roleid].join(' ');
+
+const find = (rows: readonly access.ListAccessAclResponseBodyItem[], props: AclProps) =>
+  rows.find(
+    (row) =>
+      row.path === normalize(props.path) &&
+      row.type === props.type &&
+      row.ugid === props.ugid &&
+      row.roleid === props.roleid,
+  );
+
+/**
+ * ⚠️ PVE answers `propagate` as 1/0 rather than true/false, and OMITS it when it carries the API
+ *   default, which is ON. distilled's generated schema types it `unknown` for the same reason.
+ */
+const propagates = (row: access.ListAccessAclResponseBodyItem) => {
+  const value = row.propagate;
+  return value === undefined || value === 1 || value === true || value === '1';
+};
+
+export const attributesOf = (
+  rows: readonly access.ListAccessAclResponseBodyItem[],
+  props: AclProps,
+): AclAttributes => {
+  const row = find(rows, props);
+  return {
+    bound: row !== undefined,
+    path: normalize(props.path),
+    propagate: row !== undefined && propagates(row),
+    roleid: props.roleid,
+    type: props.type,
+    ugid: props.ugid,
+  };
+};
+
+export const matches = (attributes: AclAttributes, props: AclProps) =>
+  attributes.bound && attributes.propagate === (props.propagate !== false);

package/src/proxmox/acl.ts

@@ -47,9 +47,15 @@ import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as access from '@distilled.cloud/proxmox/access';
 import * as Effect from 'effect/Effect';
-import { guardForm } from './constraint-guard.ts';
+import { attributesOf, bind, guardWrite, identity, matches, tuple } from './acl-wire.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
+import {
+  UNREADABLE,
+  type Unreadable,
+  readOrUnreadable,
+  unreadableWarning,
+} from './unreadable-read.ts';
 
 /** PVE's three kinds of subject. The read answers this word; the write wants its plural. */
 export type AclSubjectType = 'user' | 'group' | 'token';
@@ -91,91 +97,29 @@ export interface ProxmoxAcl extends Resource<
 
 export const ProxmoxAcl = Resource<ProxmoxAcl>('Proxmox.Acl');
 
-/** ⚠️ PVE normalises ACL paths (collapses repeated slashes, strips the trailing one, adds a leading one). */
-const normalize = (raw: string) => `/${raw.split('/').filter(Boolean).join('/')}`;
-
-/** The write names the subject with a plural key that differs per kind; the read answers singular. */
-const SUBJECT_FIELD = { group: 'groups', token: 'tokens', user: 'users' } as const;
-
-/** The vendor endpoint every write and every constraint check runs against. */
-const ENDPOINT = 'pve:PUT /access/acl';
-
-/** The tuple PVE keys a grant by, as PUT's fields. */
-const tuple = (props: AclProps): access.PutAccessAclRequest => ({
-  path: normalize(props.path),
-  roles: props.roleid,
-  [SUBJECT_FIELD[props.type]]: props.ugid,
-});
-
-/** Create and update are one call: the tuple plus the single mutable field. */
-const bind = (props: AclProps): access.PutAccessAclRequest => ({
-  ...tuple(props),
-  propagate: props.propagate === false ? '0' : '1',
-});
-
-/** `guardForm` wants a plain string-valued form; distilled's request type carries `?` instead. */
-const asForm = (body: access.PutAccessAclRequest): Record<string, string> =>
-  Object.fromEntries(Object.entries(body).filter((e): e is [string, string] => e[1] !== undefined));
-
-/**
- * ⚠️ ALWAYS PRESENCE-CHECKED. `bind`'s output IS the create form (there is no separate,
- *   narrower update form for this family — see the header), so the vendor's required-parameter
- *   check is never wrong to run; the two separate create/update passes the generic factory ran
- *   elsewhere collapse to one call here without losing coverage.
- */
-const guardWrite = (props: AclProps) => guardForm(ENDPOINT, asForm(bind(props)), true);
-
-/** What a change of this string means: not an edit, a different grant. */
-const identity = (grant: Pick<AclAttributes, 'path' | 'roleid' | 'type' | 'ugid'>) =>
-  [normalize(grant.path), grant.type, grant.ugid, grant.roleid].join(' ');
-
-const find = (rows: readonly access.ListAccessAclResponseBodyItem[], props: AclProps) =>
-  rows.find(
-    (row) =>
-      row.path === normalize(props.path) &&
-      row.type === props.type &&
-      row.ugid === props.ugid &&
-      row.roleid === props.roleid,
-  );
-
-/**
- * ⚠️ PVE answers `propagate` as 1/0 rather than true/false, and OMITS it when it carries the API
- *   default, which is ON. distilled's generated schema types it `unknown` for the same reason.
- */
-const propagates = (row: access.ListAccessAclResponseBodyItem) => {
-  const value = row.propagate;
-  return value === undefined || value === 1 || value === true || value === '1';
-};
-
-const attributesOf = (
-  rows: readonly access.ListAccessAclResponseBodyItem[],
-  props: AclProps,
-): AclAttributes => {
-  const row = find(rows, props);
-  return {
-    bound: row !== undefined,
-    path: normalize(props.path),
-    propagate: row !== undefined && propagates(row),
-    roleid: props.roleid,
-    type: props.type,
-    ugid: props.ugid,
-  };
-};
-
-const matches = (attributes: AclAttributes, props: AclProps) =>
-  attributes.bound && attributes.propagate === (props.propagate !== false);
-
 /**
  * ⛔ `readRole: 'provision'`, WITHOUT WHICH EVERY GRANT READS BACK AS ABSENT — see the header's
- *   ⛔ on filtering. `read`/`orElseSucceed` folds ANY failure (network, a genuine permission
- *   error) into "unknown"; a 200 with an empty or non-matching list is a real answer, not folded.
+ *   ⛔ on filtering.
+ * ★ `readOrUnreadable` (unreadable-read.ts) runs first: a REFUSED mint of `provision` — the
+ *   "cries wolf" bug — comes back `UNREADABLE` instead of the `undefined` a genuine, SUCCESSFUL
+ *   read (the row simply not being in the list) produces, so `diff` below can tell them apart.
+ * ⛔ NO `orElseSucceed` HERE ANY MORE — found on 2026-09-24, the SAME bug class as the credential
+ *   denial: it used to fold EVERY OTHER failure (a transport error, `PveClusterExhausted`, a
+ *   decode failure) into `undefined` too, which then read exactly like a genuine absence and
+ *   forced the same false `update`. Only a read that actually SUCCEEDS (and the grant is not in
+ *   the list it returns) may mean absent now; every other failure propagates and fails the whole
+ *   plan loudly — the engine's own contract for a failed `read`/`diff` (verify.ts's `readWithState`
+ *   already expects and reports it as `'failed'`).
  */
 const readAttributes = (props: AclProps) =>
-  runPve(props.target, 'provision', false, access.listAccessAcl({})).pipe(
-    Effect.map((rows) => attributesOf(rows, props)),
-    Effect.orElseSucceed(() => undefined),
+  readOrUnreadable(runPve(props.target, 'provision', false, access.listAccessAcl({}))).pipe(
+    Effect.map((rows) => (rows === UNREADABLE ? UNREADABLE : attributesOf(rows, props))),
   );
 
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+const dropUnreadable = (live: AclAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;
+
 export const ProxmoxAclProvider = () =>
   Provider.effect(
     ProxmoxAcl,
@@ -184,7 +128,7 @@ export const ProxmoxAclProvider = () =>
         /** ⛔ EMPTY LIKE EVERY OTHER PVE RESOURCE. Adopting every grant a human ever clicked is not adoption. */
         list: () => Effect.succeed([]),
         read: Effect.fn(function* ({ olds }) {
-          return yield* readAttributes(olds);
+          return dropUnreadable(yield* readAttributes(olds));
         }),
         /**
          * ⛔ AN IDENTITY CHANGE IS A REPLACE. Editing `roleid` (or the subject, or the path) would
@@ -201,6 +145,12 @@ export const ProxmoxAclProvider = () =>
           yield* guardWrite(news);
           if (output === undefined) return undefined;
           const live = yield* readAttributes(news);
+          // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and
+          //   force `update` on a grant that was plainly there — see unreadable-read.ts.
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.Acl', identity(news));
+            return { action: 'noop' } as const;
+          }
           return live !== undefined && matches(live, news)
             ? ({ action: 'noop' } as const)
             : ({ action: 'update' } as const);
@@ -212,12 +162,15 @@ export const ProxmoxAclProvider = () =>
          *   the gap.
          */
         reconcile: Effect.fn(function* ({ news }) {
-          const before = yield* readAttributes(news);
+          // ⚠️ `dropUnreadable`: reconcile only runs once `provision` already minted for the
+          //   write below, so `UNREADABLE` here is a near-impossible race, not the routine case
+          //   `diff` handles — treating it as "not yet bound" costs at most one redundant PUT.
+          const before = dropUnreadable(yield* readAttributes(news));
           yield* guardWrite(news);
           if (before === undefined || !matches(before, news)) {
             yield* runPve(news.target, 'provision', true, access.putAccessAcl(bind(news)));
           }
-          const after = yield* readAttributes(news);
+          const after = dropUnreadable(yield* readAttributes(news));
           if (after === undefined || !after.bound) {
             return yield* Effect.die(
               new Error(

package/src/proxmox/adopt-noop.test.ts

@@ -16,9 +16,11 @@ import { engineOver } from '../verify/fake-engine.ts';
 import { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
 import type { PbsTarget } from './credentials.ts';
 import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import { ProxmoxGroup, ProxmoxGroupProvider } from './group.ts';
 import { PbsDatastore, PbsDatastoreProvider } from './pbs-datastore.ts';
 import { ProxmoxPool, ProxmoxPoolProvider } from './pool.ts';
 import { ProxmoxSdnApply, ProxmoxSdnApplyProvider } from './sdn-apply.ts';
+import { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
 
 const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
 
@@ -54,6 +56,22 @@ const cases: readonly Case[] = [
     name: 'Proxmox.Acl (wraps the factory reconcile)',
     provider: ProxmoxAclProvider as never,
   },
+  {
+    declare: () =>
+      ProxmoxGroup('mint', { comment: 'fence', groupid: 'hf-mint', target: FAKE_TARGET }) as never,
+    live: { 'access/groups/hf-mint': { comment: 'fence', members: [] } },
+    name: 'Proxmox.Group (its own reconcile, since the distilled migration)',
+    provider: ProxmoxGroupProvider as never,
+  },
+  {
+    // ⚠️ KEY IS PERCENT-ENCODED — user.ts's own ⚠️: distilled's `{userid}` substitution encodes
+    //   the `@`, and `clusterWith` below does no decoding of `call.path`.
+    declare: () =>
+      ProxmoxUser('iac', { comment: 'x', target: FAKE_TARGET, userid: 'iac@pve' }) as never,
+    live: { 'access/users/iac%40pve': { comment: 'x', enable: 1, expire: 0 } },
+    name: 'Proxmox.User (its own reconcile, since the distilled migration)',
+    provider: ProxmoxUserProvider as never,
+  },
   {
     declare: () =>
       PbsDatastore('store1', {

package/src/proxmox/api-token-adopt.test.ts

@@ -17,10 +17,6 @@ import { engineOver } from '../verify/fake-engine.ts';
 import { type ApiTokenProps, ProxmoxApiToken, ProxmoxApiTokenProvider } from './api-token.ts';
 import { shape } from './api-token-form.ts';
 import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
-import type {
-  AccessUsersUseridTokenTokenidPostParams,
-  AccessUsersUseridTokenTokenidPutParams,
-} from './generated/pve.ts';
 
 type Live = { comment?: string; expire: number | string; privsep: number };
 
@@ -32,12 +28,19 @@ const tokens = new Map<string, Live>([
   ['access/users/svc@pve/token/lease2', { comment: 'lease', expire: '1789327175', privsep: 0 }],
 ]);
 
+/**
+ * ⚠️ `decodeURIComponent` — user.ts's own ⚠️, and it applies here too: distilled's `{userid}`/
+ *   `{tokenid}` label substitution percent-encodes `iac@pve` to `iac%40pve`, where `client.ts`'s
+ *   plain string concatenation never did. `tokens`'s keys stay literal (`@`); only the lookup
+ *   decodes, so this map does not have to be rewritten for a wire-level detail.
+ */
 const cluster = () =>
   fakePve((call: PveCall) => {
-    if (call.method === 'GET') return tokens.get(call.path);
+    const key = decodeURIComponent(call.path);
+    if (call.method === 'GET') return tokens.get(key);
     if (call.method === 'PUT') {
-      const live = tokens.get(call.path);
-      if (live !== undefined) tokens.set(call.path, { ...live, ...call.form });
+      const live = tokens.get(key);
+      if (live !== undefined) tokens.set(key, { ...live, ...call.form });
       return call.form;
     }
     return undefined;
@@ -125,14 +128,27 @@ describe('adopting a metadata-only ApiToken declaration', () => {
       expect(await engine.deploy(flipped())).toEqual({ 'iac-pve-apply': 'adopted' });
     });
     const put = fake.calls.find((call) => call.method === 'PUT');
-    expect(fake.writes()).toEqual(['PUT access/users/iac@pve/token/apply']);
+    // ⚠️ PERCENT-ENCODED — see the ⚠️ on `cluster` above.
+    expect(fake.writes()).toEqual(['PUT access/users/iac%40pve/token/apply']);
+    // ⛔ `userid`/`tokenid` DO NOT LEAK INTO THE WIRE FORM, even though `shape()` (below) must
+    //   include them for distilled's `putAccessUserToken` call — they are `T.Label()` fields,
+    //   pulled into the URL by the protocol layer and never sent in the body. MEASURED here.
     expect(put?.pairs.map(([name]) => name)).toEqual(['comment', 'expire', 'privsep']);
   });
 
-  test('the form keys typecheck against both generated PVE params, with no cast', () => {
+  // ★ THE OLD PROOF ("typechecks against the generated PVE params, no cast") is now `shape()`'s
+  //   own return type (`access.PutAccessUserTokenRequest`), checked at compile time by every
+  //   caller. This pins the one thing that is not: `userid`/`tokenid` ARE in the object `shape`
+  //   builds (distilled needs them to fill the URL), even though the wire test above proves
+  //   they never reach the actual PUT body.
+  test('shape() carries userid/tokenid for distilled, alongside the three mutable fields', () => {
     const props = propsFor('iac@pve', 'apply', { comment: 'automation' });
-    const post: AccessUsersUseridTokenTokenidPostParams = shape(props);
-    const put: AccessUsersUseridTokenTokenidPutParams = shape(props);
-    expect(post).toEqual(put);
+    expect(shape(props)).toEqual({
+      comment: 'automation',
+      expire: '0',
+      privsep: '0',
+      tokenid: 'apply',
+      userid: 'iac@pve',
+    });
   });
 });