@homeflare/alchemy 0.39.0 → 0.41.0

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/qemu-volume.test.ts

@@ -1,9 +1,9 @@
 /**
  * Pure unit tests for `judgeDisk` — the red-team C1 fix on PR 297. No network, no fake PVE.
- * ⛔ WHAT THESE PIN: a "fresh" declaration (new-disk GiB, or `storage:cloudinit`) never re-drifts
- *   against an existing live volume in the same slot; a genuine volume/storage swap is refused,
- *   never written; a size change is refused (no resize call exists here); an option-only change is
- *   written on the LIVE volume id and LIVE size.
+ * ⛔ WHAT THESE PIN: a "fresh" declaration (new-disk GiB, `storage:cloudinit`, or
+ *   `storage:0,import-from=...`) never re-drifts against an existing live volume in the same slot;
+ *   a genuine volume/storage swap is refused, never written; a size change is refused (no resize
+ *   call exists here); an option-only change is written on the LIVE volume id and LIVE size.
  */
 import { describe, expect, test } from 'bun:test';
 import { judgeDisk, parseDisk } from './qemu-volume.ts';
@@ -20,6 +20,145 @@ describe('a "fresh" declaration matches any existing volume in its slot', () =>
   });
 });
 
+/**
+ * The disk-import convergence bug homeflare-proxmox PR 84's red team found (2026-09-26, real
+ * fake-PVE engine): `judgeDisk` never recognized `<storage>:0,import-from=<volid>` as a new-disk
+ * spelling, so it compared the literal volname `"0"` against PVE's live read-back of the real
+ * `vm-<vmid>-disk-<n>` it allocated on import and refused -- on the very deploy that created the
+ * disk, and on every plan after (Talos's `declareTalos` declares the import spelling every time,
+ * never switches to the resolved volname). Each `judgeDisk` call below stands in for one PVE read
+ * a real Talos deploy makes; none of them are a live PVE call.
+ */
+describe('the import-from create spelling converges (PR 84 red team)', () => {
+  const IMPORT_DECLARED = 'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw';
+
+  test('create: post-write verification reads back the real volume PVE allocated', () => {
+    // The deploy that creates the VM re-reads the config right after the PUT to verify it landed.
+    // Before the fix this was refused (declared volname "0" vs live "vm-10000-disk-0").
+    expect(judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=2G')).toEqual({});
+  });
+
+  test('re-plan: the same declared import spelling against the now-adopted live disk', () => {
+    // A later `bun run plan` fabricates the same live read as create did; declared is unchanged
+    // (declareTalos always emits import-from, never the resolved volname). Must still be a no-op.
+    const verdict = judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=2G');
+    expect(verdict.refuse).toBeUndefined();
+    expect(verdict.put).toBeUndefined();
+  });
+
+  test('second deploy: PVE has since filled in defaults the fresh check must not treat as drift', () => {
+    // pve-qemu-server fills in options nobody declared (ssd/discard/etc.). A "fresh" declaration
+    // skips option comparison entirely, so this must be a no-op too -- not a PUT trying to "fix"
+    // options that were never wrong, and not a resize of the placeholder "0" against the real size.
+    const verdict = judgeDisk(
+      'scsi0',
+      IMPORT_DECLARED,
+      'cephtb4:vm-10000-disk-0,size=2G,ssd=1,discard=on',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('no resize is ever attempted for an import-from disk', () => {
+    // The live size (2G, from the imported image) never appears in a `put` -- there is no `put` at
+    // all, because `want.kind === 'fresh'` returns before size or options are ever inspected.
+    expect(judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=200G')).toEqual({});
+  });
+
+  test('a volid with its own colon (storage:path) still parses as one fresh spelling', () => {
+    // import-from points at cephfs-tb4:import/talos-factory.raw -- a second colon inside the value,
+    // which a colon-anchored regex could truncate. Confirms the whole declared string is consumed.
+    expect(
+      judgeDisk(
+        'scsi0',
+        'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw',
+        'cephtb4:vm-10042-disk-0,size=2G',
+      ),
+    ).toEqual({});
+  });
+
+  test('a genuine size mismatch on an already-adopted volume is still refused', () => {
+    // Not an import-from declaration: a plain adopted volume whose declared size disagrees with the
+    // live one. Must still hit the existing no-resize refusal, unchanged by the new spelling.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:vm-10000-disk-0,size=4G',
+      'cephtb4:vm-10000-disk-0,size=2G',
+    );
+    expect(verdict.refuse).toMatch(/does not resize a disk/);
+    expect(verdict.put).toBeUndefined();
+  });
+
+  test('volname "0" without import-from is not swept into the new "fresh" spelling', () => {
+    // Guards NEW_IMPORT's literal ",import-from=" requirement: a coincidental "storage:0,k=v" (no
+    // import-from) must still be judged as a real volume named "0", not treated as always-matching.
+    const verdict = judgeDisk('scsi0', 'cephtb4:0,ssd=1', 'cephtb4:vm-10000-disk-0,size=2G');
+    expect(verdict.refuse).toMatch(/is not the live vm-10000-disk-0/);
+  });
+
+  test('a mismatched storage on an import-from declaration is still refused, not silently matched', () => {
+    // "fresh" only skips the volname/size/options checks -- the storage check above it still runs.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw',
+      'local-zfs:vm-10000-disk-0,size=2G',
+    );
+    expect(verdict.refuse).toMatch(/the volume is on local-zfs, declared on cephtb4/);
+  });
+});
+
+/**
+ * The LAND red team's Important finding on this same PR (2026-09-26): options declared alongside
+ * `import-from` were either silently dropped (declared after it -- `.+` swallowed them uncompared)
+ * or stranded the disk forever (declared before it -- missed the old regex, fell to the `volume`
+ * branch, and got refused against the real live volname just like the bug this file fixes). Fixed by
+ * detecting `import-from` after the general comma split instead of a position-anchored regex.
+ */
+describe('options declared alongside import-from are enforced, in either order (LAND red team)', () => {
+  const IMPORT = 'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw';
+
+  test('an option after import-from that already matches live is a noop', () => {
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('an option after import-from that disagrees with live is written, on the live volume id', () => {
+    // Scenario B from the red team: iothread was declared and honored at create; discard/ssd are
+    // added later. Before this fix, verify said `noop` and the deploy wrote nothing.
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1,discard=on,ssd=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict.put).toBe('cephtb4:vm-150-disk-0,iothread=1,discard=on,ssd=1,size=2G');
+  });
+
+  test('an option BEFORE import-from is still recognized as fresh, not a stranded volume', () => {
+    // Scenario C from the red team: `cephtb4:0,iothread=1,import-from=...` missed the old
+    // position-anchored regex entirely and was refused forever as a volname "0" vs the live one.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:0,iothread=1,import-from=cephfs-tb4:import/talos-factory.raw',
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('a live-only default the caller never declared is not treated as drift', () => {
+    // Only iothread was declared; ssd/discard are PVE's own fill-in. A full-map compare (sameMap)
+    // would call this drift and rewrite the disk on every plan -- the subset check must not.
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G,ssd=1,discard=on',
+    );
+    expect(verdict).toEqual({});
+  });
+});
+
 describe('an existing-volume declaration', () => {
   const live = 'cephtb4:vm-101-disk-0,size=32G,ssd=1';
 
@@ -77,4 +216,14 @@ describe('parseDisk', () => {
     expect(disk.size).toBe('32G');
     expect(disk.options).toEqual(new Map([['ssd', '1']]));
   });
+
+  test('the import-from spelling parses as fresh, same shape as the other two', () => {
+    expect(parseDisk('cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw')).toEqual({
+      kind: 'fresh',
+      options: new Map(),
+      size: undefined,
+      source: 'cephtb4',
+      volname: '',
+    });
+  });
 });

package/src/proxmox/qemu-volume.ts

@@ -11,15 +11,48 @@
  *   creates a fresh cloud-init seed drive; the live slot then reads back
  *   `<storage>:vm-<vmid>-cloudinit,media=cdrom`. Both spellings compare equal to an existing volume
  *   already in the slot, for the same reason `storage:GiB` does.
+ * ⛔ A THIRD NEW-VOLUME SPELLING, FOUND BY homeflare-proxmox PR 84's RED TEAM (2026-09-26, real
+ *   fake-PVE engine): `<storage>:0,import-from=<volid>` imports a disk from another volume or a
+ *   downloaded image at create time. Before this fix it fell through to the `volume` branch below
+ *   (it has a comma, so `NEW_DISK` never matched it), so `want.volname` stayed the literal `"0"`
+ *   forever while PVE's live read-back reported the real `vm-<vmid>-disk-<n>` it allocated on
+ *   import -- a volname mismatch, REFUSED. That refusal fired on the very deploy that created the
+ *   disk (post-write verification reads the config right back) and on every plan after, because
+ *   the declared value is `import-from=...` again each time (Talos's `declareTalos` recomputes it
+ *   from the download resource, never switches to the resolved volname). Fixed the same way as the
+ *   other two: an `import-from` disk also counts as `kind: 'fresh'`, which already matches whatever
+ *   is live unconditionally when nothing else is declared (see `want.kind === 'fresh'` below) -- no
+ *   special-casing of the live side needed.
+ * ⛔ IMPORT-FROM IMPORTS ONLY AT CREATE. Changing just the `import-from=` *source* (e.g. bumping a
+ *   factory image path) on an already-created disk still reads as `noop`: PVE does not re-import an
+ *   existing volume, and this resource has no rebuild-the-disk path. That is correct for Talos, which
+ *   upgrades in place through `talosctl`, not by recreating its disk -- a caller that DOES want a
+ *   fresh import on image change must delete and recreate the row itself.
+ * ⛔ LAND RED TEAM (2026-09-26): OPTIONS DECLARED ALONGSIDE `import-from` MUST STILL BE ENFORCED, AND
+ *   MUST BE RECOGNIZED REGARDLESS OF WHERE `import-from` SITS IN THE LIST. The first cut matched
+ *   `import-from` only when it came immediately after `:0,`, via a regex whose `.+` then swallowed
+ *   every option after it uncompared (silently never written) while any option declared BEFORE it
+ *   (`cephtb4:0,iothread=1,import-from=...`) missed the regex entirely and fell to the `volume`
+ *   branch, comparing literal volname `"0"` against the live real one forever -- REFUSED, same
+ *   stranded-disk failure this file exists to fix, just for a different option order. Fixed by
+ *   folding the import check into the general `storage:volname,k=v,...` parse below: ANY declaration
+ *   whose volname is the literal `"0"` and whose options include an `import-from` key is `fresh`,
+ *   with `import-from` itself dropped and every other declared option carried through for
+ *   `judgeDisk` to enforce (see its `want.kind === 'fresh'` branch) -- independent of option order.
  * ⛔ NO RESIZE IS MADE HERE. lxc-volume.ts drives a second endpoint (`PUT .../resize`) this resource
  *   does not call — Talos's disks are declared once at their create size. A size difference between
  *   two already-adopted volume declarations is REFUSED with the `qm resize` to run by hand, never
  *   guessed at or silently written.
- * ⚠️ OPTIONS BEYOND `size` ARE COMPARED AS A WHOLE, NOT KEY BY KEY. Unlike lxc-volume.ts, this file
- *   does not model pve-qemu-server's per-option defaults (`ssd`, `discard`, `iothread`, …) — that
- *   table is unverified here. So an option difference is real drift and gets written, exactly as the
- *   whole-string comparison this replaces already did; only the two "new volume" spellings and the
- *   live volume id/size are special-cased, which is the minimum that fixes the measured bug.
+ * ⚠️ OPTIONS BEYOND `size` ARE COMPARED AS A WHOLE, NOT KEY BY KEY, FOR AN ADOPTED `volume` -- BUT AS
+ *   A SUBSET FOR A `fresh` IMPORT. Unlike lxc-volume.ts, this file does not model pve-qemu-server's
+ *   per-option defaults (`ssd`, `discard`, `iothread`, …) — that table is unverified here. For an
+ *   already-adopted volume, any options difference from live is real drift and gets written in full,
+ *   exactly as the whole-string comparison this replaces already did. An `import-from` disk cannot
+ *   use that same whole-map comparison: nobody declares PVE's post-import defaults, so comparing the
+ *   full map would treat every default PVE fills in as drift and rewrite the disk on every plan (the
+ *   builder's "second deploy" test below pins this). So a `fresh` import instead checks only the
+ *   options the caller actually declared against live, ignoring any live-only keys, and PUTs the
+ *   declared options (not merged with what live already has) when one of them disagrees.
  */
 import { sameMap } from './lxc-wire.ts';
 
@@ -29,7 +62,8 @@ const NEW_DISK = /^([^:\s]+):(\d+(?:\.\d+)?)$/;
 const NEW_CLOUDINIT = /^([^:\s]+):cloudinit$/;
 
 export type Disk = {
-  /** `fresh`: either new-disk spelling above. `volume`: an existing volume, `storage:volname,...`. */
+  /** `fresh`: a new-disk spelling (`storage:GiB`, `storage:cloudinit`, or `storage:0,import-from=...`
+   *  possibly with more options). `volume`: an existing volume, `storage:volname,...`. */
   readonly kind: 'fresh' | 'volume';
   readonly source: string;
   readonly volname: string;
@@ -37,15 +71,24 @@ export type Disk = {
   readonly options: Map<string, string>;
 };
 
-/** `storage:volname,k=v,...` (or one of the two "fresh" spellings) into its comparable parts. */
+/**
+ * `storage:volname,k=v,...` (or one of the "fresh" spellings) into its comparable parts.
+ * ⚠️ THE IMPORT SPELLING IS DETECTED AFTER THE GENERAL SPLIT, NOT BY ITS OWN REGEX: `import-from`'s
+ *   value can itself contain a colon (e.g. `cephfs-tb4:import/talos-factory.raw`) and other options
+ *   can come before or after it, so a regex anchored on `:0,import-from=` right after the colon (as
+ *   the first cut had) misses that ordering and swallows everything after it into one opaque match.
+ *   Splitting on commas like any `volume` spelling first, THEN checking for a literal `"0"` volname
+ *   plus an `import-from` key among the parsed options, catches every ordering and keeps every other
+ *   declared option (`iothread=1`, `discard=on`, …) visible to `judgeDisk` instead of swallowed.
+ */
 export const parseDisk = (text: string): Disk => {
-  const fresh = NEW_DISK.exec(text) ?? NEW_CLOUDINIT.exec(text);
-  if (fresh !== null) {
+  const bare = NEW_DISK.exec(text) ?? NEW_CLOUDINIT.exec(text);
+  if (bare !== null) {
     return {
       kind: 'fresh',
       options: new Map(),
       size: undefined,
-      source: fresh[1] ?? '',
+      source: bare[1] ?? '',
       volname: '',
     };
   }
@@ -61,6 +104,10 @@ export const parseDisk = (text: string): Disk => {
   );
   const size = options.get('size');
   options.delete('size');
+  if (volname === '0' && options.has('import-from')) {
+    options.delete('import-from');
+    return { kind: 'fresh', options, size: undefined, source, volname: '' };
+  }
   return { kind: 'volume', options, size, source, volname };
 };
 
@@ -97,10 +144,20 @@ export const judgeDisk = (key: string, declared: string, live: string): DiskVerd
         'between storages is not an update this resource makes -- move it by hand, then declare it.',
     };
   }
-  // ⛔ A "fresh" declaration always matches an existing volume already in this slot: PVE holds one
-  //   there, and re-sending storage:GiB / storage:cloudinit would allocate a SECOND volume and park
-  //   the live one at unusedN (the header's ⛔, ported from lxc-volume.ts's own).
-  if (want.kind === 'fresh') return {};
+  // ⛔ A "fresh" declaration never re-triggers create: PVE holds a real volume in this slot already,
+  //   and re-sending storage:GiB / storage:cloudinit / storage:0,import-from=... as the PUT value
+  //   would allocate a SECOND volume and park the live one at unusedN (the header's ⛔, ported from
+  //   lxc-volume.ts's own). So a `fresh` PUT, when one is needed, is always built from the LIVE
+  //   volume id (`have.volname`/`have.size`), never the declared placeholder -- same as `volume`.
+  // ⚠️ ONLY THE OPTIONS THE CALLER ACTUALLY DECLARED ARE CHECKED (a subset, not `sameMap`): nobody
+  //   declares PVE's post-import defaults, so an empty `want.options` (plain import-from, nothing
+  //   else declared) is always a noop no matter what live has filled in, and a non-empty one is
+  //   compared key-by-key against live, ignoring any key live has that the caller never declared.
+  if (want.kind === 'fresh') {
+    if (want.options.size === 0) return {};
+    if ([...want.options].every(([k, v]) => have.options.get(k) === v)) return {};
+    return { put: printOptions(have.source, have.volname, want.options, have.size) };
+  }
   if (want.volname !== have.volname) {
     return {
       refuse:

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