@homeflare/alchemy 0.40.0 → 0.42.0

package/src/proxmox/lease-cache.test.ts

@@ -14,13 +14,13 @@ import * as Cache from 'effect/Cache';
 import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 import * as Exit from 'effect/Exit';
-import type { PveCredential } from './credentials.ts';
-import { type LeaseKey, makeLeases, timeToLive } from './lease-cache.ts';
+import { type PveCredential, type PveTarget, mintTier } from './credentials.ts';
+import { type LeaseKey, keyOf, makeLeases, targetForKey, timeToLive } from './lease-cache.ts';
 
 const C1: LeaseKey = {
   mount: 'proxmox-c1',
-  role: 'read',
   scheme: 'pve',
+  tier: 'read',
 };
 /** ⚠️ Same role as C1, DIFFERENT mount — the collision the key has to survive. */
 const C2: LeaseKey = { ...C1, mount: 'proxmox-c2' };
@@ -79,6 +79,61 @@ describe('how long a lease is kept', () => {
   });
 });
 
+describe('K-T1: keyOf resolves an overridden tier into the cache key (I1)', () => {
+  // ⛔ The one line the PR exists for (`tier: mintTier(target, role)` in `keyOf`) had no direct
+  //   test: revert it to `tier: role` and the rest of the suite still passes, because
+  //   `targetForKey`'s tests prove only the reconstruction half and `mintTier`'s tests prove only
+  //   the resolution function, never the composition a real `leased()` call depends on.
+  it('a plain PveTarget with no override keys on the bare role', () => {
+    const target: PveTarget = { members: [], mount: 'proxmox-tb4', scheme: 'pve' };
+    assert.equal(keyOf(target, 'read').tier, 'read');
+  });
+
+  it('a PveTarget.roles override reaches the cache key, not just a direct mint', () => {
+    const target: PveTarget = {
+      members: [],
+      mount: 'proxmox-tb4',
+      roles: { read: 'talos-provision' },
+      scheme: 'pve',
+    };
+    assert.equal(keyOf(target, 'read').tier, 'talos-provision');
+    // The unmentioned role still falls back to itself on the same target.
+    assert.equal(keyOf(target, 'provision').tier, 'provision');
+  });
+
+  it('a PbsTarget key never carries an override — the type has no roles field', () => {
+    const pbs = { api: 'https://pbs.invalid/api2/json', mount: 'pbs-c1', scheme: 'pbs' as const };
+    assert.equal(keyOf(pbs, 'read').tier, 'read');
+  });
+});
+
+describe('K-T1/M3: targetForKey round-trips the resolved tier back through mintTier', () => {
+  // ⛔ Since M3 dropped `role` from `LeaseKey`, `targetForKey` always mints a pve reconstruction
+  //   with the fixed role `'read'` — the caller's ORIGINAL role is irrelevant here, only `tier`
+  //   (already resolved by `keyOf`) has to round-trip.
+  it('a plain tier reconstructs to itself', () => {
+    const key: LeaseKey = { mount: 'proxmox-tb4', scheme: 'pve', tier: 'read' };
+    assert.equal(mintTier(targetForKey(key), 'read'), 'read');
+  });
+
+  it('an overridden tier reconstructs to the SAME tier, not the bare role', () => {
+    // ⛔ This is the exact reconstruction the cache-miss path depends on: `keyOf` resolved
+    //   `talos-provision` from the caller's real target once; `targetForKey` never sees that
+    //   target again, only this key, so it has to be able to rebuild the same answer from `tier`
+    //   alone.
+    const key: LeaseKey = { mount: 'proxmox-tb4', scheme: 'pve', tier: 'talos-provision' };
+    assert.equal(mintTier(targetForKey(key), 'read'), 'talos-provision');
+  });
+
+  it('a pbs key never carries an override through', () => {
+    const key: LeaseKey = { mount: 'pbs-c1', scheme: 'pbs', tier: 'provision' };
+    assert.equal(mintTier(targetForKey(key), 'provision'), 'provision');
+  });
+});
+
+// ⚠️ `mintForKey`'s own request-path behavior is exercised in lease-cache-mint.test.ts, against a
+//   fake OpenBao server — not hand-reproduced here.
+
 describe('lease cache under concurrency', () => {
   it('mints once for many concurrent callers, and serves the next from the cache', async () => {
     const mint = countingMint(() => cred('hf-read@pve!a', 3600));
@@ -123,7 +178,7 @@ describe('lease cache under concurrency', () => {
     assert.equal(mint.calls(), 2);
   });
 
-  it('does not serve one cluster the credential of another with the same mount and role', async () => {
+  it('does not serve one cluster the credential of another with the same tier', async () => {
     const mint = countingMint((call) => cred(`hf-read@pve!${String(call)}`, 3600));
     const [c1, c2] = await Effect.runPromise(
       Effect.gen(function* () {
@@ -137,8 +192,8 @@ describe('lease cache under concurrency', () => {
 
   it('shares one lease across two members of the same cluster mount', async () => {
     const mint = countingMint((call) => cred(`hf-read@pve!${String(call)}`, 3600));
-    const NODE_B: LeaseKey = { mount: 'proxmox-c1', role: 'read', scheme: 'pve' };
-    const NODE_C: LeaseKey = { mount: 'proxmox-c1', role: 'read', scheme: 'pve' };
+    const NODE_B: LeaseKey = { mount: 'proxmox-c1', scheme: 'pve', tier: 'read' };
+    const NODE_C: LeaseKey = { mount: 'proxmox-c1', scheme: 'pve', tier: 'read' };
     await Effect.runPromise(
       Effect.gen(function* () {
         const leases = yield* makeLeases(mint.mintFor);
@@ -151,7 +206,7 @@ describe('lease cache under concurrency', () => {
 
   it('keeps read and provision apart', async () => {
     const mint = countingMint((call) => cred(`hf@pve!${String(call)}`, 3600));
-    const PROVISION: LeaseKey = { ...C1, role: 'provision' };
+    const PROVISION: LeaseKey = { ...C1, tier: 'provision' };
     const [read, provision] = await Effect.runPromise(
       Effect.gen(function* () {
         const leases = yield* makeLeases(mint.mintFor);
@@ -160,4 +215,25 @@ describe('lease cache under concurrency', () => {
     );
     assert.notEqual(read.tokenId, provision.tokenId);
   });
+
+  // ⛔ K-T1's own reason `tier` joined the key: two consumers on the SAME mount/scheme but
+  //   DIFFERENT `PveTarget.roles` overrides would otherwise collide into one cache entry and hand
+  //   each other's credential to the wrong caller. M3 dropped `role` from the key entirely (it
+  //   was always redundant with `tier`), which this test still exercises unchanged.
+  it('keeps two different tier overrides of the same mount/scheme apart', async () => {
+    const mint = countingMint((call) => cred(`hf@pve!${String(call)}`, 3600));
+    const DEFAULT_READ: LeaseKey = { mount: 'proxmox-tb4', scheme: 'pve', tier: 'read' };
+    const OVERRIDDEN_READ: LeaseKey = { ...DEFAULT_READ, tier: 'talos-provision' };
+    const [plain, overridden] = await Effect.runPromise(
+      Effect.gen(function* () {
+        const leases = yield* makeLeases(mint.mintFor);
+        return [
+          yield* Cache.get(leases, DEFAULT_READ),
+          yield* Cache.get(leases, OVERRIDDEN_READ),
+        ] as const;
+      }),
+    );
+    assert.notEqual(plain.tokenId, overridden.tokenId);
+    assert.equal(mint.calls(), 2);
+  });
 });

package/src/proxmox/lease-cache.ts

@@ -47,7 +47,13 @@ import * as Cache from 'effect/Cache';
 import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 import * as Exit from 'effect/Exit';
-import { type ApiTarget, type PveCredential, type PveRole } from './credentials.ts';
+import {
+  type ApiTarget,
+  type BaoEnvironment,
+  type PveCredential,
+  type PveRole,
+  mintTier,
+} from './credentials.ts';
 import { mint } from './mint.ts';
 
 /**
@@ -66,24 +72,49 @@ const REMINT_MARGIN_SECONDS = 60;
 /**
  * What a credential is cached under.
  *
- * ⛔ KEYED ON THE OPENBAO MOUNT AND ROLE, NOT ON A MEMBER HOSTNAME. A PVE API token is
- *   cluster-wide — `user.cfg` is replicated — so node-b, node-c and node-d share one credential. Keying on
- *   `api` would mint three identical tokens when failover rotates members.
+ * ⛔ KEYED ON THE OPENBAO MOUNT AND TIER, NOT ON A MEMBER HOSTNAME OR ON `role` (M3, red team on
+ *   K-T1). A PVE API token is cluster-wide — `user.cfg` is replicated — so node-b, node-c and
+ *   node-d share one credential. Keying on `api` would mint three identical tokens when failover
+ *   rotates members. `role` USED to be part of this key too, but the minted credential depends
+ *   only on `(mount, scheme, tier)` — `role` only ever fed `mintTier` to re-derive the tier the
+ *   key already carries — so `roles: { read: 'x', provision: 'x' }` (one tier for both roles, the
+ *   shape `docs/credentials.md` itself recommends) used to open TWO cache entries and mint TWO
+ *   byte-for-byte interchangeable tokens for what is provably one credential. Dropping `role`
+ *   collapses that back to one entry without changing the default case, where `tier === role`
+ *   already.
  * ★ THE MOUNT CANNOT COLLIDE ACROSS CLUSTERS: `proxmox-c1`, `proxmox-c2` and `pbs-c1` are
  *   distinct OpenBao mounts with distinct policies; two estates never share a mount name.
  * ★ A PLAIN OBJECT IS A SAFE KEY BECAUSE EFFECT COMPARES KEYS STRUCTURALLY — two separately built
  *   literals with the same fields are one entry, which the probe above measured.
+ *
+ * ⛔ `tier` IS THE KEY, NOT `role` (K-T1). `targetForKey` below has to RECONSTRUCT a target from
+ *   the key alone (it does not keep the caller's original `ApiTarget` around), and a
+ *   `PveTarget.roles` override lives on THAT original target, not on `role` — so without `tier`
+ *   in the key, every `leased()` call for an overridden role would resolve its override once at
+ *   the first `keyOf`, then reuse whatever `targetForKey` happens to reconstruct on a cache miss,
+ *   and TWO DIFFERENT overrides sharing one `{mount, scheme}` (e.g. one consumer's default `read`
+ *   tier and another's `roles: {read: 'x'}` override, same mount) would collide into ONE cache
+ *   entry and hand each other's credential to the wrong caller. Resolving the tier at `keyOf` —
+ *   where the real target is still in hand — and keying on it closes that: two different tiers
+ *   are two different entries, always.
  */
 export type LeaseKey = {
   readonly mount: string;
-  readonly role: PveRole;
   readonly scheme: ApiTarget['scheme'];
+  readonly tier: string;
 };
 
-const keyOf = (target: ApiTarget, role: PveRole): LeaseKey => ({
+/**
+ * ⚠️ EXPORTED FOR THE TEST (I1, red team on K-T1). This is the one line the whole PR exists
+ *   for — `tier: mintTier(target, role)` is what makes an overridden `PveTarget.roles` reach the
+ *   cached path at all. Nothing else in this file's test suite calls `keyOf` or `leased`
+ *   directly, so without this export a regression here (e.g. reverting to `tier: role`) passed
+ *   the whole suite silently.
+ */
+export const keyOf = (target: ApiTarget, role: PveRole): LeaseKey => ({
   mount: target.mount,
-  role,
   scheme: target.scheme,
+  tier: mintTier(target, role),
 });
 
 /**
@@ -115,12 +146,45 @@ export const timeToLive = (exit: Exit.Exit<PveCredential, unknown>): Duration.Du
 export const makeLeases = <E, R>(mintFor: (key: LeaseKey) => Effect.Effect<PveCredential, E, R>) =>
   Cache.makeWith(mintFor, { capacity: 64, requireServicesAt: 'lookup', timeToLive });
 
-const targetForKey = (key: LeaseKey): ApiTarget =>
+/**
+ * ⛔ CARRIES `key.tier` BACK IN AS A `roles` OVERRIDE (K-T1), SO `mint`'S OWN `mintTier` CALL
+ *   REPRODUCES THE SAME TIER `keyOf` ALREADY RESOLVED. This target is synthetic — it is never the
+ *   caller's real `PveTarget` (`members`/`api` are throwaway placeholders `mint` never reads) —
+ *   and, since M3 dropped `role` from `LeaseKey`, it no longer even knows which semantic role
+ *   produced `key.tier`. It doesn't need to: `roles: { read: key.tier }` plus always minting with
+ *   the fixed role `'read'` (below) makes `mintTier(targetForKey(key), 'read') === key.tier`
+ *   unconditionally, because `mintTier` only ever consults the ONE role it's called with. Which
+ *   role the ORIGINAL caller asked for is irrelevant here — `keyOf` already folded that into
+ *   `key.tier` before this function ever sees the key.
+ * ⚠️ THE PBS BRANCH MINTS WITH `key.tier` ITSELF AS THE ROLE, NOT `'read'`. A `PbsTarget` has no
+ *   `roles` override (see `credentials.ts`'s ⛔ on `PbsTarget`), so `mintTier` for `scheme:'pbs'`
+ *   always returns its `role` argument unchanged — meaning `key.tier` for a PBS key IS the literal
+ *   role name (`'read'`/`'provision'`) `keyOf` recorded. Passing anything else here would ask
+ *   OpenBao for the wrong tier.
+ * ⚠️ EXPORTED FOR THE TEST, which checks that round trip directly rather than only through the
+ *   cache's externally visible behaviour.
+ */
+export const targetForKey = (key: LeaseKey): ApiTarget =>
   key.scheme === 'pbs'
     ? { api: 'https://pbs.invalid/api2/json', mount: key.mount, scheme: 'pbs' }
-    : { members: [], mount: key.mount, scheme: 'pve' };
+    : { members: [], mount: key.mount, roles: { read: key.tier }, scheme: 'pve' };
+
+/**
+ * ⚠️ EXPORTED FOR THE TEST (second red-team pass on K-T1). `targetForKey`'s own tests call
+ *   `mintTier(targetForKey(key), 'read')` to check the round trip, which hand-reproduces this
+ *   function's fixed choice of `'read'` as the pve mint role rather than exercising it — change
+ *   that choice here and those tests keep passing while a live cache miss mints the wrong tier.
+ *   Testing this function directly (against a fake OpenBao) pins the choice itself.
+ *
+ * ⚠️ `env` DEFAULTS TO `process.env`, SAME AS `mint` ITSELF (credentials.ts) — the cache's real
+ *   caller below (`Effect.runSync(makeLeases(mintForKey))`) always calls this with one argument,
+ *   so the default is what production runs on. The parameter exists only so the test can pass a
+ *   fake OpenBao's address without touching the real environment.
+ */
+export const mintForKey = (key: LeaseKey, env: BaoEnvironment = process.env) =>
+  mint(targetForKey(key), key.scheme === 'pbs' ? (key.tier as PveRole) : 'read', env);
 
-const leases = Effect.runSync(makeLeases((key) => mint(targetForKey(key), key.role)));
+const leases = Effect.runSync(makeLeases(mintForKey));
 
 /**
  * A credential for `role` on `target`: a still-valid lease when one is kept, one shared mint when

package/src/proxmox/mint.ts

@@ -1,5 +1,5 @@
 /**
- * Minting one PVE/PBS credential from OpenBao: `GET /v1/<mount>/creds/<role>`, alive for five
+ * Minting one PVE/PBS credential from OpenBao: `GET /v1/<mount>/creds/<tier>`, alive for five
  * minutes. Split out of `credentials.ts` (2026-09-24) to keep that file's TYPES under the
  * 250-line cap once `PveCredentialDenied`'s catchers needed a real header there; the reasoning
  * for WHY the estate mints rather than stores a token is still credentials.ts's own header.
@@ -14,6 +14,7 @@ import * as Headers from 'effect/unstable/http/Headers';
 import * as HttpClient from 'effect/unstable/http/HttpClient';
 import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
 import { PveCredentialDenied } from './credential-errors.ts';
+import { mintTier } from './credentials.ts';
 import type { ApiTarget, BaoEnvironment, PveCredential, PveRole } from './credentials.ts';
 
 /** openbao v2.6.2 api/env.go:22-34 — a present BAO_* wins, even empty; else its VAULT_* twin. */
@@ -21,7 +22,9 @@ const baoVariable = (env: BaoEnvironment, name: string) =>
   env[`BAO_${name}`] ?? env[`VAULT_${name}`] ?? '';
 
 /**
- * Mint one credential for `role`: `GET /v1/<mount>/creds/<role>` on OpenBao's HTTP API.
+ * Mint one credential for `role`: `GET /v1/<mount>/creds/<tier>` on OpenBao's HTTP API, where
+ * `tier` is `mintTier(target, role)` (credentials.ts) — `role` itself unless `target.roles`
+ * overrides it (K-T1).
  *
  * 🔴 IT SHELLED OUT TO `bao read -format=json` UNTIL 2026-09-14. The case for the CLI was that one
  *   client could not disagree with `bao kv get` about what this machine may do. <estate>/openbao then
@@ -46,7 +49,11 @@ const baoVariable = (env: BaoEnvironment, name: string) =>
  */
 export const mint = (target: ApiTarget, role: PveRole, env: BaoEnvironment = process.env) =>
   Effect.gen(function* () {
-    const path = `${target.mount}/creds/${role}`;
+    // ⛔ THE ONE PLACE A `PveRole` BECOMES A TIER NAME. `mintTier` (credentials.ts) reads
+    //   `target.roles` when the target overrides it; every other line in this function uses
+    //   `tier`, never `role`, for anything that reaches OpenBao or an error message.
+    const tier = mintTier(target, role);
+    const path = `${target.mount}/creds/${tier}`;
     // ⛔ METHOD, PATH AND OpenBao's `errors` ONLY — never a header (the token), never a success
     //   body (the credential is IN it, so echoing it would print the secret into a log).
     const refuse = (status: number, detail: string) =>
@@ -125,7 +132,7 @@ export const mint = (target: ApiTarget, role: PveRole, env: BaoEnvironment = pro
        *   so it is the one signal trusted here.
        */
       if (status === 403 && isOpenBaoBody) {
-        return yield* Effect.fail(new PveCredentialDenied({ detail, mount: target.mount, role }));
+        return yield* Effect.fail(new PveCredentialDenied({ detail, mount: target.mount, tier }));
       }
       return yield* Effect.fail(refuse(status, detail || '(no errors given)'));
     }
@@ -135,7 +142,7 @@ export const mint = (target: ApiTarget, role: PveRole, env: BaoEnvironment = pro
       // ⛔ REFUSE RATHER THAN RETURN A HALF CREDENTIAL, and again WITHOUT quoting the body.
       return yield* Effect.fail(
         new Error(
-          `${target.mount}/creds/${role} returned no token_id/secret. Either this approle lacks ` +
+          `${target.mount}/creds/${tier} returned no token_id/secret. Either this approle lacks ` +
             `the grant, or the mount is not ${target.mount}. Say which mount and role you needed ` +
             `than falling back to a stored credential -- every stored PVE token is read-only.`,
         ),

package/src/proxmox/node-network.ts

@@ -94,6 +94,7 @@ import {
 } from './node-network-wire.ts';
 import type { NodeNetworkAttributes } from './node-network-wire.ts';
 import { runPve } from './distilled-pve.ts';
+import { mintTier } from './credentials.ts';
 import { type PveRequirements } from './resource-spec.ts';
 import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
 
@@ -173,7 +174,12 @@ export const ProxmoxNodeNetworkProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused mint used to fall into `undefined` and force `update`
           //   on an interface that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.NodeNetwork', `${news.node}/${news.iface}`);
+            yield* unreadableWarning(
+              'Proxmox.NodeNetwork',
+              `${news.node}/${news.iface}`,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
             return { action: 'noop' } as const;
           }
           if (live === undefined) {

package/src/proxmox/role.ts

@@ -64,6 +64,7 @@ import {
 } from './role-wire.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
+import { mintTier } from './credentials.ts';
 import {
   UNREADABLE,
   type Unreadable,
@@ -151,7 +152,12 @@ export const ProxmoxRoleProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
           //   `update` on a role that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.Role', news.roleid);
+            yield* unreadableWarning(
+              'Proxmox.Role',
+              news.roleid,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
             return { action: 'noop' } as const;
           }
           if (live === undefined) {

package/src/proxmox/storage-form.ts

@@ -4,7 +4,10 @@
  * both files under the 250-line cap — the api-token.ts/api-token-form.ts seam, same reasoning.
  */
 import type * as storage from '@distilled.cloud/proxmox/storage';
+import { sharedAccepted } from './storage-plugin-options.ts';
 import type { StorageProps } from './storage.ts';
+import { changedProps } from './storage-wire.ts';
+import type { StorageAttributes } from './storage-wire.ts';
 import { flag } from './values.ts';
 
 export const STORAGE_CREATE = 'pve:POST /storage';
@@ -75,6 +78,16 @@ const locatorForm = (locator: StorageLocator | undefined) =>
 const underscored = (form: Record<string, string>): Record<string, string> =>
   Object.fromEntries(Object.entries(form).map(([key, value]) => [key.replaceAll('-', '_'), value]));
 
+/**
+ * The 7 fields `mutable()` reads, narrowed out of `StorageProps` — not `StorageProps` itself, so
+ * a partial diff (storage-wire.ts's `changedProps`, which carries none of `storage`/`locator`/
+ * `target`) can satisfy this type directly.
+ */
+export type MutableFields = Pick<
+  StorageProps,
+  'comment' | 'content' | 'disable' | 'nodes' | 'preallocation' | 'prune-backups' | 'shared'
+>;
+
 /**
  * The mutable half, for create and update alike.
  *
@@ -93,15 +106,21 @@ const underscored = (form: Record<string, string>): Record<string, string> =>
  *   vendor-constraint table is keyed by PVE's own names (`underscored`'s own header has the
  *   measured evidence). `toDistilledCreate`/`toDistilledUpdate` translate a COPY for the actual
  *   SDK call; this function and its callers never see the underscored form.
+ *
+ * ⛔ `shared` IS GATED BY TYPE — `sharedAccepted` (storage-plugin-options.ts, vendor-cited): most
+ *   plugins refuse it outright ("unexpected property 'shared'", the measured bug this gate
+ *   fixes), so it is dropped here regardless of what the caller passed, for both create and
+ *   update alike — `type` is always required precisely so this gate can run on the FULL declared
+ *   set at create time too, not only on a partial update diff.
  */
-const mutable = (props: StorageProps) => ({
+const mutable = (type: string, props: MutableFields) => ({
   ...field('comment', props.comment),
   ...field('content', props.content),
   ...field('disable', flag(props.disable)),
   ...field('nodes', props.nodes),
   ...field('preallocation', props.preallocation),
   ...field('prune-backups', props['prune-backups']),
-  ...field('shared', flag(props.shared)),
+  ...(sharedAccepted(type) ? field('shared', flag(props.shared)) : {}),
 });
 
 /**
@@ -113,7 +132,7 @@ const mutable = (props: StorageProps) => ({
  */
 export const createForm = (props: StorageProps): Record<string, string> => ({
   ...locatorForm(props.locator),
-  ...mutable(props),
+  ...mutable(props.type, props),
   storage: props.storage,
   type: props.type,
 });
@@ -123,9 +142,23 @@ export const createForm = (props: StorageProps): Record<string, string> => ({
  *   (`PutStorageRequest` has no `type`, and the plugin locator fields it does carry are for a
  *   different purpose: moving an existing volume, not re-pointing the definition), and comparing
  *   either could only plan an update that no write can apply: a plan that reports work forever.
+ *
+ * ★ PARTIAL ON A KNOWN LIVE OBJECT — THE FIX FOR THE MEASURED BUG. `live === undefined` means
+ *   there is no live row to diff against yet (`diff()`'s own early sanity check, run before any
+ *   read; and the "about to create" branch in `reconcile()`) and this returns the FULL declared
+ *   set, same as before this change. Once `live` is a real read, only `changedProps`
+ *   (storage-wire.ts) — the declared fields that actually differ from what PVE just reported —
+ *   reach the wire. Before this, `reconcile` PUT the full declared set whenever ANYTHING
+ *   differed, so a declared `shared` that already MATCHED live still rode along on every update;
+ *   for `storage-cephfs-tb4` (`content` was the only real drift, measured 2026-09-27) that meant
+ *   sending `shared` to a plugin whose own `options()` never accepts it (storage-plugin-options.ts
+ *   has the vendor citation), and PVE answered `unexpected property 'shared'`.
  */
-export const updateForm = (props: StorageProps): Record<string, string> => ({
-  ...mutable(props),
+export const updateForm = (
+  props: StorageProps,
+  live: StorageAttributes | undefined,
+): Record<string, string> => ({
+  ...mutable(props.type, live === undefined ? props : changedProps(live, props)),
   storage: props.storage,
 });
 
@@ -139,6 +172,13 @@ export const updateForm = (props: StorageProps): Record<string, string> => ({
 export const toDistilledCreate = (props: StorageProps): storage.CreateStorageRequest =>
   underscored(createForm(props)) as unknown as storage.CreateStorageRequest;
 
-/** The actual `putStorage` call body — `updateForm`, translated once. See `toDistilledCreate`. */
-export const toDistilledUpdate = (props: StorageProps): storage.PutStorageRequest =>
-  underscored(updateForm(props)) as unknown as storage.PutStorageRequest;
+/**
+ * The actual `putStorage` call body — translated once. See `toDistilledCreate`.
+ * ⚠️ TAKES THE ALREADY-BUILT FORM, NOT `props`+`live` — storage.ts's `reconcile` computes
+ *   `updateForm(news, before)` exactly ONCE and passes that SAME object here and to `guardWrite`,
+ *   so the vendor-constraint check and the wire body can never diverge. Two independent calls to
+ *   `updateForm`, each running its own `changedProps`, would still agree today, but "the guard
+ *   checks what is actually sent" (the house rule this fix follows) should not depend on that.
+ */
+export const toDistilledUpdate = (form: Record<string, string>): storage.PutStorageRequest =>
+  underscored(form) as unknown as storage.PutStorageRequest;

package/src/proxmox/storage-plugin-options.ts

@@ -0,0 +1,45 @@
+/**
+ * Which PVE storage plugin TYPES accept the `shared` property on write (create or update) — from
+ * each plugin's own `options()` in vendor source, NOT the generic combined property list
+ * `pve-apidoc` documentation carries (storage.ts's own header has that gap: apidoc.js merges
+ * every plugin's fields into one flat list for display, so `shared` LOOKS like a plain valid
+ * property of PUT /storage/{storage} there — `generated/pve/storage.ts`'s own
+ * `StorageStoragePutParams.shared` came from exactly that merged list, and so did the constraint
+ * codegen's own inclusion of `shared` as a recognized wire field). The check PVE actually runs is
+ * PER STORAGE TYPE, against that concrete plugin's own `options()` accepted-key set
+ * (PVE::SectionConfig) — a key the plugin never names is refused outright, which is why a cephfs
+ * PUT carrying `shared` answers `unexpected property 'shared'` even though the apidoc schema and
+ * the generated wire types both carry the field.
+ *
+ * MEASURED against github.com/proxmox/pve-storage (the official read-only GitHub mirror of
+ * git.proxmox.com/pve-storage.git), branch `master`, read 2026-09-27 — each plugin's own
+ * `sub options` block. Extended 2026-09-27 (PR 314's own red team) to cover the five types the
+ * first pass left unverified rather than guessed at; only these two lists moved:
+ *
+ *   accepts `shared` (`shared => { optional => 1 }`):
+ *     DirPlugin.pm:85, LVMPlugin.pm:453, BTRFSPlugin.pm:69, ESXiPlugin.pm:52
+ *
+ *   `shared` is ABSENT from `options()` entirely — PVE's per-type accepted-key check refuses it
+ *   on both create and update, whatever the combined apidoc schema shows:
+ *     CephFSPlugin.pm, RBDPlugin.pm, ZFSPoolPlugin.pm, LvmThinPlugin.pm, NFSPlugin.pm,
+ *     CIFSPlugin.pm, PBSPlugin.pm, ISCSIPlugin.pm, ISCSIDirectPlugin.pm, ZFSPlugin.pm (the remote
+ *     ZFS-over-iSCSI plugin, distinct from `zfspool`)
+ *
+ * `storage-cephfs-tb4`'s PUT failure (measured 2026-09-27, `bun run deploy`,
+ * `InternalServerError: update storage failed: unexpected property 'shared'`) is exactly this:
+ * `cephfs` has no `shared` in its own `options()`, so the base class's generic `shared` property
+ * (`PVE::Storage::Plugin`'s `$defaultData->{propertyList}`: `type => 'boolean', optional => 1`,
+ * no `fixed`) is never in the accepted set for that plugin, whether or not the declared value
+ * would have matched what PVE already has.
+ *
+ * ⚠️ STILL NOT EXHAUSTIVE. Every PVE plugin type is now checked against vendor source EXCEPT
+ *   whatever ships after this file was last read — `sharedAccepted` treats an unrecognized type
+ *   as NOT accepting `shared`, the safe default: a wrongly-excluded type just never sends a
+ *   declared `shared` (storage-form.ts's `mutable`) and, if the declared value actually disagrees
+ *   with what PVE reports, the plan dies loud rather than lying `noop` (storage-wire.ts's
+ *   `matches`) — it does not risk a second `unexpected property` 500. Read a new plugin's own
+ *   `options()` on github.com/proxmox/pve-storage before adding it to either list.
+ */
+const SHARED_ACCEPTED_TYPES: ReadonlySet<string> = new Set(['dir', 'lvm', 'btrfs', 'esxi']);
+
+export const sharedAccepted = (type: string): boolean => SHARED_ACCEPTED_TYPES.has(type);