hypernote 0.3.0__tar.gz → 0.4.0__tar.gz

{hypernote-0.3.0 → hypernote-0.4.0}/AGENTS.md

@@ -40,7 +40,7 @@ Hypernote owns a thin control plane:
 
 Core rule: notebook edits and execution must operate on one logical document truth whether JupyterLab is closed, already open, or opened mid-run.
 
-Lifecycle rule: notebook contents and outputs persist through Jupyter's `.ipynb` model, but Hypernote's runtime state, job records, and cell attribution are intentionally in-memory and notebook-scoped.
+Lifecycle rule: notebook contents and outputs persist through Jupyter's `.ipynb` model, but Hypernote's runtime state, job records, cell attribution, and `setup serve` collaboration journal are intentionally ephemeral and notebook- or server-scoped.
 
 Concurrent-actor rule: JupyterLab and Hypernote share one notebook session and one kernel. Hypernote-driven cells run in an ipykernel subshell so the kernel's main shell stays responsive to native Lab actions. Hypernote's extension overrides `/api/kernels/{id}/interrupt` and `/api/kernels/{id}/restart` so Lab's Stop and Restart toolbar buttons reach the subshell-routed cell or perform the right cleanup. See [dev/current-architecture.md](dev/current-architecture.md) for the full mechanism.
 

{hypernote-0.3.0 → hypernote-0.4.0}/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 0.4.0 - 2026-05-10
+
+Hypernote now treats Jupyter's real-time collaboration journal as temporary
+server-local state for `setup serve`, keeping the `.ipynb` notebook file as the
+only durable project artifact.
+
+### Changed
+
+- `hypernote setup serve` now configures Jupyter RTC to use temporary
+  collaboration journal storage instead of Jupyter's default project-root
+  `.jupyter_ystore.db` SQLite database.
+- Live-server and browser regression fixtures now launch with the same
+  temporary journal policy as `setup serve`, including coverage that notebook
+  execution does not create `.jupyter_ystore.db` in the server root.
+- Project guidance now distinguishes the durable **Notebook File** from the
+  temporary **Collaboration Journal**, and documents the crash-recovery tradeoff
+  for unsaved live shared-document changes.
+
 ## 0.3.0 - 2026-05-10
 
 Hypernote is now a JupyterLab-first integration: the default install carries the

{hypernote-0.3.0 → hypernote-0.4.0}/CONTEXT.md

@@ -9,6 +9,14 @@ server so agents and humans can work against one notebook truth.
 The server-side notebook document that all Hypernote operations use as the live notebook truth.
 _Avoid_: file-only notebook truth
 
+**Notebook File**:
+The `.ipynb` artifact that persists notebook contents and outputs after the Shared Document is saved.
+_Avoid_: Hypernote database, collaboration store, job history
+
+**Collaboration Journal**:
+The Jupyter real-time collaboration update store used as recoverability cache for live Shared Document state.
+_Avoid_: notebook primary storage, Hypernote job history, attribution store
+
 **Hypernote JupyterLab Server**:
 A JupyterLab server launched or verified with Hypernote's required server and collaboration extensions.
 _Avoid_: plain Jupyter server, separate agent server
@@ -24,6 +32,8 @@ _Avoid_: separate runtime mode
 ## Relationships
 
 - A **Hypernote JupyterLab Server** owns the **Shared Document**.
+- A **Shared Document** saves durable notebook contents and outputs into one **Notebook File**.
+- A **Collaboration Journal** is temporary server-local state; Hypernote does not make it a durable project artifact or product choice.
 - An **Open Lab Tab** and **Agent Automation** must attach to the same **Hypernote JupyterLab Server**.
 - **Agent Automation** does not require an **Open Lab Tab**, but it still requires the **Hypernote JupyterLab Server**.
 
@@ -31,8 +41,13 @@ _Avoid_: separate runtime mode
 
 > **Dev:** "Can agents run notebooks without JupyterLab?"
 > **Domain expert:** "No separate mode: agents use the **Hypernote JupyterLab Server** even if nobody has an **Open Lab Tab**."
+>
+> **Dev:** "Is the collaboration database part of Hypernote's durable state?"
+> **Domain expert:** "No — durability means the **Shared Document** has saved back to the **Notebook File**."
 
 ## Flagged Ambiguities
 
 - Agent work without an **Open Lab Tab** was previously described as a separate product mode; resolved: Hypernote only distinguishes whether an **Open Lab Tab** exists.
 - "Jupyter server" was used broadly; resolved: the supported product server is a **Hypernote JupyterLab Server**.
+- Jupyter's real-time collaboration store was treated as possible Hypernote state; resolved: it is a **Collaboration Journal**, not primary notebook storage or Hypernote job history.
+- Persistent collaboration-store configuration was considered as a user-facing choice; resolved: Hypernote treats the **Collaboration Journal** as temporary server-local state only.

{hypernote-0.3.0 → hypernote-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypernote
-Version: 0.3.0
+Version: 0.4.0
 Summary: Thin control plane for Jupyter notebook execution with jobs, attribution, and runtime lifecycle
 Project-URL: Homepage, https://github.com/gilad-rubin/hypernote
 Project-URL: Repository, https://github.com/gilad-rubin/hypernote
@@ -29,6 +29,7 @@ Description-Content-Type: text/markdown
 - **One notebook truth** - notebook edits, execution, and late-open JupyterLab views all operate on the same logical document.
 - **Agent-first surface** - the Python SDK is primary, and the CLI is a thin shell over it.
 - **Ephemeral control plane** - Jupyter owns durable `.ipynb` contents and outputs; Hypernote owns in-memory runtimes, jobs, and attribution.
+- **Temporary collaboration journal** - `setup serve` keeps Jupyter RTC updates in server-local temp storage, not repo-root databases.
 
 ## What it ships
 
@@ -76,6 +77,7 @@ Jupyter owns:
 
 - notebook persistence
 - shared YDoc document state
+- temporary collaboration journal state for live RTC updates
 - kernel and session primitives
 - notebook rendering in JupyterLab
 

{hypernote-0.3.0 → hypernote-0.4.0}/README.md

@@ -4,6 +4,7 @@
 - **One notebook truth** - notebook edits, execution, and late-open JupyterLab views all operate on the same logical document.
 - **Agent-first surface** - the Python SDK is primary, and the CLI is a thin shell over it.
 - **Ephemeral control plane** - Jupyter owns durable `.ipynb` contents and outputs; Hypernote owns in-memory runtimes, jobs, and attribution.
+- **Temporary collaboration journal** - `setup serve` keeps Jupyter RTC updates in server-local temp storage, not repo-root databases.
 
 ## What it ships
 
@@ -51,6 +52,7 @@ Jupyter owns:
 
 - notebook persistence
 - shared YDoc document state
+- temporary collaboration journal state for live RTC updates
 - kernel and session primitives
 - notebook rendering in JupyterLab
 

{hypernote-0.3.0 → hypernote-0.4.0}/SKILL.md

@@ -51,6 +51,10 @@ uv run hypernote setup serve --no-browser &
 available. The default address is `http://127.0.0.1:8888`. Omit `--no-browser`
 when you want setup to open JupyterLab immediately.
 
+Servers launched by `setup serve` use temporary Jupyter collaboration journal storage.
+Notebook contents and outputs still persist through the `.ipynb` file once the
+shared document is saved.
+
 **If the server is running but `default_kernel` points to the wrong Python** (e.g., a
 different repo's `.venv`), stop the old server and start a new one with `setup serve`
 from this repo. This is the only case where you should restart a running server.

{hypernote-0.3.0 → hypernote-0.4.0}/dev/current-architecture.md

@@ -21,6 +21,8 @@ Jupyter shared document + kernel/session primitives
 - `setup serve` is the CLI bootstrap path for starting a local Hypernote-enabled JupyterLab server.
 - Notebook reads and writes must go through the shared-document path.
 - Execution must resolve cell source from the same document model the UI sees.
+- Servers launched by `setup serve` use Jupyter's temporary RTC collaboration journal;
+  the `.ipynb` file is the durable notebook artifact.
 - JupyterLab is the supported integration environment. Opening a Lab tab is optional,
   but Hypernote still runs through the Hypernote-enabled JupyterLab server and shared
   document path.
@@ -31,6 +33,7 @@ Jupyter shared document + kernel/session primitives
 - open-tab and closed-tab behavior must match
 - opening a notebook mid-run must show prior output and continue streaming
 - persisted `.ipynb` output must converge with the live shared document
+- unsaved shared-document state is not recovered through a project-local RTC database
 - runtime creation must resolve the desired kernel from an explicit override, otherwise the
   notebook metadata kernelspec, otherwise `python3`
 - Hypernote must not silently reuse a live runtime if the notebook now targets a different kernel

{hypernote-0.3.0 → hypernote-0.4.0}/dev/release.md

@@ -63,11 +63,30 @@ Either way, the only change to `pyproject.toml` is the top-level
 git add CHANGELOG.md pyproject.toml uv.lock
 git commit -m "chore: prepare v$VERSION release"
 git push -u origin release/v$VERSION
+```
+
+If the PR is **only** release bookkeeping, a generic release title is fine:
+
+```bash
 gh pr create \
   --title "chore: prepare v$VERSION release" \
   --body "Release prep for v$VERSION. CHANGELOG section moved, version bumped, lock refreshed. The release workflow runs automatically after merge."
 ```
 
+If the release PR also contains a feature or fix, the PR title and body should
+lead with that shipped change, not with the version bump. Include the target
+version in the title so it is clear that merging to `master` releases it:
+
+```bash
+gh pr create \
+  --title "Use temporary collaboration journal for setup serve and release v$VERSION" \
+  --body "This PR ships the temporary collaboration journal change and prepares v$VERSION. Merging to master triggers the release workflow for v$VERSION."
+```
+
+Release PRs should be ready for review when opened unless the implementation is
+intentionally incomplete. Do not make a release PR draft just because it contains
+the version bump.
+
 ```bash
 # 5. wait for CI, address any review, merge into master
 gh pr merge --merge   # or --squash, depending on team preference
@@ -128,6 +147,9 @@ or replace it.
 - **Do not edit a CHANGELOG entry after the corresponding version is published.** If you need to correct it, file a follow-up PR that adds a "Note" line under the next version explaining the correction.
 - **Do not bump the version outside a release PR.** The checked-in version bump
   is the automatic release trigger once the PR lands on `master`.
+- **Do not hide a shipped behavior change behind a generic release title.** If
+  the PR includes a feature or fix, make that the title and explain that the
+  version bump releases it.
 - **Do not include local-only work in the CHANGELOG.** If `git ls-tree origin/master` doesn't show the files, they are not shipping. Drop the line or commit the files first.
 - **Do not skip the integration test step before opening the release PR.**
   Browser tests catch the kernel-control regressions that unit tests cannot —

{hypernote-0.3.0 → hypernote-0.4.0}/docs/cli.md

@@ -108,6 +108,7 @@ For command variants, prefer consistent structure over clever special cases. A m
 - `hypernote setup serve`
   - starts a Hypernote-enabled JupyterLab server in the current Python environment
   - opens a browser tab by default; use `--no-browser` to keep the same server without opening a tab
+  - uses Jupyter's temporary real-time collaboration journal; the `.ipynb` remains the durable notebook artifact
 - `hypernote --server http://127.0.0.1:8899 setup serve --root /path/to/repo`
   - starts the server for another repo or port while keeping execution in that repo's environment
 - if the JupyterLab integration stack is missing in the current env, `setup serve` fails with an install hint instead of a long module error

{hypernote-0.3.0 → hypernote-0.4.0}/docs/getting-started.md

@@ -32,6 +32,11 @@ uv run hypernote setup serve
 `setup serve` opens JupyterLab by default. Use `--no-browser` when you want the
 same server without opening a Lab tab.
 
+Servers launched by `setup serve` configure Jupyter's real-time collaboration journal as
+temporary server-local state. Saved notebook contents and outputs still persist
+in the `.ipynb`; unsaved live collaboration changes are not recovered through a
+project-local database after a server crash.
+
 If the notebook belongs to another repo, install Hypernote there (`uv add hypernote --dev`)
 and run the same bootstrap command from that repo.
 
@@ -87,6 +92,7 @@ The notebook state, execution state, and outputs should still agree.
 ## Lifecycle expectation
 
 - notebook contents and outputs persist in the `.ipynb` because Jupyter owns the document
+- Jupyter's collaboration journal is temporary server-local state for servers launched by `setup serve`
 - runtime state, jobs, and cell attribution are ephemeral Hypernote control-plane state
 - stopping a runtime or restarting the server clears that control-plane state
 - runtime creation resolves the requested kernel first, otherwise notebook metadata

{hypernote-0.3.0 → hypernote-0.4.0}/docs/runtime-model.md

@@ -6,6 +6,7 @@ Jupyter owns the notebook document and kernel primitives. Hypernote owns the con
 
 - notebook persistence
 - shared YDoc state
+- real-time collaboration journal state
 - kernel and session primitives
 - notebook rendering in JupyterLab
 
@@ -26,6 +27,18 @@ Hypernote-owned control-plane state is intentionally ephemeral:
 
 Notebook contents and outputs still persist because Jupyter owns the `.ipynb` document.
 
+## Collaboration journal
+
+Servers launched by `setup serve` configure Jupyter's real-time collaboration journal as
+temporary server-local state. The journal helps the live shared document while
+the server is running, but it is not a project artifact, job history, or
+attribution store.
+
+Durability begins when the shared document is saved into the `.ipynb` notebook
+file. If a server crashes before an unsaved live change reaches the `.ipynb`,
+Hypernote does not promise to recover that change from a persistent
+collaboration database.
+
 ## Kernel selection
 
 Runtime creation resolves the desired kernel in this order:

{hypernote-0.3.0 → hypernote-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hypernote"
-version = "0.3.0"
+version = "0.4.0"
 description = "Thin control plane for Jupyter notebook execution with jobs, attribution, and runtime lifecycle"
 readme = "README.md"
 requires-python = ">=3.11"

{hypernote-0.3.0 → hypernote-0.4.0}/src/hypernote/cli/main.py

@@ -51,6 +51,7 @@ PROGRESS_CHOICES = click.Choice(["quiet", "events", "full"])
 HYPERNOTE_EXTENSION_FLAGS = (
     "{'hypernote': True, 'jupyter_server_nbmodel': True, 'jupyter_server_ydoc': True}"
 )
+HYPERNOTE_YSTORE_CLASS = "jupyter_server_ydoc.stores.TempFileYStore"
 DEFAULT_SOURCE_PREVIEW_CHARS = 120
 DEFAULT_OUTPUT_PREVIEW_CHARS = DEFAULT_READ_OUTPUT_CHARS
 DEFAULT_TAIL_OUTPUT_CHARS = DEFAULT_READ_OUTPUT_CHARS
@@ -163,6 +164,7 @@ def _serve_command(
             "--ServerApp.disable_check_xsrf=True",
             f"--ServerApp.root_dir={root}",
             f"--ServerApp.jpserver_extensions={HYPERNOTE_EXTENSION_FLAGS}",
+            f"--YDocExtension.ystore_class={HYPERNOTE_YSTORE_CLASS}",
         ]
     )
     return cmd

{hypernote-0.3.0 → hypernote-0.4.0}/tests/conftest.py

@@ -13,6 +13,7 @@ from pathlib import Path
 import httpx
 import pytest
 
+from hypernote.cli.main import HYPERNOTE_EXTENSION_FLAGS, HYPERNOTE_YSTORE_CLASS
 from tests.helpers import auth_headers, hypernote_headers
 
 
@@ -47,15 +48,13 @@ def live_server(tmp_path_factory: pytest.TempPathFactory) -> LiveServer:
         "--ServerApp.password=",
         "--ServerApp.disable_check_xsrf=True",
         f"--ServerApp.root_dir={root_dir}",
-        (
-            "--ServerApp.jpserver_extensions="
-            "{'hypernote': True, 'jupyter_server_nbmodel': True, 'jupyter_server_ydoc': True}"
-        ),
+        f"--ServerApp.jpserver_extensions={HYPERNOTE_EXTENSION_FLAGS}",
+        f"--YDocExtension.ystore_class={HYPERNOTE_YSTORE_CLASS}",
     ]
     env = os.environ.copy()
     process = subprocess.Popen(
         cmd,
-        cwd=str(Path(__file__).resolve().parents[1]),
+        cwd=str(root_dir),
         env=env,
         stdout=log_path.open("w"),
         stderr=subprocess.STDOUT,

{hypernote-0.3.0 → hypernote-0.4.0}/tests/test_cli.py

@@ -1212,6 +1212,10 @@ def test_setup_serve_launches_jupyterlab_with_browser_by_default(
     assert (
         f"--ServerApp.jpserver_extensions={cli_main.HYPERNOTE_EXTENSION_FLAGS}" in cmd
     )
+    assert (
+        "--YDocExtension.ystore_class=jupyter_server_ydoc.stores.TempFileYStore"
+        in cmd
+    )
     assert captured["cwd"] == str(tmp_path.resolve())
     assert captured["check"] is False
 

{hypernote-0.3.0 → hypernote-0.4.0}/tests/test_live_server.py

@@ -50,6 +50,21 @@ async def test_execute_persists_output(
     assert outputs, "Expected outputs to be persisted into the notebook"
 
 
+async def test_execute_does_not_create_project_collaboration_database(
+    hypernote_api,
+    jupyter_api,
+    live_server: LiveServer,
+):
+    notebook = await _create_live_notebook(jupyter_api, "hypernote-live-temp-journal")
+    quoted = urllib.parse.quote(notebook, safe="")
+    resp = await hypernote_api.post(f"/notebooks/{quoted}/execute", json={"cell_ids": ["cell-a"]})
+    resp.raise_for_status()
+
+    job = await await_job(hypernote_api, resp.json()["job_id"])
+    assert job["status"] == "succeeded"
+    assert not (live_server.root_dir / ".jupyter_ystore.db").exists()
+
+
 async def test_execute_honors_notebook_kernelspec_instead_of_defaulting(
     hypernote_api,
     jupyter_api,

{hypernote-0.3.0 → hypernote-0.4.0}/uv.lock

@@ -614,7 +614,7 @@ wheels = [
 
 [[package]]
 name = "hypernote"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },