@homeflare/alchemy 0.40.0 → 0.41.0

package/src/opnsense/alias.test.ts

@@ -16,6 +16,7 @@ import { spec } from './alias.ts';
 import { fakeFailure, fakeOpnsense, fakeOpnsenseLayer, getOnlyOrFail } from './fake-opnsense.ts';
 import type { OpnsenseWriteRefused } from './policy.ts';
 import { opnsenseOperations } from './resource.ts';
+import { optionMap } from './wire.ts';
 
 /** `Effect.flip`'s promise resolves to the union of every error this spec can raise; every
  * refusal test below is asserting specifically on the `OpnsenseWriteRefused` member. */
@@ -30,15 +31,17 @@ const PROPS: AliasProps = {
   uuid: UUID,
 };
 
-const liveItem = (overrides: Partial<alias.AliasItem> = {}): alias.AliasItem => ({
-  content: '10.20.10.1',
+// `liveItem` builds a `ModelAliasReadItem` — the WHOLE-MODEL `get()`'s read-shaped item, whose
+// `content`/`type` decode as option maps, not strings (OPNSENSE-2 — see alias-form.ts).
+const liveItem = (overrides: Partial<alias.ModelAliasReadItem> = {}): alias.ModelAliasReadItem => ({
+  content: optionMap('10.20.10.1'),
   enabled: '1',
   name: 'homeflare_edge',
-  type: 'host',
+  type: optionMap('host'),
   ...overrides,
 });
 
-const getResponse = (items: Record<string, alias.AliasItem>) =>
+const getResponse = (items: Record<string, alias.ModelAliasReadItem>) =>
   Response.json({ alias: { aliases: { alias: items } } });
 
 describe('Opnsense.Firewall.Alias spec.fetchLive', () => {
@@ -126,7 +129,9 @@ describe('opnsenseOperations(spec).diff', () => {
   });
 
   test('update when live content drifted from the declaration — never from a read error', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ content: '10.20.10.9' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ content: optionMap('10.20.10.9') }) }),
+    );
     const result = await Effect.runPromise(
       opnsenseOperations(spec)
         .diff(PROPS, attributesOf(UUID, liveItem()))
@@ -138,7 +143,9 @@ describe('opnsenseOperations(spec).diff', () => {
 
 describe('opnsenseOperations(spec).reconcile and destroy — the read-only policy', () => {
   test('reconcile observes with one GET, then refuses — never a write', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ content: 'drifted' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ content: optionMap('drifted') }) }),
+    );
     const failure = asRefusal(
       await Effect.runPromise(
         Effect.flip(

package/src/opnsense/alias.ts

@@ -3,15 +3,16 @@
  * READ-ONLY BY DESIGN — see policy.ts's header. `reconcile`/`delete` always refuse.
  *
  * ★ READ GOES THROUGH `get()`, NEVER `getItem`/`searchItem`. `get()` (`firewall_alias.ts#get`)
- *   returns the WHOLE model tree — `{ alias: { aliases: { alias: { <uuid>: AliasItem, ... } } } }`
- *   — so finding one item by uuid is an object-key lookup, not a request the vendor could answer
- *   ambiguously. That sidesteps two real gaps in this early SDK, both measured against the
- *   generated `firewall_alias.ts`: (1) there is no per-item `getAlias` operation at all — only
- *   `get` (whole model) and `searchAlias` (paginated, see below) exist; (2) `firewall_category.ts`
- *   and `firewall_group.ts` DO export a `getCategory`/`getGroup`, but their generated request
- *   schema carries no `uuid` path parameter (`GetCategoryRequest`/`GetGroupRequest` are both
- *   `S.Struct({})` against a `uri` with no `{uuid}` placeholder) — a generation gap, not a design
- *   choice, so this family does not rely on them for any of the three resources, uniformly.
+ *   returns the WHOLE model tree — `{ alias: { aliases: { alias: { <uuid>: ModelAliasReadItem,
+ *   ... } } } }` — so finding one item by uuid is an object-key lookup, not a request the vendor
+ *   could answer ambiguously. `Alias` has no per-item `getAlias` operation at all (`getItemAction`
+ *   decorates its result — see the distilled clone's package README) — only `get` (whole model)
+ *   and `searchAlias` (paginated, see below) exist, so this family's whole-model read is the only
+ *   option here (unlike Category/Group, whose `getCategory`/`getGroup` per-item operations now
+ *   exist correctly — OPNSENSE-1 — but this file still uses `get()` uniformly across the three
+ *   resources; switching Category/Group to their per-item operation is a separate, later PR).
+ *   `ModelAliasReadItem`'s list-shaped fields (`type`/`interface`/`proto`/`categories`) decode as
+ *   option maps, not strings (OPNSENSE-2) — see `alias-form.ts`'s `attributesOf`.
  *
  * ⛔ NOT `searchAlias`. It is POST-shaped (a read, per OPNsense's own MVC convention — see the
  *   family's docs page) and paginated with no typed limit/offset the generated request schema
@@ -87,7 +88,12 @@ export const isOpnsenseFirewallAlias = (value: unknown): value is OpnsenseFirewa
   (value as { Type?: unknown }).Type === 'Opnsense.Firewall.Alias';
 
 /** Exported for direct testing against `fake-opnsense.ts` — the same seam `../discord/*.ts` uses. */
-export const spec: OpnsenseSpec<AliasProps, Alias.AliasItem, AliasAttributes, OpnsenseOpError> = {
+export const spec: OpnsenseSpec<
+  AliasProps,
+  Alias.ModelAliasReadItem,
+  AliasAttributes,
+  OpnsenseOpError
+> = {
   attributes: attributesOf,
   fetchLive: (props) =>
     Alias.get({}).pipe(Effect.map((res) => res.alias?.aliases?.alias?.[props.uuid])),

package/src/opnsense/group-form.test.ts

@@ -1,16 +1,20 @@
 /**
- * `group-form.ts`'s pure functions against literal `GroupItem` fixtures — no network.
+ * `group-form.ts`'s pure functions against literal `ModelIfgroupentryReadItem` fixtures (the
+ * WHOLE-MODEL `get()`'s read-shaped item — `members` is an option map, OPNSENSE-2) — no network.
  */
 import { describe, expect, test } from 'bun:test';
 import type * as group from '@distilled.cloud/opnsense/firewall_group';
 import { attributesOf, matches } from './group-form.ts';
 import type { GroupProps } from './group.ts';
+import { optionMap } from './wire.ts';
 
 const UUID = '33333333-3333-3333-3333-333333333333';
 
-const liveGroup = (overrides: Partial<group.GroupItem> = {}): group.GroupItem => ({
+const liveGroup = (
+  overrides: Partial<group.ModelIfgroupentryReadItem> = {},
+): group.ModelIfgroupentryReadItem => ({
   ifname: 'IOT_DEVICES',
-  members: 'opt1,opt2',
+  members: optionMap('opt1', 'opt2'),
   sequence: '1',
   ...overrides,
 });
@@ -27,8 +31,8 @@ describe('group-form attributesOf', () => {
     });
   });
 
-  test('members are split, sorted and deduplicated', () => {
-    const live = liveGroup({ members: 'opt2,opt1,opt1' });
+  test('members are the selected keys, sorted and deduplicated', () => {
+    const live = liveGroup({ members: optionMap('opt2', 'opt1') });
     expect(attributesOf(UUID, live).members).toEqual(['opt1', 'opt2']);
   });
 
@@ -50,13 +54,13 @@ describe('group-form matches', () => {
   });
 
   test('member-list order alone is not drift', () => {
-    const live = attributesOf(UUID, liveGroup({ members: 'opt2,opt1' }));
+    const live = attributesOf(UUID, liveGroup({ members: optionMap('opt2', 'opt1') }));
     const declared: GroupProps = { ...props, members: ['opt1', 'opt2'] };
     expect(matches(live, declared)).toBe(true);
   });
 
   test('a removed member is drift', () => {
-    const live = attributesOf(UUID, liveGroup({ members: 'opt1' }));
+    const live = attributesOf(UUID, liveGroup({ members: optionMap('opt1') }));
     expect(matches(live, props)).toBe(false);
   });
 });
@@ -65,7 +69,7 @@ describe('propsFromLive round-trip', () => {
   test('the props it returns plan noop against the exact live object they came from', () => {
     const live = liveGroup({
       descr: 'IoT VLANs',
-      members: 'opt3,opt1,opt2',
+      members: optionMap('opt3', 'opt1', 'opt2'),
       nogroup: '1',
       sequence: '5',
     });

package/src/opnsense/group-form.ts

@@ -5,13 +5,22 @@
  */
 import type { GroupAttributes, GroupProps } from './group.ts';
 import type * as group from '@distilled.cloud/opnsense/firewall_group';
-import { bool01, csvSet, csvSetOf, numField } from './wire.ts';
+import { bool01, csvSetOf, numField, selectedOf } from './wire.ts';
 
-/** ★ Attributes and the declaration renderer are one function — see alias-form.ts's header note. */
-export const attributesOf = (uuid: string, live: group.GroupItem): GroupAttributes => ({
+/**
+ * ★ Attributes and the declaration renderer are one function — see alias-form.ts's header note.
+ *
+ * `live` is `ModelIfgroupentryReadItem` (the WHOLE-MODEL `get()`'s read-shaped item), not
+ * `GroupItem` — `members` (`.\InterfaceField`, `Multiple="Y"`) decodes as an option map, not a
+ * comma string (OPNSENSE-2; see wire.ts's module doc).
+ */
+export const attributesOf = (
+  uuid: string,
+  live: group.ModelIfgroupentryReadItem,
+): GroupAttributes => ({
   description: live.descr ?? '',
   ifname: live.ifname,
-  members: csvSet(live.members),
+  members: selectedOf(live.members),
   nogroup: bool01(live.nogroup, false),
   sequence: numField(live.sequence, 0),
   uuid,

package/src/opnsense/group.test.ts

@@ -12,6 +12,7 @@ import { spec } from './group.ts';
 import { fakeFailure, fakeOpnsense, fakeOpnsenseLayer, getOnlyOrFail } from './fake-opnsense.ts';
 import type { OpnsenseWriteRefused } from './policy.ts';
 import { opnsenseOperations } from './resource.ts';
+import { optionMap } from './wire.ts';
 
 const asRefusal = (value: unknown) => value as OpnsenseWriteRefused;
 
@@ -24,14 +25,18 @@ const PROPS: GroupProps = {
   uuid: UUID,
 };
 
-const liveItem = (overrides: Partial<group.GroupItem> = {}): group.GroupItem => ({
+// `liveItem` builds a `ModelIfgroupentryReadItem` — the WHOLE-MODEL `get()`'s read-shaped item,
+// whose `members` decodes as an option map, not a comma string (OPNSENSE-2 — see group-form.ts).
+const liveItem = (
+  overrides: Partial<group.ModelIfgroupentryReadItem> = {},
+): group.ModelIfgroupentryReadItem => ({
   ifname: 'IOT_DEVICES',
-  members: 'opt1,opt2',
+  members: optionMap('opt1', 'opt2'),
   sequence: '1',
   ...overrides,
 });
 
-const getResponse = (items: Record<string, group.GroupItem>) =>
+const getResponse = (items: Record<string, group.ModelIfgroupentryReadItem>) =>
   Response.json({ group: { ifgroupentry: items } });
 
 describe('Opnsense.Firewall.Group spec.fetchLive', () => {
@@ -86,17 +91,21 @@ describe('opnsenseOperations(spec).read — S7/S8, marker-less API', () => {
 
 describe('opnsenseOperations(spec).diff', () => {
   test('noop when the declared member set matches live, regardless of order', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt2,opt1' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ members: optionMap('opt2', 'opt1') }) }),
+    );
     const result = await Effect.runPromise(
       opnsenseOperations(spec)
-        .diff(PROPS, attributesOf(UUID, liveItem({ members: 'opt2,opt1' })))
+        .diff(PROPS, attributesOf(UUID, liveItem({ members: optionMap('opt2', 'opt1') })))
         .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
     );
     expect(result).toEqual({ action: 'noop' });
   });
 
   test('update when a member was removed live', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt1' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ members: optionMap('opt1') }) }),
+    );
     const result = await Effect.runPromise(
       opnsenseOperations(spec)
         .diff(PROPS, attributesOf(UUID, liveItem()))
@@ -108,7 +117,9 @@ describe('opnsenseOperations(spec).diff', () => {
 
 describe('opnsenseOperations(spec).reconcile and destroy — the read-only policy', () => {
   test('reconcile observes with one GET, then refuses — never a write', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt1' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ members: optionMap('opt1') }) }),
+    );
     const failure = asRefusal(
       await Effect.runPromise(
         Effect.flip(

package/src/opnsense/group.ts

@@ -2,8 +2,10 @@
  * `Opnsense.Firewall.Group` — a read-only declaration of one `firewall/group` item (an
  * "Interface Group", not a permission group) on the edge. READ-ONLY BY DESIGN — see policy.ts's
  * header. `reconcile`/`delete` always refuse. Mirrors alias.ts exactly; see that file's header
- * for why `get()` (whole model) is the read source rather than `getGroup` — the same generation
- * gap (no `uuid` in `GetGroupRequest`'s schema) applies here too.
+ * for why `get()` (whole model) is the read source uniformly across this family rather than the
+ * now-correct `getGroup` per-item operation (OPNSENSE-1 fixed `GetGroupRequest`'s missing `uuid`,
+ * but switching to it is a separate, later PR). `members` decodes as an option map, not a comma
+ * string — see `group-form.ts`'s `attributesOf` (OPNSENSE-2).
  */
 import { adopt } from 'alchemy/AdoptPolicy';
 import { Resource } from 'alchemy';
@@ -54,7 +56,12 @@ export const isOpnsenseFirewallGroup = (value: unknown): value is OpnsenseFirewa
   value !== null &&
   (value as { Type?: unknown }).Type === 'Opnsense.Firewall.Group';
 
-export const spec: OpnsenseSpec<GroupProps, Group.GroupItem, GroupAttributes, OpnsenseOpError> = {
+export const spec: OpnsenseSpec<
+  GroupProps,
+  Group.ModelIfgroupentryReadItem,
+  GroupAttributes,
+  OpnsenseOpError
+> = {
   attributes: attributesOf,
   fetchLive: (props) =>
     Group.get({}).pipe(Effect.map((res) => res.group?.ifgroupentry?.[props.uuid])),

package/src/opnsense/wire.ts

@@ -2,20 +2,27 @@
  * How OPNsense's MVC model spells a value on the wire, and how to get it back to something
  * comparable — the `../proxmox/values.ts` idea, scoped to this vendor's own spellings.
  *
- * ★ OPNSENSE HAS EXACTLY TWO WIRE SHAPES THIS FAMILY NEEDS. Every `BooleanField` is the string
- *   `"1"` or `"0"` (never a JSON boolean — `AliasItem.enabled: string`, `GroupItem.nogroup?:
- *   string`, see `firewall_alias.ts`/`firewall_group.ts`). Every multi-select `OptionField`/
- *   `ModelRelationField` is a SINGLE comma-joined string, not a JSON array (`AliasItem.categories`,
- *   `GroupItem.members` — both carry the doc comment "wire value is a single comma-joined string,
- *   not a JSON array" in the generated SDK). Nothing here is specific to one resource.
+ * ★ OPNSENSE HAS EXACTLY TWO WIRE SHAPES THIS FAMILY NEEDS ON WRITE (props stay plain values;
+ *   this family never writes, but `matches` compares against them). Every `BooleanField` is the
+ *   string `"1"` or `"0"` (never a JSON boolean). Every multi-select `OptionField`/
+ *   `ModelRelationField`'s WRITE-side spelling is a SINGLE comma-joined string, not a JSON array.
+ *
+ * ⚠️ READ IS A THIRD SHAPE (OPNSENSE-2, distilled `homeflare/opnsense`'s `read-shape.ts`): the
+ *   SAME list-shaped fields decode on GET as an option map `{key: {value, selected}}`, not a
+ *   string — `AliasItem`/`GroupItem` (this family's OLD, pre-fix type references) were the
+ *   WRITE-shaped structs; `fetchLive` actually decodes `ModelAliasReadItem`/
+ *   `ModelIfgroupentryReadItem` (the WHOLE-MODEL GET's read-shaped item), whose `type`/
+ *   `interface`/`proto`/`categories`/`members` are option maps. `selectedOf`/`selectedOneOf`
+ *   below extract the selected key(s) back to the SAME plain-string/string[] shape `matches`
+ *   already compares, so the rest of this family's logic (and `AliasAttributes`/
+ *   `GroupAttributes`'s own field types) is unchanged.
  *
  * ⚠️ COMMA-LIST ORDER ROUND-TRIP IS NOT ASSUMED STABLE. OPNsense builds these from a PHP
- *   associative array (`ModelRelationField`/`OptionField::getNodeData()`), and nothing in the
- *   model XML promises the join order survives a save-then-read unchanged. Sorting and
- *   deduplicating both sides before comparing is what makes `matches` (alias-form.ts,
- *   group-form.ts) actually settle instead of reporting drift on a re-ordered list that changed
- *   nothing — the same reasoning `../proxmox/user-wire.ts`'s `groupSet` documents for PVE's
- *   `groups` field.
+ *   associative array, and nothing in the model XML promises the join order survives a
+ *   save-then-read unchanged. Sorting and deduplicating both sides before comparing is what makes
+ *   `matches` (alias-form.ts, group-form.ts) actually settle instead of reporting drift on a
+ *   re-ordered list that changed nothing — the same reasoning `../proxmox/user-wire.ts`'s
+ *   `groupSet` documents for PVE's `groups` field.
  */
 
 /** OPNsense's own boolean spelling. Absent takes the caller's stated default — OPNsense's own
@@ -54,3 +61,41 @@ export const numField = (value: string | undefined, fallback: number): number =>
   const parsed = Number(value);
   return Number.isFinite(parsed) ? parsed : fallback;
 };
+
+/** One entry of a GET-decoded option map — `{value: <label>, selected: 0|1}`, see this file's
+ * module doc. Structural, not imported from the SDK: every generated `*Map` field shares this
+ * exact shape (`OptionEntry` in each service module), and staying structural here avoids a
+ * per-resource-file type import just for this. */
+export interface OpnsenseOptionEntry {
+  readonly value: string;
+  readonly selected: number;
+}
+
+/**
+ * The selected key(s) of a GET-decoded option map, normalised the same way `csvSet` normalises
+ * the write-side comma string — sorted, deduplicated, empty-key filtered. Use for a
+ * `Multiple="Y"` field (`AliasItem.proto`, `AliasItem.categories`, `GroupItem.members`); for a
+ * single-select field use `selectedOneOf`.
+ */
+export const selectedOf = (
+  map: Readonly<Record<string, OpnsenseOptionEntry | undefined>> | undefined,
+): readonly string[] => {
+  if (map === undefined) return [];
+  const keys = Object.entries(map)
+    .filter(([key, entry]) => key !== '' && entry?.selected === 1)
+    .map(([key]) => key);
+  return [...new Set(keys)].sort();
+};
+
+/** Single-select convenience over `selectedOf` — the one selected key, or `''` if none (the same
+ * "absent" spelling a plain string field uses, e.g. `AliasItem.type`/`GroupItem`'s own
+ * `.\InterfaceField` members when not `Multiple="Y"`). */
+export const selectedOneOf = (
+  map: Readonly<Record<string, OpnsenseOptionEntry | undefined>> | undefined,
+): string => selectedOf(map)[0] ?? '';
+
+/** The encode direction, for test fixtures: every listed key marked `selected: 1`, mirroring a
+ * real OPNsense GET response (`{[key]: {value, selected: 1}}`) — so a fixture exercises the exact
+ * decode path `selectedOf`/`selectedOneOf` handle, not the pre-fix plain-string shape. */
+export const optionMap = (...keys: readonly string[]): Record<string, OpnsenseOptionEntry> =>
+  Object.fromEntries(keys.map((key) => [key, { value: key, selected: 1 }]));

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);