pixie-lab 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

pixie/deploy/_main.py

@@ -311,10 +311,32 @@ def _cmd_purge(args: argparse.Namespace) -> int:
         shutil.rmtree(data_dir)
         print(f"pixie-lab purge: removed {data_dir}", file=sys.stderr)
 
-    # 4. Delete the deploy directory itself.
+    # 4. Delete the deploy directory itself. ``dest`` often sits under a
+    #    root-owned parent (e.g. /opt), where an unprivileged operator can
+    #    empty the dir but can't rmdir it -- rmtree clears the contents,
+    #    then raises on the final rmdir. Report that plainly instead of
+    #    dumping a traceback; the state is gone either way, so it's a
+    #    caveat, not a failure.
     if remove_dir and dest.exists():
-        shutil.rmtree(dest)
-        print(f"pixie-lab purge: removed {dest}", file=sys.stderr)
+        try:
+            shutil.rmtree(dest)
+            print(f"pixie-lab purge: removed {dest}", file=sys.stderr)
+        except OSError as exc:
+            leftover = sorted(p.name for p in dest.iterdir()) if dest.is_dir() else []
+            if not leftover:
+                print(
+                    f"pixie-lab purge: emptied {dest}, but could not remove the "
+                    f"directory itself ({exc.strerror or exc}) -- its parent is not "
+                    f"writable (a root-owned /opt, say). The empty dir is harmless; "
+                    f"you can redeploy into it or 'sudo rmdir' it.",
+                    file=sys.stderr,
+                )
+            else:
+                print(
+                    f"pixie-lab purge: could not fully remove {dest} "
+                    f"({exc.strerror or exc}); leftover: {', '.join(leftover)}",
+                    file=sys.stderr,
+                )
 
     return 0
 

pixie/events/_kinds.py

@@ -21,7 +21,9 @@ from __future__ import annotations
 # ---------- catalog + fetch pipeline ---------------------------------
 #
 # Every catalog-store mutation emits one of these. ``subject_kind`` is
-# always ``"entry"``; ``subject_id`` is the catalog entry name.
+# ``"entry"`` (``subject_id`` = the catalog entry name) for the per-row
+# kinds; the ``catalog.import.*`` pair is catalog-scoped instead
+# (``subject_kind = "catalog"``) since one import touches many entries.
 
 CATALOG_ENTRY_ADDED = "catalog.entry.added"
 """A new row landed via POST /catalog/entries, POST /ui/catalog/add,
@@ -95,36 +97,37 @@ EXPORT_NBDKIT_EXITED = "export.nbdkit.exited"
 (``_refresh_row`` noticed no live proc for a ``running`` row).
 ``details.previous_port`` + ``details.error`` explain."""
 
-# ---------- persistent overlays (per-machine qcow2) -----------------
+# ---------- persistent overlays (alias-keyed volumes) ---------------
 #
-# ``subject_kind`` is always ``"machine"``; ``subject_id`` is the
-# canonical MAC. ``details`` names the (image_sha, profile) triple.
+# ``subject_kind`` is always ``"overlay"``; ``subject_id`` is the
+# globally-unique ``alias`` (``""`` for a fleet-wide bulk action). An
+# overlay is a single-writer qcow2 volume over one base image, not a
+# per-machine file; ``details`` carries ``alias`` / ``image_sha`` /
+# ``qcow2_path`` as relevant.
 
 OVERLAY_CREATED = "overlay.created"
-"""A per-machine qcow2 overlay was materialised for the first time
-for a ``(mac, image_sha, profile)`` triple. ``details`` carries
-``image_sha``, ``profile``, and ``qcow2_path``."""
+"""An alias-keyed qcow2 overlay was materialised for the first time
+(lazy-created on the first nbdboot render, or after a Reset).
+``details`` carries ``alias``, ``image_sha``, and ``qcow2_path``."""
 
 OVERLAY_RESET = "overlay.reset"
-"""Operator hit Reset on the machine detail page: the qemu-nbd was
-terminated, the qcow2 was unlinked, the overlays row was deleted.
+"""Operator hit Reset (one alias) or Prune (bulk) on the Overlays
+page: the qemu-nbd was terminated, the qcow2 unlinked, the overlays
+row deleted. ``subject_id`` is the alias for a single Reset, ``""``
+for a bulk Prune (``details.pruned`` counts the reclaimed volumes).
 Next plan render lazily creates a fresh overlay from the base."""
 
-OVERLAY_BOOTED = "overlay.booted"
-"""Plan render for an already-existing overlay row (heartbeat).
-Emitted on every persistent nbdboot render so an operator can grep
-the events log for "which overlays am I actually using?"."""
-
 # ---------- machines + PXE ------------------------------------------
 #
 # ``subject_kind`` is always ``"machine"``; ``subject_id`` is the
 # canonical MAC address.
 
 MACHINE_DISCOVERED = "machine.discovered"
-"""First-ever GET /pxe/<mac> for a MAC pixie has not seen before.
-Emitted from ``machines_store.touch_seen`` when a new row is
-created; subsequent hits do NOT emit (they update ``last_seen_at``
-via the ``pxe.plan.rendered`` event instead)."""
+"""First-ever GET /pxe/<mac> for a MAC pixie has not seen before. The
+``/pxe/<mac>`` route detects the absent row before ``touch_seen``
+auto-registers it and emits this once; subsequent hits do NOT emit
+(they update ``last_seen_at`` via the ``pxe.plan.rendered`` event
+instead). ``details.boot_mode`` is the auto-registered default."""
 
 MACHINE_BOUND = "machine.bound"
 """First bind for a MAC: PUT /machines/<mac> or POST
@@ -232,7 +235,6 @@ KNOWN_EVENT_KINDS: frozenset[str] = frozenset(
         EXPORT_NBDKIT_EXITED,
         OVERLAY_CREATED,
         OVERLAY_RESET,
-        OVERLAY_BOOTED,
         MACHINE_DISCOVERED,
         MACHINE_BOUND,
         MACHINE_BINDING_CHANGED,

pixie/exports/_store.py

@@ -33,33 +33,80 @@ CREATE TABLE IF NOT EXISTS exports (
 
 CREATE INDEX IF NOT EXISTS idx_exports_content_sha
     ON exports(content_sha256);
+"""
 
--- One row per (mac, image_sha, profile) triple; the qcow2 file at
--- ``qcow2_path`` has ``backing_file`` pointing at the catalog blob
--- for ``image_sha`` and holds every write the machine has made under
--- that profile. Separate from the ``exports`` table above because the
--- ephemeral (nbdkit) and persistent (qemu-nbd) paths have different
--- identity (per-content vs per-triple) and lifecycle (respawn on
--- restart vs create-on-first-bind).
+# An overlay is a globally-named writable volume over ONE base image.
+# Identity is its ``alias`` (globally unique), NOT the machine: the
+# qcow2 at ``qcow2_path`` has ``backing_file`` pointing at the catalog
+# blob for ``image_sha`` and holds every write made through it. Exactly
+# one machine may hold exclusive write at a time -- ``attached_mac``
+# (empty = free) records which; qemu-nbd's qcow2 image-lock is the
+# backstop. Separate table from ``exports`` because the ephemeral
+# (nbdkit, per-content) and persistent (qemu-nbd, per-alias) paths have
+# different identity + lifecycle.
+_OVERLAYS_SCHEMA = """
 CREATE TABLE IF NOT EXISTS overlays (
-    mac           TEXT NOT NULL,
+    alias         TEXT PRIMARY KEY,
     image_sha     TEXT NOT NULL,
-    profile       TEXT NOT NULL,
     qcow2_path    TEXT NOT NULL,
+    attached_mac  TEXT NOT NULL DEFAULT '',
     nbd_port      INTEGER NOT NULL DEFAULT 0,
     status        TEXT NOT NULL DEFAULT 'idle',
     error         TEXT NOT NULL DEFAULT '',
     created_at    TEXT NOT NULL,
-    last_boot_at  TEXT NOT NULL DEFAULT '',
-    PRIMARY KEY (mac, image_sha, profile)
+    last_boot_at  TEXT NOT NULL DEFAULT ''
 );
-CREATE INDEX IF NOT EXISTS idx_overlays_mac
-    ON overlays(mac);
 CREATE INDEX IF NOT EXISTS idx_overlays_image_sha
     ON overlays(image_sha);
+CREATE INDEX IF NOT EXISTS idx_overlays_attached_mac
+    ON overlays(attached_mac);
 """
 
 
+def _migrate_overlays_schema(conn: sqlite3.Connection) -> None:
+    """Re-key the pre-alias ``overlays`` table (PK
+    ``(mac, image_sha, profile)``) to the alias-keyed shape. For each
+    old row a globally-unique ``alias = <profile>-<mac_slug>`` is minted
+    (dedup on the rare collision) and ``attached_mac`` is seeded with the
+    row's old ``mac`` so the machine that owned it keeps its exclusive
+    hold. The qcow2 ``qcow2_path`` is left untouched -- no large files
+    move during migration. Idempotent: a table that already has an
+    ``alias`` column, or no overlays table at all, is left alone."""
+    cols = {row[1] for row in conn.execute("PRAGMA table_info(overlays)").fetchall()}
+    if not cols or "alias" in cols:
+        return
+    old_rows = conn.execute("SELECT * FROM overlays").fetchall()
+    conn.execute("ALTER TABLE overlays RENAME TO overlays_pre_alias")
+    conn.executescript(_OVERLAYS_SCHEMA)
+    seen: set[str] = set()
+    for r in old_rows:
+        mac_slug = str(r["mac"]).replace(":", "-")
+        base = f"{r['profile']}-{mac_slug}"
+        alias = base
+        n = 1
+        while alias in seen:
+            n += 1
+            alias = f"{base}-{n}"
+        seen.add(alias)
+        conn.execute(
+            """
+            INSERT INTO overlays (
+                alias, image_sha, qcow2_path, attached_mac,
+                nbd_port, status, error, created_at, last_boot_at
+            ) VALUES (?, ?, ?, ?, 0, 'idle', '', ?, ?)
+            """,
+            (
+                alias,
+                r["image_sha"],
+                r["qcow2_path"],
+                r["mac"],
+                r["created_at"],
+                r["last_boot_at"],
+            ),
+        )
+    conn.execute("DROP TABLE overlays_pre_alias")
+
+
 @dataclass
 class Export:
     """One registered NBD export."""
@@ -99,6 +146,8 @@ class ExportsStore:
     def _ensure_schema(self) -> None:
         with self._conn() as conn:
             conn.executescript(_SCHEMA)
+            _migrate_overlays_schema(conn)
+            conn.executescript(_OVERLAYS_SCHEMA)
 
     @contextlib.contextmanager
     def _conn(self) -> Generator[sqlite3.Connection]:
@@ -182,18 +231,20 @@ def _row_to_export(row: sqlite3.Row) -> Export:
 
 @dataclass
 class Overlay:
-    """One persistent per-machine qcow2 overlay for ``boot_mode=nbdboot``.
+    """A globally-named writable volume over one base image.
 
-    Identity is the ``(mac, image_sha, profile)`` triple. The qcow2 at
-    ``qcow2_path`` has ``backing_file`` pointing at the catalog blob
-    for ``image_sha``; a qemu-nbd subprocess serves it while the row's
-    ``status == 'running'``. Deleting the row is the operator's
-    "Reset overlay" action -- the caller unlinks the qcow2 too."""
+    Identity is the ``alias`` (globally unique), not a machine: the
+    qcow2 at ``qcow2_path`` has ``backing_file`` pointing at the catalog
+    blob for ``image_sha`` and holds every write made through it.
+    ``attached_mac`` records the single machine currently holding
+    exclusive write ("" = free); a qemu-nbd subprocess serves it while
+    ``status == 'running'``. Deleting the row is the operator's "Reset"
+    action -- the caller unlinks the qcow2 too."""
 
-    mac: str
+    alias: str
     image_sha: str
-    profile: str
     qcow2_path: str
+    attached_mac: str = ""
     nbd_port: int = 0
     status: str = "idle"  # "idle" | "running" | "error"
     error: str = ""
@@ -202,10 +253,10 @@ class Overlay:
 
     def to_dict(self) -> dict[str, Any]:
         out: dict[str, Any] = {
-            "mac": self.mac,
+            "alias": self.alias,
             "image_sha": self.image_sha,
-            "profile": self.profile,
             "qcow2_path": self.qcow2_path,
+            "attached_mac": self.attached_mac,
             "status": self.status,
             "created_at": self.created_at,
         }
@@ -219,12 +270,12 @@ class Overlay:
 
 
 class OverlaysStore:
-    """Repository over the ``overlays`` table on the shared state.db.
+    """Repository over the alias-keyed ``overlays`` table.
 
-    Same DB path as :class:`ExportsStore` + :class:`CatalogStore`.
-    Kept as a sibling class rather than a method-set on ExportsStore
-    so the ephemeral vs persistent lifecycles read as distinct
-    concerns at the call site."""
+    Same DB path as :class:`ExportsStore` + :class:`CatalogStore`. The
+    table is created + migrated by :meth:`ExportsStore._ensure_schema`
+    (constructed first at startup), so this is a thin data-access
+    sibling."""
 
     def __init__(self, db_path: Path) -> None:
         self.db_path = Path(db_path)
@@ -240,31 +291,21 @@ class OverlaysStore:
             conn.close()
 
     def list_all(self) -> list[Overlay]:
-        """Every overlay row across every (mac, image, profile) triple.
-        Named ``list_all`` (not ``list``) so ``list[Overlay]`` in
-        sibling method signatures below resolves to the built-in
-        rather than the shadowed method."""
         with self._conn() as conn:
-            rows = conn.execute(
-                "SELECT * FROM overlays ORDER BY mac, image_sha, profile"
-            ).fetchall()
+            rows = conn.execute("SELECT * FROM overlays ORDER BY alias").fetchall()
         return [_row_to_overlay(r) for r in rows]
 
-    def get(self, mac: str, image_sha: str, profile: str) -> Overlay | None:
+    def get(self, alias: str) -> Overlay | None:
         with self._conn() as conn:
-            row = conn.execute(
-                "SELECT * FROM overlays WHERE mac = ? AND image_sha = ? AND profile = ?",
-                (mac, image_sha, profile),
-            ).fetchone()
+            row = conn.execute("SELECT * FROM overlays WHERE alias = ?", (alias,)).fetchone()
         return _row_to_overlay(row) if row else None
 
-    def list_for_machine_and_image(self, mac: str, image_sha: str) -> list[Overlay]:
-        """Every profile this ``(mac, image_sha)`` combo has ever created.
-        Drives the bind-form overlay picker."""
+    def list_for_image(self, image_sha: str) -> list[Overlay]:
+        """Every overlay over this base image. Drives the bind-form
+        picker (which aliases a machine could attach for this image)."""
         with self._conn() as conn:
             rows = conn.execute(
-                "SELECT * FROM overlays WHERE mac = ? AND image_sha = ? ORDER BY profile",
-                (mac, image_sha),
+                "SELECT * FROM overlays WHERE image_sha = ? ORDER BY alias", (image_sha,)
             ).fetchall()
         return [_row_to_overlay(r) for r in rows]
 
@@ -273,15 +314,15 @@ class OverlaysStore:
             conn.execute(
                 """
                 INSERT OR REPLACE INTO overlays (
-                    mac, image_sha, profile, qcow2_path,
+                    alias, image_sha, qcow2_path, attached_mac,
                     nbd_port, status, error, created_at, last_boot_at
                 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
                 """,
                 (
-                    ov.mac,
+                    ov.alias,
                     ov.image_sha,
-                    ov.profile,
                     ov.qcow2_path,
+                    ov.attached_mac,
                     ov.nbd_port,
                     ov.status,
                     ov.error,
@@ -290,55 +331,52 @@ class OverlaysStore:
                 ),
             )
 
-    def delete(self, mac: str, image_sha: str, profile: str) -> bool:
+    def delete(self, alias: str) -> bool:
         with _DB_WRITE_LOCK, self._conn() as conn:
-            cur = conn.execute(
-                "DELETE FROM overlays WHERE mac = ? AND image_sha = ? AND profile = ?",
-                (mac, image_sha, profile),
-            )
+            cur = conn.execute("DELETE FROM overlays WHERE alias = ?", (alias,))
             return cur.rowcount > 0
 
-    def update_runtime(
-        self,
-        mac: str,
-        image_sha: str,
-        profile: str,
-        *,
-        nbd_port: int,
-        status: str,
-        error: str = "",
-    ) -> None:
+    def update_runtime(self, alias: str, *, nbd_port: int, status: str, error: str = "") -> None:
         """Refresh transient port + status after a qemu-nbd spawn."""
         with _DB_WRITE_LOCK, self._conn() as conn:
             conn.execute(
-                """
-                UPDATE overlays
-                SET nbd_port = ?, status = ?, error = ?
-                WHERE mac = ? AND image_sha = ? AND profile = ?
-                """,
-                (nbd_port, status, error, mac, image_sha, profile),
+                "UPDATE overlays SET nbd_port = ?, status = ?, error = ? WHERE alias = ?",
+                (nbd_port, status, error, alias),
             )
 
-    def touch_last_boot(self, mac: str, image_sha: str, profile: str) -> None:
-        """Record the timestamp of the most recent plan render for this
-        overlay. Used by the UI's "last used" column + future auto-GC."""
+    def touch_last_boot(self, alias: str) -> None:
+        with _DB_WRITE_LOCK, self._conn() as conn:
+            conn.execute("UPDATE overlays SET last_boot_at = ? WHERE alias = ?", (now_iso(), alias))
+
+    def attach(self, alias: str, mac: str) -> None:
+        """Record ``mac`` as the exclusive writer of ``alias``.
+        Single-writer is enforced at the call site (bind route + renderer
+        refuse a hand-off to a different mac); this just records it."""
+        with _DB_WRITE_LOCK, self._conn() as conn:
+            conn.execute("UPDATE overlays SET attached_mac = ? WHERE alias = ?", (mac, alias))
+
+    def detach(self, alias: str) -> None:
+        """Release the writer hold on ``alias`` (attached_mac -> '')."""
+        with _DB_WRITE_LOCK, self._conn() as conn:
+            conn.execute("UPDATE overlays SET attached_mac = '' WHERE alias = ?", (alias,))
+
+    def detach_mac(self, mac: str, *, keep: str = "") -> None:
+        """Release every alias ``mac`` holds except ``keep`` -- called
+        when a machine rebinds away so a stale hold can't block another
+        machine from attaching."""
         with _DB_WRITE_LOCK, self._conn() as conn:
             conn.execute(
-                """
-                UPDATE overlays
-                SET last_boot_at = ?
-                WHERE mac = ? AND image_sha = ? AND profile = ?
-                """,
-                (now_iso(), mac, image_sha, profile),
+                "UPDATE overlays SET attached_mac = '' WHERE attached_mac = ? AND alias != ?",
+                (mac, keep),
             )
 
 
 def _row_to_overlay(row: sqlite3.Row) -> Overlay:
     return Overlay(
-        mac=row["mac"],
+        alias=row["alias"],
         image_sha=row["image_sha"],
-        profile=row["profile"],
         qcow2_path=row["qcow2_path"],
+        attached_mac=row["attached_mac"],
         nbd_port=row["nbd_port"] or 0,
         status=row["status"],
         error=row["error"],

pixie/machines/_routes.py

@@ -66,13 +66,15 @@ class BindBody(BaseModel):
             "the global PIXIE_LIVE_ENV_EXTRA_CMDLINE. Single line."
         ),
     )
-    overlay_profile: str = Field(
+    overlay_alias: str = Field(
         default="",
         description=(
-            "Persistent-overlay profile name for nbdboot. Blank means "
-            "ephemeral tmpfs (writes vanish on reboot); non-blank names a "
-            "qcow2 overlay that persists on pixie's data volume. "
-            "Alphanumeric-leading; a-z / A-Z / 0-9 / . _ - (max 64 chars)."
+            "Globally-unique persistent-overlay alias for nbdboot. Blank "
+            "means ephemeral tmpfs (writes vanish on reboot); non-blank "
+            "attaches a named writable volume (qcow2 over a base image) "
+            "that persists on pixie's data volume. Single-writer: one "
+            "machine per alias. Alphanumeric-leading; a-z / A-Z / 0-9 / "
+            ". _ - (max 64 chars)."
         ),
     )
 
@@ -133,14 +135,28 @@ def upsert_machine(
         # not supply any new ones -- honours a partial-update PUT
         # without needing PATCH.
         labels_arg = labels if labels else (list(previous.labels) if previous else [])
+        # Single-writer + alias-implies-image resolution is shared with
+        # the UI bind route (see pixie.web._overlay_bind): attaching an
+        # alias held by another machine raises ValueError -> 422 here.
+        from pixie.web._overlay_bind import overlay_state, resolve_overlay_bind
+
+        overlays, overlays_dir = overlay_state(request.app.state)
+        image_sha, resolved_alias = resolve_overlay_bind(
+            overlays=overlays,
+            overlays_dir=overlays_dir,
+            mac=canon,
+            boot_mode=body.boot_mode,
+            image_sha=body.image_content_sha256.strip().lower(),
+            alias=body.overlay_alias,
+        )
         row = _get_machines(request).upsert_binding(
             canon,
             boot_mode=body.boot_mode,
-            image_content_sha256=body.image_content_sha256.strip().lower(),
+            image_content_sha256=image_sha,
             labels=labels_arg,
             target_disk_serial=body.target_disk_serial,
             extra_cmdline=body.extra_cmdline,
-            overlay_profile=body.overlay_profile,
+            overlay_alias=resolved_alias,
         )
     except ValueError as exc:
         raise HTTPException(status_code=422, detail=str(exc)) from exc

pixie/machines/_store.py

@@ -146,6 +146,7 @@ CREATE TABLE IF NOT EXISTS machines (
     target_disk_serial     TEXT NOT NULL DEFAULT '',
     extra_cmdline          TEXT NOT NULL DEFAULT '',
     overlay_profile        TEXT NOT NULL DEFAULT '',
+    overlay_alias          TEXT NOT NULL DEFAULT '',
     inventory_json         TEXT NOT NULL DEFAULT '',
     inventory_at           TEXT NOT NULL DEFAULT '',
     discovered_at          TEXT NOT NULL,
@@ -163,19 +164,27 @@ CREATE INDEX IF NOT EXISTS idx_machines_image_content_sha
 # live env's flash pipeline has a concrete destination.
 _FLASH_MODES: frozenset[str] = frozenset({"pixie-flash-once", "pixie-flash-always"})
 
+# Boot modes that actually consume the machine's bound disk image on the
+# next PXE: the flash pipeline writes it, nbdboot serves it over NBD. The
+# other modes (ipxe-exit / pixie-inventory / pixie-tui) ignore
+# ``image_content_sha256`` entirely, so surfacing a bound image for them
+# is noise. Used by the machines-list Image column.
+IMAGE_BOOT_MODES: frozenset[str] = _FLASH_MODES | frozenset({"nbdboot"})
+
 # Bty's shape: alphanumeric-leading, alphanumeric + space + . _ - inside,
 # 64 chars max per label, 16 labels max per machine. Matches the CSS-safe
 # subset so a label can render as a ``.badge`` without escaping surprises.
 _LABEL_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9 ._\-]{0,63}$")
 _LABEL_LIMIT = 16
 
-# Overlay profile names land on disk as
-# ``data/overlays/<mac_slug>/<image_sha>/<profile>.qcow2``. Restrict to
-# a filesystem-safe subset so a hand-typed name can't escape the
-# storage tree via ``..`` or a directory separator. Same alnum-leading
-# shape as labels for consistency; no space to keep the on-disk
-# filename shell-friendly.
-_OVERLAY_PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._\-]{0,63}$")
+# Overlay aliases land on disk as ``data/overlays/<alias>.qcow2``.
+# Restrict to a filesystem-safe subset so a hand-typed name can't escape
+# the storage tree via ``..`` or a directory separator. Same alnum-
+# leading shape as labels for consistency; no space to keep the on-disk
+# filename shell-friendly. Public so the bind-route overlay resolver
+# (pixie.web._overlay_bind) validates a new alias with the SAME rule
+# before it ever writes a row or a path.
+OVERLAY_ALIAS_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._\-]{0,63}$")
 
 
 def _migrate_schema(conn: sqlite3.Connection) -> None:
@@ -193,6 +202,17 @@ def _migrate_schema(conn: sqlite3.Connection) -> None:
         conn.execute("ALTER TABLE machines ADD COLUMN extra_cmdline TEXT NOT NULL DEFAULT ''")
     if "overlay_profile" not in cols:
         conn.execute("ALTER TABLE machines ADD COLUMN overlay_profile TEXT NOT NULL DEFAULT ''")
+    # Overlay re-model: a machine now binds a globally-unique overlay
+    # ``alias`` instead of a per-(mac,image) ``profile``. Seed the new
+    # column from the old one with the SAME deterministic mapping the
+    # overlays-table migration uses (``<profile>-<mac_slug>``) so a
+    # machine keeps pointing at the same qcow2.
+    if "overlay_alias" not in cols:
+        conn.execute("ALTER TABLE machines ADD COLUMN overlay_alias TEXT NOT NULL DEFAULT ''")
+        conn.execute(
+            "UPDATE machines SET overlay_alias = overlay_profile || '-' || "
+            "REPLACE(mac, ':', '-') WHERE overlay_profile != '' AND overlay_alias = ''"
+        )
     # Retired 2026-07 pre-1.0: sanboot_drive was carried on the bind
     # form as an iPXE ``sanboot`` BIOS drive slug, but pixie never
     # actually rendered it into any iPXE template -- the ipxe-exit
@@ -255,16 +275,17 @@ class Machine:
     workaround on ONE target without dragging the deploy-wide default
     with it."""
     overlay_profile: str = ""
-    """Per-machine persistent-overlay profile name for ``nbdboot``.
-    Blank means "ephemeral tmpfs overlay" (the historical behaviour;
-    writes vanish on reboot). Non-blank names a qcow2 file kept under
-    ``data/overlays/<mac_slug>/<image_sha>/<profile>.qcow2``; writes
-    persist across reboots because the qcow2 is stored on pixie's
-    data volume. Multiple profiles can coexist per (machine, image)
-    -- the operator flips between them by editing this field. Only
-    consulted when ``boot_mode == 'nbdboot'``; other modes ignore
-    it. See :mod:`pixie.exports._store` for the overlay row + the
-    qcow2 lifecycle."""
+    """Legacy per-(mac,image) overlay profile name. Superseded by
+    ``overlay_alias``; kept only so a pre-re-model state.db still reads.
+    Not consulted by the renderer or UI anymore."""
+    overlay_alias: str = ""
+    """The globally-unique overlay ``alias`` this machine attaches for
+    ``boot_mode == 'nbdboot'``. Blank means "ephemeral tmpfs overlay"
+    (writes vanish on reboot). Non-blank names a persistent writable
+    volume (a qcow2 over a base image; see :mod:`pixie.exports._store`);
+    the overlay carries its own ``image_sha``, and the bind sets this
+    machine's ``image_content_sha256`` to match. Single-writer: at most
+    one machine holds an alias at a time (``Overlay.attached_mac``)."""
     inventory: dict[str, Any] = field(default_factory=dict)
     inventory_at: str = ""
     discovered_at: str = field(default_factory=now_iso)
@@ -288,8 +309,8 @@ class Machine:
             out["target_disk_serial"] = self.target_disk_serial
         if self.extra_cmdline:
             out["extra_cmdline"] = self.extra_cmdline
-        if self.overlay_profile:
-            out["overlay_profile"] = self.overlay_profile
+        if self.overlay_alias:
+            out["overlay_alias"] = self.overlay_alias
         if self.last_seen_ip:
             out["last_seen_ip"] = self.last_seen_ip
         if self.inventory:
@@ -338,7 +359,7 @@ class MachinesStore:
         labels: Sequence[str] | None = None,
         target_disk_serial: str = "",
         extra_cmdline: str = "",
-        overlay_profile: str = "",
+        overlay_alias: str = "",
     ) -> Machine:
         """Operator-driven write: set boot mode + optional image ref.
         Creates the row if it doesn't exist; preserves discovery
@@ -355,11 +376,12 @@ class MachinesStore:
         ``PIXIE_LIVE_ENV_EXTRA_CMDLINE`` fallback. Newlines are
         rejected so a stray paste can't smuggle a second cmdline into
         the iPXE render.
-        ``overlay_profile`` names a persistent qcow2 overlay for
-        ``nbdboot`` (blank = ephemeral tmpfs). The renderer + exports
-        supervisor materialise the qcow2 lazily on first plan render.
-        Must match a filesystem-safe subset so the on-disk filename
-        stays legible.
+        ``overlay_alias`` names a globally-unique persistent overlay for
+        ``nbdboot`` (blank = ephemeral tmpfs). The alias carries its own
+        base image; single-writer exclusivity + the alias<->image link
+        are enforced by the bind route (which also sets
+        ``image_content_sha256`` to the overlay's image). Must match a
+        filesystem-safe subset so the on-disk qcow2 name stays legible.
         """
         canon = normalise_mac(mac)
         if boot_mode not in BOOT_MODES:
@@ -373,10 +395,10 @@ class MachinesStore:
             raise ValueError(
                 "extra_cmdline must be a single line (newlines truncate the iPXE render)"
             )
-        overlay = (overlay_profile or "").strip()
-        if overlay and not _OVERLAY_PROFILE_RE.match(overlay):
+        overlay = (overlay_alias or "").strip()
+        if overlay and not OVERLAY_ALIAS_RE.match(overlay):
             raise ValueError(
-                "overlay_profile must be alphanumeric-leading; a-z / A-Z / 0-9 / . _ - "
+                "overlay_alias must be alphanumeric-leading; a-z / A-Z / 0-9 / . _ - "
                 "(max 64 chars); avoids filesystem escapes into the qcow2 storage path"
             )
 
@@ -417,7 +439,7 @@ class MachinesStore:
                     INSERT INTO machines (
                         mac, boot_mode, image_content_sha256,
                         labels, target_disk_serial, extra_cmdline,
-                        overlay_profile,
+                        overlay_alias,
                         discovered_at, last_seen_at, last_seen_ip, updated_at
                     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, '', ?)
                     """,
@@ -440,7 +462,7 @@ class MachinesStore:
                     UPDATE machines
                     SET boot_mode = ?, image_content_sha256 = ?,
                         labels = ?, target_disk_serial = ?,
-                        extra_cmdline = ?, overlay_profile = ?,
+                        extra_cmdline = ?, overlay_alias = ?,
                         updated_at = ?
                     WHERE mac = ?
                     """,
@@ -649,6 +671,9 @@ def _row(r: sqlite3.Row) -> Machine:
     overlay_profile = ""
     with contextlib.suppress(IndexError, KeyError):
         overlay_profile = r["overlay_profile"] or ""
+    overlay_alias = ""
+    with contextlib.suppress(IndexError, KeyError):
+        overlay_alias = r["overlay_alias"] or ""
     return Machine(
         mac=r["mac"],
         boot_mode=r["boot_mode"],
@@ -657,6 +682,7 @@ def _row(r: sqlite3.Row) -> Machine:
         target_disk_serial=target_serial,
         extra_cmdline=extra_cmdline,
         overlay_profile=overlay_profile,
+        overlay_alias=overlay_alias,
         inventory=inv,
         inventory_at=inv_at,
         discovered_at=r["discovered_at"],