Fix

Author: inecik

docs/user_guide/web_app/l_sessions_sharing/01_session_mental_model.md

@@ -72,11 +72,13 @@ Practical implication:
 3) Open **Session** → **Session state**.
 4) Click **Save State**.
 5) Find the downloaded file (usually in your Downloads folder).
-6) Send the file to your collaborator **together with the dataset export folder** (or tell them where the dataset is hosted).
+6) Send the file to your collaborator. A session saved on a sample, a data link
+   or a server records where the dataset is and opens it; for a dataset opened
+   from your own computer, send the dataset export folder with it.
 
-To reopen later:
-1) Load the same dataset again.
-2) Click **Load State** and pick your `.cellucid-session` file.
+To reopen later, click **Load State** and pick your `.cellucid-session` file.
+Its dataset opens first if it is not open already; a session saved on a local
+file needs that file opened again before it is loaded.
 
 ---
 

docs/user_guide/web_app/l_sessions_sharing/03_save_restore_ux.md

@@ -28,8 +28,8 @@ In the left sidebar:
 :width: 524px
 
 The **Session** accordion. Everything that brings a dataset in sits above, and
-**Session state** sits at the bottom — the order matches the rule that the
-dataset must be loaded before a session is restored onto it.
+**Session state** sits at the bottom — a session is restored onto a dataset,
+which Load State opens first when the session records where it is.
 ```
 
 ---
@@ -66,12 +66,22 @@ save time, so repeated saves never overwrite each other.
 
 ### Load State
 
-1) Load the same dataset first.
-2) Click **Load State**.
-3) Choose the `.cellucid-session` file.
-4) Wait for the restore's progress notification to finish as **Loaded** with
+1) Click **Load State**.
+2) Choose the `.cellucid-session` file.
+3) Wait for the restore's progress notification to finish as **Loaded** with
    **Session fully restored.**
 
+A session records where its dataset was opened from: a sample dataset, a data
+link (**Open from link** or `?data=`), or a Cellucid server. When another
+dataset — or none — is open, Load State opens that one first ("Opening the
+session's dataset from …") and then applies the session. A session saved on a
+dataset opened from your own computer or in a notebook records no source:
+open that dataset yourself before loading the session.
+
+A session saved on a link records the link. A link that carries its own access
+key — a Dropbox share link, a signed bucket address — is then in the session
+file too, so share such a session only with people who may open the data.
+
 If a dataset is still loading when you choose the file, a notification says
 the session is waiting for it, and the session is applied as soon as that
 dataset has loaded. Choosing another dataset in the meantime means the session
@@ -228,9 +238,12 @@ to fail the whole restore rather than diverge quietly.
 
 ### 1) Treat the dataset + session as a pair
 
-Because sessions do not contain the dataset:
+Sessions do not contain the dataset. A session saved on a sample, a data link
+or a server points to it and opens it; one saved on a local file or in a
+notebook does not:
 - store the `.cellucid-session` file next to the dataset export folder,
-- or store a clear pointer to where the dataset is hosted (URL/GitHub path).
+- or host the dataset (see {doc}`../b_data_loading/14_open_from_link`) and save
+  the session on the hosted copy, so the session opens it by itself.
 
 ### 2) Use a naming convention that encodes intent
 

docs/user_guide/web_app/l_sessions_sharing/12_reference.md

@@ -25,7 +25,7 @@ identity before reporting success.
 
 ## Exact manifest
 
-The root has exactly `createdAt`, `datasetFingerprint`, and `chunks`:
+The root has exactly `createdAt`, `datasetFingerprint`, `source`, and `chunks`:
 
 ```json
 {
@@ -57,11 +57,20 @@ The root has exactly `createdAt`, `datasetFingerprint`, and `chunks`:
       "vectorFields": []
     }
   },
+  "source": { "kind": "sample", "dataset": "suo" },
   "chunks": []
 }
 ```
 
 - `createdAt` is a canonical ISO timestamp.
+- `source` says where the dataset was opened from, so **Load State** can open
+  it first: `{"kind": "sample", "dataset"}` for a sample of the page's
+  catalog, `{"kind": "link", "locator", "dataset"}` for a data link (the
+  `locator` is the `?data=` value, see {doc}`../b_data_loading/14_open_from_link`),
+  `{"kind": "remote", "url", "dataset"}` for a Cellucid server, or `null` for a
+  local file or a notebook, which nobody else can open from the session alone.
+  A published sample view's `source` is always `null`. It is only a pointer:
+  the fingerprint, not the source, decides whether the session applies.
 - `datasetFingerprint` has exactly `datasetId`, `cellCount`, `varCount`,
   `cellOrder`, and `dataMapping`.
 - `cellOrder` has exactly `embedding`, `dimension`, and `digest`. `embedding` is

docs/user_guide/web_app/p_developer_docs/10_sessions_persistence_and_serialization.md

@@ -56,7 +56,12 @@ The container is:
 4. for every manifest chunk, an unsigned 32-bit stored length plus exact stored
    payload bytes.
 
-The manifest has exactly `createdAt`, `datasetFingerprint`, and `chunks`.
+The manifest has exactly `createdAt`, `datasetFingerprint`, `source`, and
+`chunks`. `source` (`session/dataset-source-record.js`) is where the dataset
+was opened from — a sample, a data link's locator or a server address, with
+the dataset id — or `null`; **Load State** reads only the manifest first and,
+when another dataset (or none) is open, opens that source through the same
+connection controls a person would use before the restore runs.
 `datasetFingerprint` has exactly `datasetId`, `cellCount`, `varCount`,
 `cellOrder`, and `dataMapping`. `cellOrder` has exactly `embedding`
 (the embedding reference of the layout the live view shows), `dimension` (that

docs/user_guide/web_app/r_screenshot_checklist/06_pages_developer.md

@@ -319,7 +319,7 @@ Secondary (cheaper, complements it): a **DIAGRAM** of the coordinator's import g
 
 **needs** — Two diagrams. Both describe byte-level and control-flow contracts, which is the one category of diagram that does **not** rot with refactors — it changes only when the format breaks, and a format break is exactly when the docs must be rewritten anyway.
 
-*(a) Container byte-layout figure.* A horizontal byte-ribbon, left to right: `"CELLUCID_SESSION\n"` (magic) │ `u32 LE manifest length` │ `manifest JSON (UTF-8, exactly that many bytes)` │ then a repeating group `u32 LE stored length` │ `stored payload bytes` × N chunks. Below the ribbon, an expansion of the manifest object showing its exactly-three keys (`createdAt`, `datasetFingerprint`, `chunks`), the fingerprint's exactly-five keys, and a chunk's exactly-nine keys. Derived from: `cellucid/assets/js/app/session/bundle/format.js` (framing) and `session/session-context.js` (`getDatasetFingerprint`). This turns `:51–74` — currently three dense paragraphs a reader must reconstruct mentally — into one glance.
+*(a) Container byte-layout figure.* A horizontal byte-ribbon, left to right: `"CELLUCID_SESSION\n"` (magic) │ `u32 LE manifest length` │ `manifest JSON (UTF-8, exactly that many bytes)` │ then a repeating group `u32 LE stored length` │ `stored payload bytes` × N chunks. Below the ribbon, an expansion of the manifest object showing its exactly-four keys (`createdAt`, `datasetFingerprint`, `source`, `chunks`), the fingerprint's exactly-five keys, and a chunk's exactly-nine keys. Derived from: `cellucid/assets/js/app/session/bundle/format.js` (framing) and `session/session-context.js` (`getDatasetFingerprint`). This turns `:51–74` — currently three dense paragraphs a reader must reconstruct mentally — into one glance.
 
 *(b) Restore pipeline with the rollback edge.* Ten numbered steps down the page as stated at `:127–139` (supersede → frame under limits → validate manifest/profile/fingerprint → register reversible snapshots → eager decode/apply → lazy decode/apply → prepare all participants → commit in order → final UI refresh → publish "Session fully restored"), with a **red return edge** from any step back through "rollback in reverse participant order". The all-or-nothing property (`:24`, `:142–143`) is the page's most important claim and the reverse edge is the only way to show it. Derived from `session/session-serializer.js`.
 

src/cellucid/anndata_session/_chunks.py

@@ -84,7 +84,7 @@ def _validate_current_chunk_inventory(
 ) -> _CurrentChunkInventory:
     manifest = _require_exact_keys(
         bundle.manifest,
-        {"createdAt", "datasetFingerprint", "chunks"},
+        {"createdAt", "datasetFingerprint", "source", "chunks"},
         label="bundle.manifest",
     )
     if manifest["datasetFingerprint"] != bundle.dataset_fingerprint:

src/cellucid/session_bundle.py

@@ -8,8 +8,8 @@
 3) manifest JSON bytes (UTF-8)
 4) repeated chunks: [chunkByteLength (u32 LE), chunkBytes...]
 
-The manifest contains exactly ``createdAt``, ``datasetFingerprint``, and ordered
-``chunks`` metadata. Chunk payloads are either JSON or binary and may be
+The manifest contains exactly ``createdAt``, ``datasetFingerprint``, ``source``
+(where the dataset can be opened from, or null) and ordered ``chunks`` metadata. Chunk payloads are either JSON or binary and may be
 gzip-compressed.
 """
 
@@ -43,8 +43,18 @@
 _MANIFEST_KEYS = {
     "createdAt",
     "datasetFingerprint",
+    "source",
     "chunks",
 }
+# Where the session's dataset can be opened from, so loading the session in the
+# viewer can open it first: a sample of the page's catalog, a data link (its
+# ``?data=`` value) or a Cellucid server. Null for a local file or a notebook.
+_SOURCE_KEYS_BY_KIND = {
+    "sample": {"kind", "dataset"},
+    "link": {"kind", "locator", "dataset"},
+    "remote": {"kind", "url", "dataset"},
+}
+_CONTROL_CHARACTER_RE = re.compile(r"[\x00-\x1f\x7f]")
 # The fingerprint ties a session to one dataset and to one data mapping, not to
 # the route the dataset was opened through. Every key is required: the viewer
 # refuses a session without its cell-order record, and a reader that accepted
@@ -206,6 +216,36 @@ def _validate_cell_order(value: Any, *, kind: str) -> dict[str, Any]:
     return {"embedding": embedding, "dimension": dimension, "digest": digest}
 
 
+def _validate_text(value: Any, label: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not value
+        or value != value.strip()
+        or _CONTROL_CHARACTER_RE.search(value) is not None
+    ):
+        raise ValueError(f"Invalid session manifest ({label} must be a non-empty, unpadded string)")
+    return value
+
+
+def _validate_source(value: Any) -> dict[str, str] | None:
+    """Validate the recorded dataset source (the viewer's dataset-source-record)."""
+    if value is None:
+        return None
+    kind = value.get("kind") if isinstance(value, dict) else None
+    keys = _SOURCE_KEYS_BY_KIND.get(kind) if isinstance(kind, str) else None
+    if keys is None:
+        raise ValueError('Invalid session manifest (source kind must be "sample", "link" or "remote")')
+    if set(value) != keys:
+        raise ValueError(
+            "Invalid session manifest (source fields must be exactly " + ", ".join(sorted(keys)) + ")"
+        )
+    for key in sorted(keys - {"kind"}):
+        _validate_text(value[key], f"source.{key}")
+    if kind == "remote" and not value["url"].startswith(("https://", "http://")):
+        raise ValueError("Invalid session manifest (source.url must be an http(s) address)")
+    return dict(value)
+
+
 def _validate_manifest(manifest: Any) -> list[dict[str, Any]]:
     if not isinstance(manifest, dict):
         raise ValueError("Invalid session manifest (expected an object)")
@@ -224,6 +264,7 @@ def _validate_manifest(manifest: Any) -> list[dict[str, Any]]:
             "Invalid session manifest (createdAt must be an exact UTC millisecond timestamp)"
         )
     _validate_fingerprint(manifest["datasetFingerprint"])
+    _validate_source(manifest["source"])
 
     chunks = manifest["chunks"]
     if not isinstance(chunks, list):
@@ -402,6 +443,18 @@ def dataset_fingerprint(self) -> dict[str, Any]:
         assert isinstance(fp, dict)
         return fp
 
+    @property
+    def dataset_source(self) -> dict[str, str] | None:
+        """Where the session's dataset was opened from, or ``None``.
+
+        ``{"kind": "sample", "dataset"}``, ``{"kind": "link", "locator",
+        "dataset"}`` (``locator`` is the ``?data=`` value) or ``{"kind":
+        "remote", "url", "dataset"}``; ``None`` for a session saved on a local
+        file or in a notebook.
+        """
+        source = self.manifest["source"]
+        return None if source is None else dict(source)
+
     def list_chunk_ids(self) -> list[str]:
         self._ensure_indexed()
         assert self._chunks_by_id is not None

tests/test_feature_docs_exact_contract.py

@@ -401,7 +401,7 @@ def test_session_docs_publish_only_the_atomic_current_contract() -> None:
     developer_normalized = " ".join(developer.split())
 
     for exact in (
-        "`createdAt`, `datasetFingerprint`, and `chunks`",
+        "`createdAt`, `datasetFingerprint`, `source`, and `chunks`",
         # The fingerprint carries five fields: the viewer records a `cellOrder`
         # digest so a dataset republished re-sorted under an unchanged identity
         # cannot silently re-point saved selections, and the data mapping the

tests/test_jupyter_event_security_contract.py

@@ -271,6 +271,7 @@ def _empty_session_bundle() -> bytes:
     manifest = {
         "createdAt": "2026-07-26T00:00:00.000Z",
         "datasetFingerprint": _FINGERPRINT,
+        "source": None,
         "chunks": [],
     }
     manifest_bytes = json.dumps(
@@ -287,6 +288,7 @@ def _corrupt_gzip_session_bundle() -> bytes:
     manifest = {
         "createdAt": "2026-07-26T00:00:00.000Z",
         "datasetFingerprint": _FINGERPRINT,
+        "source": None,
         "chunks": [
             {
                 "id": "corrupt",

tests/test_session_data_mapping_contract.py

@@ -77,6 +77,7 @@ def __init__(self, fingerprint: dict[str, Any], fields: list[dict[str, Any]] | N
         self.manifest = {
             "createdAt": "2026-10-18T00:00:00.000Z",
             "datasetFingerprint": fingerprint,
+            "source": None,
             "chunks": chunks,
         }