hypernote 0.1.3__tar.gz → 0.3.0__tar.gz

hypernote-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,236 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g., 0.3.0)"
+        required: true
+        type: string
+      publish_to_pypi:
+        description: "Publish to PyPI"
+        required: true
+        default: true
+        type: boolean
+      create_draft:
+        description: "Create as draft release"
+        required: false
+        default: false
+        type: boolean
+  push:
+    branches:
+      - master
+    paths:
+      - "CHANGELOG.md"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/release.yml"
+
+permissions:
+  contents: write
+
+jobs:
+  resolve-version:
+    if: ${{ github.event_name != 'push' || github.actor != 'github-actions[bot]' }}
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.resolve.outputs.version }}
+      publish_to_pypi: ${{ steps.resolve.outputs.publish_to_pypi }}
+      create_draft: ${{ steps.resolve.outputs.create_draft }}
+      should_release: ${{ steps.resolve.outputs.should_release }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Resolve release version
+        id: resolve
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+          INPUT_PUBLISH_TO_PYPI: ${{ inputs.publish_to_pypi }}
+          INPUT_CREATE_DRAFT: ${{ inputs.create_draft }}
+        run: |
+          VERSION="$INPUT_VERSION"
+          if [ -z "$VERSION" ]; then
+            VERSION="$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])
+          PY
+          )"
+          fi
+
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$ ]]; then
+            echo "❌ Invalid version format: $VERSION"
+            echo "Expected semantic version (e.g., 0.3.0, 0.3.0-alpha.1)"
+            exit 1
+          fi
+
+          git fetch --tags --force
+          TAG="v$VERSION"
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            if [ "$GITHUB_EVENT_NAME" = "push" ] && [ "${GITHUB_RUN_ATTEMPT:-1}" = "1" ]; then
+              echo "ℹ️ $TAG already exists; nothing to release."
+              echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+              echo "publish_to_pypi=false" >> "$GITHUB_OUTPUT"
+              echo "create_draft=false" >> "$GITHUB_OUTPUT"
+              echo "should_release=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            echo "ℹ️ $TAG already exists; continuing because this is a rerun/recovery attempt."
+          fi
+
+          echo "✅ Version format is valid: $VERSION"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "publish_to_pypi=${INPUT_PUBLISH_TO_PYPI:-true}" >> "$GITHUB_OUTPUT"
+          echo "create_draft=${INPUT_CREATE_DRAFT:-false}" >> "$GITHUB_OUTPUT"
+          echo "should_release=true" >> "$GITHUB_OUTPUT"
+
+  release:
+    needs: resolve-version
+    if: ${{ needs.resolve-version.outputs.should_release == 'true' }}
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ needs.resolve-version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Ensure release version is checked in
+        env:
+          VERSION: ${{ needs.resolve-version.outputs.version }}
+        run: |
+          CURRENT_VERSION="$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])
+          PY
+          )"
+
+          if [ "$CURRENT_VERSION" = "$VERSION" ]; then
+            echo "✅ pyproject.toml already declares $VERSION"
+            exit 0
+          fi
+
+          if [ "$GITHUB_EVENT_NAME" != "workflow_dispatch" ]; then
+            echo "❌ pyproject.toml declares $CURRENT_VERSION, expected $VERSION"
+            exit 1
+          fi
+
+          sed -i -E "0,/^version = \".*\"/s//version = \"$VERSION\"/" pyproject.toml
+
+          if ! grep -q "version = \"$VERSION\"" pyproject.toml; then
+            echo "❌ Failed to update version in pyproject.toml"
+            exit 1
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          uv lock
+          git add pyproject.toml uv.lock
+          git commit -m "chore: bump version to v$VERSION"
+          CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+          git push origin "$CURRENT_BRANCH"
+          echo "✅ Version commit pushed"
+
+      - name: Build package
+        run: |
+          rm -rf dist/ build/ *.egg-info/
+          uv build
+          if [ ! -f dist/*.whl ] || [ ! -f dist/*.tar.gz ]; then
+            echo "❌ Build artifacts not found"
+            exit 1
+          fi
+          echo "✅ Package built"
+          ls -la dist/
+
+      - name: Verify package
+        run: |
+          uv run --isolated --no-project --with dist/*.whl python -c "import hypernote; print('ok')"
+          echo "✅ Package verified"
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: dist-${{ needs.resolve-version.outputs.version }}
+          path: dist/*
+          if-no-files-found: error
+
+      - name: Run tests
+        run: |
+          uv run --extra dev playwright install --with-deps chromium
+          uv run --extra dev python -m pytest -q
+
+      - name: Create and push tag
+        env:
+          VERSION: ${{ needs.resolve-version.outputs.version }}
+        run: |
+          TAG="v$VERSION"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git fetch --tags --force
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            TAG_TARGET="$(git rev-list -n 1 "$TAG")"
+            HEAD_SHA="$(git rev-parse HEAD)"
+            if [ "$TAG_TARGET" = "$HEAD_SHA" ]; then
+              echo "✅ $TAG already points at $HEAD_SHA; continuing."
+              exit 0
+            fi
+            echo "❌ $TAG points at $TAG_TARGET, not current HEAD $HEAD_SHA. Refusing to retag."
+            exit 1
+          fi
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+          echo "✅ Created and pushed tag $TAG"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CREATE_DRAFT: ${{ needs.resolve-version.outputs.create_draft }}
+        run: |
+          TAG="v${{ needs.resolve-version.outputs.version }}"
+          DRAFT_FLAG=""
+          if [ "$CREATE_DRAFT" = "true" ]; then
+            DRAFT_FLAG="--draft"
+          fi
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber
+          else
+            gh release create "$TAG" dist/* \
+              --generate-notes \
+              --verify-tag \
+              $DRAFT_FLAG
+          fi
+
+      - name: Summary
+        run: |
+          echo "## Release Summary" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Version:** v${{ needs.resolve-version.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **PyPI:** ${{ needs.resolve-version.outputs.publish_to_pypi }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Draft:** ${{ needs.resolve-version.outputs.create_draft }}" >> "$GITHUB_STEP_SUMMARY"
+
+  publish-pypi:
+    needs:
+      - resolve-version
+      - release
+    if: ${{ needs.resolve-version.outputs.publish_to_pypi == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist-${{ needs.resolve-version.outputs.version }}
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish

hypernote-0.3.0/AGENTS.md

@@ -0,0 +1,186 @@
+# Hypernote
+
+Notebook-first execution system built on top of Jupyter shared documents
+
+## Quick Start
+
+```bash
+uv sync --extra dev
+uv run hypernote
+uv run hypernote --help
+uv run hypernote setup serve
+uv run hypernote setup doctor
+uv run hypernote create tmp/demo.ipynb
+uv run hypernote ix tmp/demo.ipynb -s 'value = 20 + 22\nprint(value)'
+uv run hypernote status tmp/demo.ipynb --full
+uv run python -m pytest -q
+uv run ruff check src/hypernote tests
+```
+
+## Architecture
+
+Jupyter owns notebook truth:
+
+- `.ipynb` persistence
+- shared YDoc document state
+- kernel and session primitives
+- notebook rendering in JupyterLab
+
+Hypernote owns a thin control plane:
+
+- public SDK in [src/hypernote/sdk.py](src/hypernote/sdk.py)
+- public errors in [src/hypernote/errors.py](src/hypernote/errors.py)
+- agent-first CLI in [src/hypernote/cli/main.py](src/hypernote/cli/main.py)
+- execution orchestration and shared-document mutation in [src/hypernote/execution_orchestrator.py](src/hypernote/execution_orchestrator.py)
+- runtime ownership in [src/hypernote/runtime_manager.py](src/hypernote/runtime_manager.py)
+- HTTP handlers in [src/hypernote/server/handlers.py](src/hypernote/server/handlers.py)
+- Jupyter extension wiring in [src/hypernote/server/extension.py](src/hypernote/server/extension.py)
+- ephemeral job and attribution ledger in [src/hypernote/actor_ledger.py](src/hypernote/actor_ledger.py)
+- subshell-aware execute/interrupt/restart in [src/hypernote/server/subshell.py](src/hypernote/server/subshell.py)
+
+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.
+
+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.
+
+## Shipped Surface
+
+### SDK
+
+- `hypernote.connect(path, create=False)`
+- `Notebook`, `CellCollection`, `CellHandle`, `Runtime`, `Job`
+- `nb.run(...)`, `nb.run_all()`, `nb.restart()`, `nb.interrupt()`
+- `nb.snapshot()`, `nb.status()`, `nb.diff(...)`
+
+### CLI
+
+- `hypernote` — live workspace dashboard with hints
+- `create`
+- `ix`
+- `exec`
+- `edit`
+- `run-all`
+- `restart`
+- `restart-run-all`
+- `interrupt`
+- `status`
+- `diff`
+- `cat`
+- `job ...`
+- `runtime ...`
+- `setup doctor`
+- `setup serve`
+
+Default CLI contract:
+
+- bare `hypernote` shows live workspace state and next-step hints
+- TTY: concise human-readable progress
+- non-TTY: one compact final JSON result
+- explicit streaming only through `--watch` or `--stream-json`
+- summary-first read payloads should come from SDK-backed observation helpers, not CLI-only formatting rules
+- `setup serve` is the default local bootstrap path for a Hypernote-enabled JupyterLab server
+- `setup doctor --path PATH` is the preferred first diagnostic when server reachability,
+  kernelspec selection, or runtime mismatch is unclear
+
+## Rules
+
+- Terminology: when the user says "our system", treat that as the maintained project-operating surface, including `AGENTS.md`, `SKILL.md`, `docs/`, `dev/`, tests, and other shared guidance or verification artifacts around the code.
+- SDK first. CLI behavior should come from the SDK, not duplicate raw HTTP semantics.
+- When CLI and SDK both need compact observation behavior, define the summary/truncation/focused-read logic in the SDK and let the CLI adapt it.
+- Shared logic needs one owner. When a helper or shaping rule moves into the SDK or another shared layer, delete the old copies instead of letting multiple versions drift.
+- One truth. Do not reintroduce a contents-vs-YDoc split for notebook reads or writes.
+- Runtime creation must honor the requested kernel first, otherwise notebook metadata
+  `kernelspec.name`, otherwise `python3`.
+- Keep control-plane state ephemeral. Do not add durable job history unless the product explicitly needs it.
+- Our system is part of done. After every meaningful change, update the relevant parts of `AGENTS.md`, `SKILL.md`, `docs/`, `dev/`, tests, and adjacent shared project guidance so they stay in sync with implementation.
+- Keep adapters thin. CLI, JupyterLab, and tests should reuse shared contracts instead of re-encoding notebook behavior.
+- Treat output and API shapes as contracts. Feature variants should preserve the same top-level envelope and field semantics unless there is a deliberate, documented exception.
+- Normalize boundary inputs early. If upstream payloads can arrive in more than one valid shape, accept and normalize them at the adapter boundary rather than assuming a single representation.
+- Prefer unique notebook paths in tests and demos. Browser tests must also use unique JupyterLab workspace URLs.
+- Keep `tmp/` disposable. Durable notes belong in `docs/` or `dev/`, not `tmp/`.
+- Release every version through a PR (CHANGELOG move + version bump + lockfile refresh on a `release/vX.Y.Z` branch), never via direct push to master. The full process is in [dev/release.md](dev/release.md).
+
+## Read These First
+
+- [SKILL.md](SKILL.md)
+- [docs/README.md](docs/README.md)
+- [dev/README.md](dev/README.md)
+- [dev/release.md](dev/release.md)
+
+## If You Are Editing...
+
+### `src/hypernote/sdk.py` or `src/hypernote/errors.py`
+
+- preserve the notebook-first public object model
+- keep public enums and errors stable
+- prefer adding reusable observation helpers on `NotebookStatus` / `CellStatus` over adding CLI-only shaping logic
+- update [docs/sdk.md](docs/sdk.md)
+
+### `src/hypernote/cli/main.py`
+
+- keep non-TTY output compact by default
+- keep bare `hypernote` as the live dashboard view
+- preserve `ix` as the happy-path command
+- preserve summary-first `status` and compact `cat` with contextual hints
+- prefer rendering SDK observation helpers over introducing new CLI-only data shaping
+- keep streaming explicit in non-TTY mode
+- update [docs/cli.md](docs/cli.md)
+
+### `src/hypernote/execution_orchestrator.py`, `src/hypernote/runtime_manager.py`, or `src/hypernote/server/*`
+
+- preserve the single-truth shared-document path
+- verify open-tab and late-open behavior still hold
+- update [dev/current-architecture.md](dev/current-architecture.md)
+- if browser-visible behavior changes, update [docs/browser-regression-spec.md](docs/browser-regression-spec.md)
+
+### `tests/*`
+
+- prefer the narrowest test that proves the behavior
+- preserve coverage for:
+  - SDK shape
+  - CLI output contract
+  - live server behavior
+  - browser regression for streaming and late-open correctness
+- for contract-heavy changes, add invariant coverage for:
+  - default and focused variants
+  - empty and failure states
+  - alternate valid input shapes from upstream payloads
+  - parity between real helpers and any fake/test-double implementations
+
+### `pyproject.toml` version, `CHANGELOG.md`, or `.github/workflows/release.yml`
+
+- always use the PR-based release process in [dev/release.md](dev/release.md)
+- do not push release-prep commits directly to master, even for a one-line version bump
+- before opening the release PR, confirm `git ls-tree origin/master` shows every file mentioned in the new CHANGELOG section — local-only work must not be claimed in the changelog
+- if you change the release workflow shape (steps, secrets, version source), update [dev/release.md](dev/release.md) in the same PR so the doc stays accurate
+
+## Verification
+
+Install guidance:
+
+- `uv sync`
+  - Hypernote's default JupyterLab integration stack
+- `uv sync --extra dev`
+  - adds local development, lint, test, and browser-validation tooling
+
+Minimum checks for most changes:
+
+```bash
+uv run ruff check src/hypernote tests
+uv run python -m pytest -q
+```
+
+When browser or live-server behavior changes, also use:
+
+```bash
+HYPERNOTE_INTEGRATION=1 uv run python -m pytest -q tests/test_live_server.py
+uv run python -m pytest -q tests/test_browser_regression.py
+```
+
+Before opening or updating a PR for a cross-surface change, do a short contract pass:
+
+- check that sibling command variants still share one consistent envelope
+- check that aggregate field names still match their exact semantics
+- check that docs and hints only mention shipped commands and flags
+- check that moved logic no longer has stale copies in adapters or tests

hypernote-0.3.0/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+## 0.3.0 - 2026-05-10
+
+Hypernote is now a JupyterLab-first integration: the default install carries the
+collaboration/docprovider stack, `setup serve` opens Lab by default, and
+`setup doctor` can distinguish API reachability from shared-document and Lab
+frontend health.
+
+### Changed
+
+- Hypernote is now packaged and documented as a JupyterLab-first integration:
+  the default install includes JupyterLab collaboration support, `setup serve`
+  opens Lab by default, `setup doctor` reports the shared-document stack and
+  duplicate local servers, and cell-state operations require the shared
+  document path instead of falling back to contents-manager edits.
+
+### Notes
+
+- correction: the 0.2.0 headline mentions "an experimental VS Code extension" but the
+  `vscode-extension/` work was never committed and did not ship in the 0.2.0 artifact.
+  Documentation referring to the VS Code extension has been removed from `README.md`,
+  `AGENTS.md`, `SKILL.md`, `docs/README.md`, `dev/README.md`, and `dev/module-map.md`.
+
+## 0.2.0 - 2026-05-07
+
+Native JupyterLab as a first-class concurrent actor: open a notebook
+mid-run and see streaming output, click Stop and the cell terminates,
+click Restart and the kernel comes back ready. Plus the package now ships
+in PyPA src layout and an experimental VS Code extension.
+
+### Added
+
+- subshell-routed kernel execution (JEP 91 / ipykernel 7+): Hypernote sends `execute_request` with a `subshell_id` so the kernel's main shell stays free to answer concurrent clients (e.g. JupyterLab) — opening a notebook mid-run now renders cells immediately and continues to stream output without waiting for the running cell
+- subshell-aware `POST /api/kernels/{id}/interrupt` override: JupyterLab's Stop button (and `nb.interrupt()`) now terminates a Hypernote-driven cell, raising `KeyboardInterrupt` in the subshell thread via a main-shell `PyThreadState_SetAsyncExc` injection. Falls back to default SIGINT for non-Hypernote-driven kernels.
+- subshell- and nbmodel-aware `POST /api/kernels/{id}/restart` override: JupyterLab's Restart button now leaves the kernel ready to run new cells. Hypernote evicts nbmodel's stale per-kernel client and worker, and clears its cached subshell id, so the next execute rebuilds against the fresh kernel.
+- new browser regression tests for Lab Stop and Lab Restart against subshell-routed cells; new real-kernel unit tests for subshell creation, routing, interrupt latency, and restart cleanup.
+
+### Changed
+
+- package layout migrated to `src/hypernote/` (PyPA src layout). `pyproject.toml` now configures `[tool.hatch.build.targets.wheel] packages = ["src/hypernote"]` and `[tool.ruff] src = ["src", "tests"]`. The `hypernote` import name is unchanged — `import hypernote` continues to work.
+- release workflow switched from tag-triggered to `workflow_dispatch` — run `gh workflow run release.yml -f version=X.Y.Z` to release
+
+### Notes
+
+- subshell routing requires ipykernel 7+ (IPython kernels). Other kernels fall back to the main shell — late-open during a long-running cell will block the JupyterLab UI for those kernels and the subshell-targeted interrupt becomes a no-op (override falls through to SIGINT, which works on the main shell).
+- `PyThreadState_SetAsyncExc`-based interrupt cannot terminate a thread inside a long blocking C call without GIL release (e.g. `requests.get` with no timeout). The `KeyboardInterrupt` only fires once control returns to Python. The interrupt snippet falls back to `os.kill(pid, SIGINT)` internally if the subshell thread cannot be found, so user-visible "Stop did nothing" cases degrade to default SIGINT behavior rather than silent failure.
+
+## 0.1.3 - 2026-04-03
+
+Cross-repo runtime hardening and agent ergonomics.
+
+### Added
+
+- `hypernote setup serve` — bootstraps a Hypernote-enabled Jupyter server with all required extensions
+- `hypernote setup doctor --path PATH` — reports notebook kernelspec, live runtime kernel, resolved launcher, and warns on mismatches
+- `hypernote create --empty` — removes any default cells Jupyter auto-inserts so notebooks start clean
+- batch `ix` output now includes `cells_inserted`, `cells_total`, `cells_remaining`, `halt_reason`, and `last_processed_cell_id` on early halt
+- timeout errors now surface job id, last known status, and recovery hints pointing to `job get` and `cat`
+- runtime kernel mismatch detection — clear error when a live runtime's kernel doesn't match notebook metadata, with guidance to restart
+
+### Changed
+
+- execution now resolves kernels as: explicit override > notebook metadata `kernelspec.name` > `python3`
+- `RuntimeManager.ensure_room()` rejects silent reuse when a live room exists with a different kernel name
+- removed all hardcoded local paths from project markdown files — links are now repo-relative
+- SKILL.md rewritten: iterative `ix → observe → ix` is the primary workflow, heredoc/stdin documented for multi-line cells, server lifecycle section added, cross-repo setup simplified to `uv add hypernote --dev`
+
+### Notes
+
+- `--cells-file` batch mode is now documented as a convenience for known-good sequences, not the default workflow
+- the recommended cross-repo pattern is now: install hypernote in the target repo, not `uv run --with`
+
+## 0.1.1 - 2026-04-02
+
+Patch release focused on release automation hardening.
+
+### Changed
+
+- updated the GitHub release workflow to newer official action majors where available
+- replaced the third-party GitHub release action with the `gh` CLI in release automation
+- fixed the release workflow to install Playwright browser binaries before running browser tests
+- fixed the release workflow to run tests with the `dev` extra installed
+- fixed the PyPI publish step to use token-only `uv publish` authentication
+
+### Notes
+
+- package code is unchanged from `0.1.0`
+- this release exists to verify and stabilize the automated release path
+
+## 0.1.0 - 2026-04-02
+
+Initial public release.
+
+### Added
+
+- notebook-first Python SDK built around `Notebook`, `CellCollection`, `CellHandle`, `Runtime`, and `Job`
+- agent-first CLI with `create`, `ix`, `exec`, `edit`, `run-all`, `restart`, `interrupt`, `status`, `diff`, `cat`, `job`, and `runtime` flows
+- Jupyter server extension with narrow Hypernote REST handlers
+- notebook-scoped runtime lifecycle with attach, detach, recovery, stop, and GC
+- headless execution flow over Jupyter shared documents and `jupyter-server-nbmodel`
+- job polling and `input()` round-trip support for long-running or interactive execution
+- live-server and browser regression tests for late-open, persistence, and shared-document correctness
+- project and developer docs for the runtime model, SDK, CLI, and release workflow
+
+### Changed
+
+- aligned the control plane around an explicitly ephemeral lifecycle
+- moved job tracking and cell attribution to an in-memory notebook-scoped ledger
+- removed the SQLite dependency and any implied durable job history
+
+### Notes
+
+- Jupyter owns durable notebook contents and outputs in `.ipynb`
+- Hypernote owns ephemeral runtime state, jobs, and attribution

hypernote-0.3.0/CONTEXT.md

@@ -0,0 +1,38 @@
+# Hypernote
+
+Hypernote coordinates notebook execution through a Hypernote-enabled JupyterLab
+server so agents and humans can work against one notebook truth.
+
+## Language
+
+**Shared Document**:
+The server-side notebook document that all Hypernote operations use as the live notebook truth.
+_Avoid_: file-only notebook truth
+
+**Hypernote JupyterLab Server**:
+A JupyterLab server launched or verified with Hypernote's required server and collaboration extensions.
+_Avoid_: plain Jupyter server, separate agent server
+
+**Open Lab Tab**:
+A browser tab viewing a notebook through the Hypernote JupyterLab Server.
+_Avoid_: separate Lab server, plain Lab tab
+
+**Agent Automation**:
+CLI or SDK notebook work performed through the Hypernote JupyterLab Server, whether an Open Lab Tab currently exists.
+_Avoid_: separate runtime mode
+
+## Relationships
+
+- A **Hypernote JupyterLab Server** owns the **Shared Document**.
+- 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**.
+
+## Example Dialogue
+
+> **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**."
+
+## 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**.