Merge remote-tracking branch 'origin/main' into feat/247-foreign-workflows-pr2

utils/cached_runs.py

@@ -15,9 +15,14 @@ role (positive, negative, which Pair outputs are used) and what the hook
 already saw are recomputed from that job's own graph, and both paths count
 through the same ``own_counts`` so they cannot drift.
 
+The receipt also keeps the raw, prepend and append text the node gave the
+execution history (#403), so the history capture of a cached job can record
+the raw text the graph cannot show (``recorded_fields``) and the job becomes a
+tracked run of its prompt, as it is a counted one.
+
 Fail closed: when the cached text cannot be matched to a receipt recorded in
-this process, nothing is counted (the behavior before #347). In memory only and
-bounded; starts no threads.
+this process, nothing is counted (the behavior before #347) and the history
+fields stay unknown. In memory only and bounded; starts no threads.
 """
 
 import hashlib
@@ -39,6 +44,7 @@ try:
     from .queue_observers import subscribe_dequeue, subscribe_task_done
     from .run_keys import prompt_node_key, upstream_nodes
     from .usage_tracking import find_pair_id_by_hashes, survive_switch
+    from .execution_contexts import MAX_ATTEMPT_BYTES, MAX_FIELD_BYTES, text_size
 except ImportError:
     from utils.hashing import generate_prompt_hash
     from utils.logging_config import get_logger
@@ -53,6 +59,7 @@ except ImportError:
     from utils.queue_observers import subscribe_dequeue, subscribe_task_done
     from utils.run_keys import prompt_node_key, upstream_nodes
     from utils.usage_tracking import find_pair_id_by_hashes, survive_switch
+    from utils.execution_contexts import MAX_ATTEMPT_BYTES, MAX_FIELD_BYTES, text_size
 
 logger = get_logger("prompt_manager.cached_runs")
 
@@ -61,9 +68,15 @@ MAX_KEYS = 256  # run keys remembered (the same bound as MAX_KEYED_RUNS)
 MAX_RECEIPTS = 4  # receipts per run key: a recurring upstream value (A, B, A)
 MAX_ITEMS = 64  # list items per receipt (the cache reader's bound)
 MAX_CACHED_NODES = 500  # the execution_cached guard the history capture uses
+MAX_FIELD_TEXT_BYTES = 8 * 1024 * 1024  # history fields all receipts keep
+MAX_RECEIPT_FIELD_BYTES = MAX_ATTEMPT_BYTES  # one receipt: what one run's history holds
 _EMPTY_HASH = generate_prompt_hash("")
 
 Count = Tuple[Any, ...]  # ("prompt", hash) or ("pair", positive, negative or None)
+# (raw, prepend, append) per STRING slot, as given to record_runtime_context
+Fields = Tuple[Tuple[str, str, str], ...]
+# Executions with equal outputs recorded different fields: none can be named
+_CONFLICT: Fields = ()
 
 
 class Facts(NamedTuple):
@@ -96,6 +109,8 @@ class Seen(NamedTuple):
 class _Item(NamedTuple):
     outputs: Tuple[str, ...]
     facts: Facts
+    fields: Optional[Fields] = None
+    field_bytes: int = 0
 
 
 class _Receipt:
@@ -108,6 +123,18 @@ class _Receipt:
     def outputs(self) -> Dict[int, Tuple[str, ...]]:
         return {index: item.outputs for index, item in self.items.items()}
 
+    def field_bytes(self) -> int:
+        return sum(item.field_bytes for item in self.items.values())
+
+    def strip_fields(self) -> int:
+        """Drop the history fields (counting is unchanged); the bytes freed."""
+        freed = 0
+        for index, item in list(self.items.items()):
+            if item.field_bytes:
+                freed += item.field_bytes
+                self.items[index] = item._replace(fields=None, field_bytes=0)
+        return freed
+
 
 class _Attempt(NamedTuple):
     item_id: int
@@ -117,6 +144,22 @@ class _Attempt(NamedTuple):
     replayed: set
 
 
+def _field_size(fields: Any, slots: int) -> Optional[int]:
+    """UTF-8 size of well-formed fields for ``slots`` outputs, else None."""
+    if type(fields) is not tuple or len(fields) != slots:
+        return None
+    size = 0
+    for slot in fields:
+        if type(slot) is not tuple or len(slot) != 3:
+            return None
+        for value in slot:
+            try:
+                size += text_size(value, MAX_FIELD_BYTES)  # the capture's own check
+            except ValueError:
+                return None
+    return size
+
+
 def text_digest(value: str) -> str:
     """Digest of one returned STRING value, exactly as returned."""
     return hashlib.sha256(value.encode("utf-8", "surrogatepass")).hexdigest()
@@ -245,11 +288,14 @@ class CachedRuns:
         max_keys: int = MAX_KEYS,
         max_receipts: int = MAX_RECEIPTS,
         max_items: int = MAX_ITEMS,
+        max_field_bytes: int = MAX_FIELD_TEXT_BYTES,
         context: Callable[[], Tuple[Optional[str], Optional[int]]] = _host_context,
     ) -> None:
         self._max_keys = max_keys
         self._max_receipts = max_receipts
         self._max_items = max_items
+        self._max_field_bytes = max_field_bytes
+        self._field_bytes = 0  # UTF-8 bytes of the fields all receipts keep
         self._context = context
         self._receipts: "OrderedDict[str, List[_Receipt]]" = OrderedDict()
         self._attempt: Optional[_Attempt] = None
@@ -284,7 +330,10 @@ class CachedRuns:
                 self._attempt = None
             for run_key, receipts in self._receipts.items():
                 if receipts and receipts[0].item_id == item_id:
-                    self._receipts[run_key] = _deduplicated(receipts)
+                    before = _bytes(receipts)
+                    deduplicated = _deduplicated(receipts)
+                    self._field_bytes += _bytes(deduplicated) - before
+                    self._receipts[run_key] = deduplicated
 
     def _current(self) -> Tuple[Optional[_Attempt], Optional[int]]:
         """The attempt the executing node belongs to, and its list index."""
@@ -305,8 +354,19 @@ class CachedRuns:
         with self._lock:
             return str(node_id) in attempt.replayed
 
-    def record_item(self, node_id: Any, outputs: Tuple[Any, ...], facts: Facts) -> None:
-        """Remember what this execution returned and was entitled to count."""
+    def record_item(
+        self,
+        node_id: Any,
+        outputs: Tuple[Any, ...],
+        facts: Facts,
+        fields: Optional[Fields] = None,
+    ) -> None:
+        """Remember what this execution returned and was entitled to count.
+
+        ``fields`` are the texts the node gave the execution history, one
+        ``(raw, prepend, append)`` per output; kept only when well formed,
+        each within the history's field limit and the store within its budget.
+        """
         try:
             attempt, index = self._current()
             node = attempt.nodes.get(str(node_id)) if attempt else None
@@ -317,14 +377,20 @@ class CachedRuns:
                 return
             if any(not isinstance(value, str) for value in outputs):
                 return
-            item = _Item(tuple(text_digest(value) for value in outputs), facts)
+            size = _field_size(fields, len(outputs)) if fields is not None else None
+            item = _Item(
+                tuple(text_digest(value) for value in outputs),
+                facts,
+                fields if size is not None else None,
+                size or 0,
+            )
             self._store(node[1], attempt.item_id, index, item)
         except Exception as error:
             logger.debug(f"Could not record a cached-run receipt: {error}")
 
     def _store(self, run_key: str, item_id: int, index: int, item: _Item) -> None:
         with self._lock:
-            receipts = self._receipts.pop(run_key, [])
+            receipts = self._take(run_key)
             if receipts and receipts[0].item_id == item_id:
                 receipt = receipts[0]
             else:
@@ -334,9 +400,44 @@ class CachedRuns:
                 receipt = _Receipt(item_id)
                 receipts.insert(0, receipt)
             receipt.items[index] = item
-            self._receipts[run_key] = receipts[: self._max_receipts]
+            receipts = receipts[: self._max_receipts]
+            if item.field_bytes and (
+                receipt.field_bytes() > MAX_RECEIPT_FIELD_BYTES
+                or not self._make_room(_bytes(receipts))
+            ):
+                # Counting is as before; this job's history fields stay unknown
+                receipt.items[index] = item._replace(fields=None, field_bytes=0)
+            self._put(run_key, receipts)
             while len(self._receipts) > self._max_keys:
-                self._receipts.popitem(last=False)
+                _, dropped = self._receipts.popitem(last=False)
+                self._field_bytes -= _bytes(dropped)
+
+    def _make_room(self, needed: int) -> bool:
+        """Free the fields of the least recently used receipts (under the lock).
+
+        Old receipts of workflows never run again must not hold the budget:
+        their counting stays, only their history fields go. False when
+        ``needed`` does not fit even then.
+        """
+        if needed > self._max_field_bytes:
+            return False
+        for receipts in self._receipts.values():  # least recently used first
+            if self._field_bytes + needed <= self._max_field_bytes:
+                break
+            for receipt in receipts:
+                self._field_bytes -= receipt.strip_fields()
+        return self._field_bytes + needed <= self._max_field_bytes
+
+    def _take(self, run_key: str) -> List[_Receipt]:
+        """Remove a key's receipts and their bytes from the store (under the lock)."""
+        receipts = self._receipts.pop(run_key, [])
+        self._field_bytes -= _bytes(receipts)
+        return list(receipts)
+
+    def _put(self, run_key: str, receipts: List[_Receipt]) -> None:
+        """Store a key's receipts as the most recently used (under the lock)."""
+        self._receipts[run_key] = receipts
+        self._field_bytes += _bytes(receipts)
 
     # -- cached nodes -------------------------------------------------------
 
@@ -393,25 +494,11 @@ class CachedRuns:
 
     def _match(self, run_key: str, values: Any) -> Optional[List[_Item]]:
         """The items of the one receipt whose outputs equal ``values``, in order."""
-        if not values:
-            return None
-        length = len(values[0])
-        if length == 0 or length > self._max_items:
-            return None
-        if any(len(slot) != length for slot in values):
-            return None
-        wanted = {
-            index: tuple(text_digest(slot[index]) for slot in values)
-            for index in range(length)
-        }
         with self._lock:
-            receipts = self._receipts.get(run_key)
-            if not receipts:
-                return None
-            matches = [receipt for receipt in receipts if receipt.outputs() == wanted]
+            matches = self._matching(run_key, values)
             if not matches:
                 return None
-            self._receipts.move_to_end(run_key)
+            length = len(values[0])
             facts = {
                 tuple(receipt.items[index].facts for index in range(length))
                 for receipt in matches
@@ -420,13 +507,99 @@ class CachedRuns:
                 return None
             return [matches[0].items[index] for index in range(length)]
 
+    def _matching(self, run_key: str, values: Any) -> List[_Receipt]:
+        """Receipts of ``run_key`` whose outputs equal ``values`` (under the lock)."""
+        if type(values) not in (list, tuple) or not values:
+            return []
+        if any(type(slot) not in (list, tuple) for slot in values):
+            return []
+        length = len(values[0])
+        if length == 0 or length > self._max_items:
+            return []
+        if any(len(slot) != length for slot in values):
+            return []
+        if any(type(value) is not str for slot in values for value in slot):
+            return []
+        wanted = {
+            index: tuple(text_digest(slot[index]) for slot in values)
+            for index in range(length)
+        }
+        receipts = self._receipts.get(run_key)
+        if not receipts:
+            return []
+        matches = [receipt for receipt in receipts if receipt.outputs() == wanted]
+        if matches:
+            self._receipts.move_to_end(run_key)
+        return matches
+
+    # -- the history capture (#403) -------------------------------------------
+
+    def recorded_fields(
+        self, prompt_id: Any, node_id: Any, values: Any
+    ) -> Optional[List[Fields]]:
+        """The history fields of the execution a cached node reuses, per list item.
+
+        ``values`` are the node's cached STRING outputs (``cached_string_outputs``).
+        Only for a node of the job currently executing, and only when every
+        receipt matching ``values`` kept the same fields; None otherwise. Never
+        counts and never marks the node replayed.
+        """
+        try:
+            with self._lock:
+                attempt = self._attempt
+                if (
+                    attempt is None
+                    or type(prompt_id) is not str
+                    or prompt_id != attempt.prompt_id
+                    or type(node_id) is not str
+                    or node_id not in attempt.nodes
+                ):
+                    return None
+                matches = self._matching(attempt.nodes[node_id][1], values)
+                if not matches:
+                    return None
+                found = []
+                for index in range(len(values[0])):
+                    fields = {receipt.items[index].fields for receipt in matches}
+                    if len(fields) != 1 or None in fields or _CONFLICT in fields:
+                        return None
+                    found.append(fields.pop())
+                return found
+        except Exception as error:
+            logger.debug(f"Could not read a cached run's history fields: {error}")
+            return None
+
 
 def _deduplicated(receipts: List[_Receipt]) -> List[_Receipt]:
-    """The newest receipt replaces older ones with the same outputs."""
+    """The newest receipt replaces older ones with the same outputs.
+
+    Counting needs only the outputs. When a replaced receipt recorded other
+    history fields for equal outputs (a raw text the outputs do not show),
+    the newest item's fields become a conflict, so no cached job of it is
+    given either text (#403). A conflict stays until the run key is dropped.
+    """
     if not receipts:
         return receipts
-    outputs = receipts[0].outputs()
-    return [receipts[0]] + [r for r in receipts[1:] if r.outputs() != outputs]
+    newest, outputs = receipts[0], receipts[0].outputs()
+    kept = [newest]
+    for receipt in receipts[1:]:
+        if receipt.outputs() != outputs:
+            kept.append(receipt)
+            continue
+        for index, item in list(newest.items.items()):
+            older = receipt.items[index].fields
+            if older == _CONFLICT or (
+                older is not None and item.fields is not None and older != item.fields
+            ):
+                newest.items[index] = item._replace(fields=_CONFLICT, field_bytes=0)
+    return kept
+
+
+def _bytes(receipts: List[_Receipt]) -> int:
+    """UTF-8 bytes of the history fields ``receipts`` keep."""
+    return sum(
+        item.field_bytes for receipt in receipts for item in receipt.items.values()
+    )
 
 
 def _job_nodes(graph: Dict[str, Any], outputs: Any) -> Dict[str, Tuple[str, str]]:

utils/execution_context_host.py

@@ -151,10 +151,77 @@ def cached_string_outputs(
         return None
 
 
+def _receipt_fields(
+    receipts: object, executor: object, job_id: str, source: object
+) -> list | None:
+    """Per list index, the ``(raw, prepend, append)`` of the execution reused (#403).
+
+    From the #347 receipt whose digests equal every STRING slot of the cache
+    entry; None when there is none or the answer is malformed.
+    """
+    try:
+        if receipts is None:
+            try:
+                from .cached_runs import CACHED_RUNS as receipts
+            except ImportError:
+                from utils.cached_runs import CACHED_RUNS as receipts
+        values = cached_string_outputs(executor, source.node_id, source.node_type)
+        if values is None:
+            return None
+        found = receipts.recorded_fields(job_id, source.node_id, values)
+        if type(found) is not list or len(found) != len(values[0]):
+            return None
+        position = (
+            (1 if source.output_slot in (1, 3) else 0)
+            if source.node_type == "PromptManagerPair"
+            else 0
+        )
+        fields = []
+        for slots in found:
+            slot = slots[position] if type(slots) is tuple else None
+            if not (
+                type(slot) is tuple
+                and len(slot) == 3
+                and all(type(value) is str for value in slot)
+            ):
+                return None
+            fields.append(slot)
+        return fields
+    except Exception:
+        return None
+
+
+def _agrees(inferred: PromptSnapshot, fields: tuple) -> bool:
+    """Every field the graph knows equals the receipt's; else fill nothing."""
+    known = (inferred.raw, inferred.prepend, inferred.append)
+    return all(
+        field.value is None or field.value == value
+        for field, value in zip(known, fields)
+    )
+
+
+def _filled(inferred: TextEvidence, value: str) -> TextEvidence:
+    """A field the graph cannot show, taken from the reused execution (#403)."""
+    if inferred.value is not None:
+        return inferred
+    return TextEvidence(value, "inferred", "graph_semantics", None)
+
+
 def observe_cached_context(
-    executor: object, message_type: object, message_data: object
+    executor: object,
+    message_type: object,
+    message_data: object,
+    *,
+    receipts: object = None,
 ) -> None:
-    """Copy bounded local strings without cache/provider execution or retention."""
+    """Copy bounded local strings without cache/provider execution or retention.
+
+    Raw, prepend and append come from graph inference; a field it leaves
+    unknown (runtime-only text) is taken from the receipt of the execution the
+    cache entry is proven to come from (``CachedRuns.recorded_fields``), so the
+    cached job is a tracked run of its prompt (#403). ``receipts`` defaults to
+    the process ``CACHED_RUNS``.
+    """
     try:
         binding = active_capture()
         if binding is None or type(message_type) is not str:
@@ -198,18 +265,29 @@ def observe_cached_context(
             inferred = manager.source_snapshot(cap, source)
             if inferred is None:
                 continue
+            fields = None
+            if any(
+                field.value is None
+                for field in (inferred.raw, inferred.prepend, inferred.append)
+            ):
+                fields = _receipt_fields(receipts, executor, cap.job_id, source)
             for index, value in enumerate(values):
                 if type(value) is not str:
                     continue
+                raw, prepend, append = inferred.raw, inferred.prepend, inferred.append
+                if fields is not None and _agrees(inferred, fields[index]):
+                    raw = _filled(raw, fields[index][0])
+                    prepend = _filled(prepend, fields[index][1])
+                    append = _filled(append, fields[index][2])
                 manager.observe(
                     cap,
                     source,
                     index,
                     PromptSnapshot(
-                        inferred.raw,
+                        raw,
                         TextEvidence(value, "recorded", "host_cache_output", None),
-                        inferred.prepend,
-                        inferred.append,
+                        prepend,
+                        append,
                     ),
                 )
     except Exception:

utils/workspace_keys.py

@@ -0,0 +1,213 @@
+"""The per-install secret behind the workspace's gallery scopes and cursors (#430).
+
+A page addresses a listed file as ``{root_index, root_scope, path}``. The root
+scope is an HMAC over the root's index and canonical path, so the server can
+refuse an action aimed at a root that was renumbered or replaced since the page
+listed it (``py/api/images.py`` ``_gallery_scope_error``). The listing's keyset
+cursors are MACed with a second key, so a forged position never reaches the
+sort code.
+
+Both keys used to be drawn per process, so every ComfyUI restart made every
+open workspace tab stale. They now derive from one random secret persisted in
+``workspace-scope.key`` beside the database (never in ``config.json`` and never
+in the database, so a backup or an export does not carry it). When the folder
+cannot hold it, the process falls back to a per-process secret, as before.
+
+Standard library only: a fresh process can derive the same scope without
+importing the API.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+import os
+import re
+import secrets
+import stat
+import time
+from typing import NamedTuple
+
+logger = logging.getLogger("prompt_manager.api")
+
+KEY_FILE_NAME = "workspace-scope.key"
+SECRET_BYTES = 32
+_HEX = re.compile(r"[0-9a-fA-F]{64}")
+# Bounded read: a valid file is 64 hex characters and a newline.
+_MAX_FILE_BYTES = 128
+_ROOT_SCOPE_PURPOSE = b"prompt-manager/gallery-root-scope/v1"
+_CURSOR_PURPOSE = b"prompt-manager/workspace-cursor/v1"
+_SCOPE_TAG = "prompt-manager-gallery-root-v1"
+_TEMP_PREFIX = f".{KEY_FILE_NAME}."
+_TEMP_SUFFIX = ".tmp"
+_STALE_TEMP_SECONDS = 60
+
+
+class WorkspaceKeys(NamedTuple):
+    """The derived keys; ``persisted`` is False for a per-process fallback."""
+
+    root_scope: bytes
+    cursor: bytes
+    persisted: bool
+
+
+def _read(path: str) -> bytes | None:
+    """The secret in *path*, None when it is missing or not 64 hex characters.
+
+    Raises OSError for anything but a missing file (a folder, no permission).
+    """
+    try:
+        with open(path, "rb") as handle:
+            raw = handle.read(_MAX_FILE_BYTES + 1)
+    except FileNotFoundError:
+        return None
+    try:
+        text = raw.decode("ascii").strip()
+    except UnicodeDecodeError:
+        return b""
+    return bytes.fromhex(text) if _HEX.fullmatch(text) else b""
+
+
+def _write_exclusive(path: str, secret: bytes) -> None:
+    """Create *path* (it must not exist) holding *secret*, owner-only, fsynced."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+    descriptor = os.open(path, flags, 0o600)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write((secret.hex() + "\n").encode("ascii"))
+            handle.flush()
+            os.fsync(handle.fileno())
+    except BaseException:
+        _unlink(path)
+        raise
+
+
+def _unlink(path: str) -> None:
+    try:
+        os.unlink(path)
+    except OSError:
+        pass
+
+
+def _sweep_temps(directory: str) -> None:
+    """Remove temp files a crashed first start left (older than a minute)."""
+    try:
+        names = os.listdir(directory)
+    except OSError:
+        return
+    cutoff = time.time() - _STALE_TEMP_SECONDS
+    for name in names:
+        if name.startswith(_TEMP_PREFIX) and name.endswith(_TEMP_SUFFIX):
+            path = os.path.join(directory, name)
+            try:
+                if os.stat(path).st_mtime < cutoff:
+                    os.unlink(path)
+            except OSError:
+                pass
+
+
+def _tighten(path: str) -> None:
+    """On POSIX an existing key readable by group or others becomes 0o600."""
+    if os.name != "posix":
+        return  # the file inherits the folder's ACL, as the database does
+    try:
+        if stat.S_IMODE(os.stat(path).st_mode) & 0o077:
+            os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _store(directory: str, path: str, secret: bytes, *, replace: bool) -> None:
+    """Publish *secret* at *path*; a new file never overwrites a concurrent winner.
+
+    The secret is written to a temp file first. ``os.link`` then fails when
+    *path* exists, so of two first starts exactly one file wins
+    (FileExistsError for the other). A file system without hard links (FAT,
+    some shares) creates *path* with ``O_EXCL`` instead. *replace* (a corrupt
+    key) swaps the file with ``os.replace``; Windows refuses that while
+    another process holds the file open, which the caller treats as unusable.
+    """
+    temp = os.path.join(
+        directory, f"{_TEMP_PREFIX}{secrets.token_hex(8)}{_TEMP_SUFFIX}"
+    )
+    _write_exclusive(temp, secret)
+    try:
+        if replace:
+            os.replace(temp, path)
+            return
+        try:
+            os.link(temp, path)
+        except FileExistsError:
+            raise
+        except OSError:
+            # Not atomic: a second first start reading mid-write would see a
+            # corrupt key. Rare (two first starts on FAT or a share at once);
+            # each process still uses the file it reads back.
+            _write_exclusive(path, secret)
+    finally:
+        _unlink(temp)
+
+
+def load_install_secret(directory: str) -> bytes | None:
+    """The persisted secret of *directory*, created on first use; None if unusable.
+
+    After any write the file is read back and its content is what counts, so
+    processes racing on a first start end with the one secret on disk.
+    """
+    path = os.path.join(directory, KEY_FILE_NAME)
+    try:
+        _sweep_temps(directory)
+        current = _read(path)
+        if current:
+            _tighten(path)
+            return current
+        corrupt = current is not None
+        try:
+            _store(directory, path, secrets.token_bytes(SECRET_BYTES), replace=corrupt)
+        except FileExistsError:
+            pass  # another process created it first: its file counts
+        stored = _read(path)
+        if not stored:
+            raise OSError(f"{KEY_FILE_NAME} is not readable after it was written")
+        if corrupt:
+            logger.warning(
+                f"{KEY_FILE_NAME} was not a valid key and was replaced; "
+                "open workspace pages must refresh once"
+            )
+        return stored
+    except OSError as exc:
+        logger.warning(f"Could not use {KEY_FILE_NAME}: {exc.__class__.__name__}")
+        return None
+
+
+def _derive(secret: bytes, purpose: bytes) -> bytes:
+    return hmac.new(secret, purpose, hashlib.sha256).digest()
+
+
+def workspace_keys_for(db_path: str | None) -> WorkspaceKeys:
+    """The keys for the library whose database is *db_path* (blocking I/O)."""
+    secret = None
+    if isinstance(db_path, str) and db_path.strip() and db_path != ":memory:":
+        secret = load_install_secret(os.path.dirname(os.path.abspath(db_path)))
+    persisted = secret is not None
+    if not persisted:
+        logger.warning(
+            "Workspace scopes use a per-process key: open workspace pages must "
+            "refresh after a restart"
+        )
+        secret = secrets.token_bytes(SECRET_BYTES)
+    return WorkspaceKeys(
+        _derive(secret, _ROOT_SCOPE_PURPOSE),
+        _derive(secret, _CURSOR_PURPOSE),
+        persisted,
+    )
+
+
+def gallery_root_scope(keys: WorkspaceKeys, canonical_root: str, index: int) -> str:
+    """The 64-hex scope of the root at *index* (its canonical path string)."""
+    payload = json.dumps(
+        [_SCOPE_TAG, index, canonical_root], separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+    return hmac.new(keys.root_scope, payload, hashlib.sha256).hexdigest()