openstategraph 0.3.0rc18__tar.gz

openstategraph-0.3.0rc18/.env.example

@@ -0,0 +1,11 @@
+
+# --- Deployment ---------------------------------------------------------
+# Shared bearer token for the HTTP API and the MCP layer. Unset means NO
+# auth: anyone who reaches the port can run workflows, read every workflow
+# file and spend your model budget. See docs/deploying.md.
+OPENSTATEGRAPH_API_TOKEN=
+
+# Where durable state (approval checkpoints, the serve lock) is written.
+# Defaults to the platform state dir when installed, or the checkout's
+# .openstategraph/ in a repo. Never inside someone else's workflows folder.
+OPENSTATEGRAPH_STATE_DIR=

openstategraph-0.3.0rc18/.gitignore

@@ -0,0 +1,80 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Code graph — derived, rebuild with `graphify update .`
+graphify-out/
+
+# Editor / OS
+.DS_Store
+*.swp
+.idea/
+.vscode/*
+!.vscode/extensions.json
+
+# Local env and secrets
+.env
+.env.*
+!.env.example
+*.local
+
+# Python (backend, not yet created)
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Test output. `.coverage` is the sqlite database a coverage run writes: a
+# build artifact with no reader, carrying the absolute paths of whichever
+# machine produced it. It was tracked until `publishable/04`, which is what an
+# artifact with no ignore rule does — an untracked file comes back on the next
+# careless `git add`.
+coverage/
+.coverage
+.coverage.*
+.gstack/
+
+# No PDF belongs at the repository root. A third party's article was committed
+# there and went unnoticed for weeks (`publishable/04`); republishing somebody
+# else's copyrighted work is the reason that mattered, and a careless `git add`
+# at the root is how it arrived. Anchored, so a PDF that a document genuinely
+# needs can still live beside that document. `git add -f` is the hatch.
+/*.pdf
+
+# Code Workshop workflow — runtime jail and PR dry-run output, never sources
+harness-loop-graph.pdf
+.claude/settings.local.json
+.dev/
+
+# Runtime state, not content: thread checkpoints (ticket 05) live beside the
+# workflow packages they are state about. The -wal/-shm siblings are sqlite's.
+.openstategraph/
+workflows/.openstategraph/
+test-results/
+playwright-report/
+
+# Internal planning substrate — local only, never published
+.scratch/
+HANDOVER.md
+
+# The refused-term table for `backend/tests/test_the_tree_is_publishable.py`.
+# The gate is the one place a client engagement is named, and `publishable/06`
+# measured what that cost: tracked, the gate would have published the list it
+# exists to keep out, in the commit and in the sdist both. So the words live
+# here, untracked, and the gate loads them — skipping loudly when the file is
+# absent rather than reporting a green it did not earn. At the repository root
+# on purpose: the sdist is built from `backend/`, so a table up here cannot
+# reach a distribution even if this rule were deleted.
+/.engagement-terms.json
+
+# The migration CLI's own scratch directory. It caches a version string and a
+# link state for whichever project a maintainer is pointed at — a working note
+# of one machine, not a fact about this repository, and the one file it holds
+# today is the CLI's latest version number (team-board-and-gap-reports/09).
+supabase/.temp/

openstategraph-0.3.0rc18/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zulfeekar Cheriyam Purath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openstategraph-0.3.0rc18/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: openstategraph
+Version: 0.3.0rc18
+Summary: A compiler from a vendor-neutral workflow.json to a LangGraph StateGraph.
+Project-URL: Homepage, https://github.com/zulfeekar/openstategraph
+Project-URL: Repository, https://github.com/zulfeekar/openstategraph
+Project-URL: Source, https://github.com/zulfeekar/openstategraph
+Project-URL: Changelog, https://github.com/zulfeekar/openstategraph/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/zulfeekar/openstategraph/blob/main/docs/adoption.md
+Author: Zulfeekar Cheriyam Purath
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,compiler,langchain,langgraph,state-machine,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: langchain-core<2,>=1.0
+Requires-Dist: langchain<2,>=1.0
+Requires-Dist: langgraph<2,>=1.0
+Requires-Dist: pydantic<3,>=2.9
+Provides-Extra: all
+Requires-Dist: databricks-sql-connector<5,>=3.4; extra == 'all'
+Requires-Dist: deepagents<1,>=0.7; extra == 'all'
+Requires-Dist: fastapi<0.142,>=0.115; extra == 'all'
+Requires-Dist: langchain-anthropic<2,>=1.0; extra == 'all'
+Requires-Dist: langchain-mcp-adapters<0.4,>=0.3.0; extra == 'all'
+Requires-Dist: langchain-ollama<2,>=1.0; extra == 'all'
+Requires-Dist: langchain-openai<2,>=1.0; extra == 'all'
+Requires-Dist: langgraph-checkpoint-postgres<4,>=3.1; extra == 'all'
+Requires-Dist: langgraph-checkpoint-sqlite>=3.1; extra == 'all'
+Requires-Dist: mcp<2,>=1.25; extra == 'all'
+Requires-Dist: msal<2,>=1.28; extra == 'all'
+Requires-Dist: psycopg-pool>=3.2; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'all'
+Requires-Dist: pyodbc<6,>=5.0; extra == 'all'
+Requires-Dist: python-multipart>=0.0.9; extra == 'all'
+Requires-Dist: uvicorn>=0.30; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic<2,>=1.0; extra == 'anthropic'
+Provides-Extra: bastion
+Requires-Dist: bastion-prompt-protection<2,>=1.3; extra == 'bastion'
+Provides-Extra: databricks
+Requires-Dist: databricks-sql-connector<5,>=3.4; extra == 'databricks'
+Provides-Extra: deep
+Requires-Dist: deepagents<1,>=0.7; extra == 'deep'
+Provides-Extra: dev
+Requires-Dist: fastapi==0.141.1; extra == 'dev'
+Requires-Dist: mypy==1.19.1; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=1.4; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.14.10; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: langchain-mcp-adapters<0.4,>=0.3.0; extra == 'mcp'
+Requires-Dist: mcp<2,>=1.25; extra == 'mcp'
+Provides-Extra: mssql
+Requires-Dist: msal<2,>=1.28; extra == 'mssql'
+Requires-Dist: pyodbc<6,>=5.0; extra == 'mssql'
+Provides-Extra: ollama
+Requires-Dist: langchain-ollama<2,>=1.0; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: langchain-openai<2,>=1.0; extra == 'openai'
+Provides-Extra: postgres
+Requires-Dist: langgraph-checkpoint-postgres<4,>=3.1; extra == 'postgres'
+Requires-Dist: psycopg-pool>=3.2; extra == 'postgres'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
+Provides-Extra: server
+Requires-Dist: fastapi<0.142,>=0.115; extra == 'server'
+Requires-Dist: langchain-mcp-adapters<0.4,>=0.3.0; extra == 'server'
+Requires-Dist: langgraph-checkpoint-sqlite>=3.1; extra == 'server'
+Requires-Dist: mcp<2,>=1.25; extra == 'server'
+Requires-Dist: python-multipart>=0.0.9; extra == 'server'
+Requires-Dist: uvicorn>=0.30; extra == 'server'
+Provides-Extra: sqlite
+Requires-Dist: langgraph-checkpoint-sqlite>=3.1; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# OpenStateGraph
+
+> **Who this page is for:** you are adding OpenStateGraph to a project you already have,
+> from a package index. This is the distribution's own page; there is no
+> checkout in it.
+
+**A compiler from a vendor-neutral `workflow.json` to a LangGraph
+`StateGraph`.** Not an execution engine — the thing it produces is a plain
+compiled LangGraph object that runs, streams, checkpoints and deploys
+anywhere Python runs, with or without this package's editor.
+
+```bash
+pip install "openstategraph[ollama]==0.3.0rc18"
+```
+
+That is the line that works today, and it names no index because it needs
+none: **this is on PyPI**. The `--index-url` / `--extra-index-url` pair this
+block carried until `0.3.0rc18` was the cost of a TestPyPI-only distribution,
+and that is over.
+
+The `==` is the one thing left to explain, and it is there because the version
+above is a **pre-release**. pip excludes pre-releases from an unpinned
+requirement — the same trap
+[`../docs/building-an-atom.md`](../docs/building-an-atom.md) records for a
+plugin's `>=` specifier — so `pip install "openstategraph[ollama]"` with no
+`==` resolves nothing, and pip reports that as a package it cannot find rather
+than as a candidate it skipped. The pin goes away with the first final release;
+[`../docs/releasing.md`](../docs/releasing.md) is the page that says how a
+version gets here, and holds the TestPyPI rehearsal form for maintainers.
+
+The day a **final** release lands, the pin goes too and this collapses to the
+one line it should always have been:
+
+```bash
+pip install "openstategraph[ollama]"          # once a final release is published
+```
+
+Either way you can install the identical artifact from a checkout —
+`pip install -e "backend[ollama]"` from the repository root, or build the
+wheel with `python3 -m build backend` — which is what CI's `clean-install`
+job does, into an empty virtualenv outside the repository.
+
+```python
+from openstategraph import load_workflow
+
+workflow = load_workflow("path/to/my-workflow")
+print(workflow.ask("How many invoices are there?"))
+```
+
+`load_workflow` takes the one thing an adopter actually has — the package
+folder holding `workflow.json` — and wires the package's own `tools/`,
+`functions/`, `middlewares/`, `skills/` and `knowledge/` before compiling.
+Anything it could not resolve lands on `.warnings` and logs a WARNING, because
+the alternative failure mode is a workflow that answers confidently without
+the tools it was drawn with.
+
+`workflow.graph` is the escape hatch: the compiled LangGraph object, with
+nothing of ours in the way.
+
+## Install footprint
+
+The core is four dependencies — `langgraph`, `langchain`, `langchain-core`,
+`pydantic`. Never "four packages": **package** is a settled word here for
+`workflows/<slug>/` (CLAUDE.md's lexicon), and `backend/pyproject.toml` names
+this line as the place the other sense kept being copied to. Everything else is an extra, because a consumer of `load_workflow`
+should not install a web server or three provider SDKs to run a graph in
+their own process.
+
+| Extra | Install it for |
+| --- | --- |
+| `[anthropic]` / `[openai]` / `[ollama]` | a `model` string starting `anthropic:` / `openai:` / `ollama:` |
+| `[deep]` | a document containing an `agent.deep` node |
+| `[sqlite]` | `settings.checkpointer: "sqlite"`, or `OPENSTATEGRAPH_MEMORY_PATH` |
+| `[server]` | the editor's HTTP API (`openstategraph.api.main`) — the **web layer only**, so pair it with a provider extra (`[server,ollama]`) or the editor opens onto workflows it cannot run. Includes `[mcp]`, so `openstategraph mcp` works after this extra alone |
+| `[mcp]` | the MCP transport (`openstategraph.mcp_server`) on its own, with no web server |
+| `[all]` | everything above — what a checkout of this repo wants |
+| `[dev]` | contributors (pytest, ruff) |
+
+Each of those is imported lazily at its one call site, and a missing one
+raises an `ImportError` naming the exact `pip install` line rather than
+degrading quietly.
+
+## Public surface and stability
+
+`openstategraph.__all__` and `openstategraph.abc.__all__` are the semver-public
+surface, plus `openstategraph.errors` and the `workflow.json` schema itself.
+Everything under `openstategraph.api.*` and `openstategraph.mcp_server` is
+internal and carries no stability guarantee. See
+[`docs/stability.md`](../docs/stability.md) for the deprecation policy — the
+short version is that pre-1.0, a breaking change bumps the **minor**, never the
+patch.
+
+MIT licensed. Full documentation lives in the repository's `docs/`.

openstategraph-0.3.0rc18/README.md

@@ -0,0 +1,93 @@
+# OpenStateGraph
+
+> **Who this page is for:** you are adding OpenStateGraph to a project you already have,
+> from a package index. This is the distribution's own page; there is no
+> checkout in it.
+
+**A compiler from a vendor-neutral `workflow.json` to a LangGraph
+`StateGraph`.** Not an execution engine — the thing it produces is a plain
+compiled LangGraph object that runs, streams, checkpoints and deploys
+anywhere Python runs, with or without this package's editor.
+
+```bash
+pip install "openstategraph[ollama]==0.3.0rc18"
+```
+
+That is the line that works today, and it names no index because it needs
+none: **this is on PyPI**. The `--index-url` / `--extra-index-url` pair this
+block carried until `0.3.0rc18` was the cost of a TestPyPI-only distribution,
+and that is over.
+
+The `==` is the one thing left to explain, and it is there because the version
+above is a **pre-release**. pip excludes pre-releases from an unpinned
+requirement — the same trap
+[`../docs/building-an-atom.md`](../docs/building-an-atom.md) records for a
+plugin's `>=` specifier — so `pip install "openstategraph[ollama]"` with no
+`==` resolves nothing, and pip reports that as a package it cannot find rather
+than as a candidate it skipped. The pin goes away with the first final release;
+[`../docs/releasing.md`](../docs/releasing.md) is the page that says how a
+version gets here, and holds the TestPyPI rehearsal form for maintainers.
+
+The day a **final** release lands, the pin goes too and this collapses to the
+one line it should always have been:
+
+```bash
+pip install "openstategraph[ollama]"          # once a final release is published
+```
+
+Either way you can install the identical artifact from a checkout —
+`pip install -e "backend[ollama]"` from the repository root, or build the
+wheel with `python3 -m build backend` — which is what CI's `clean-install`
+job does, into an empty virtualenv outside the repository.
+
+```python
+from openstategraph import load_workflow
+
+workflow = load_workflow("path/to/my-workflow")
+print(workflow.ask("How many invoices are there?"))
+```
+
+`load_workflow` takes the one thing an adopter actually has — the package
+folder holding `workflow.json` — and wires the package's own `tools/`,
+`functions/`, `middlewares/`, `skills/` and `knowledge/` before compiling.
+Anything it could not resolve lands on `.warnings` and logs a WARNING, because
+the alternative failure mode is a workflow that answers confidently without
+the tools it was drawn with.
+
+`workflow.graph` is the escape hatch: the compiled LangGraph object, with
+nothing of ours in the way.
+
+## Install footprint
+
+The core is four dependencies — `langgraph`, `langchain`, `langchain-core`,
+`pydantic`. Never "four packages": **package** is a settled word here for
+`workflows/<slug>/` (CLAUDE.md's lexicon), and `backend/pyproject.toml` names
+this line as the place the other sense kept being copied to. Everything else is an extra, because a consumer of `load_workflow`
+should not install a web server or three provider SDKs to run a graph in
+their own process.
+
+| Extra | Install it for |
+| --- | --- |
+| `[anthropic]` / `[openai]` / `[ollama]` | a `model` string starting `anthropic:` / `openai:` / `ollama:` |
+| `[deep]` | a document containing an `agent.deep` node |
+| `[sqlite]` | `settings.checkpointer: "sqlite"`, or `OPENSTATEGRAPH_MEMORY_PATH` |
+| `[server]` | the editor's HTTP API (`openstategraph.api.main`) — the **web layer only**, so pair it with a provider extra (`[server,ollama]`) or the editor opens onto workflows it cannot run. Includes `[mcp]`, so `openstategraph mcp` works after this extra alone |
+| `[mcp]` | the MCP transport (`openstategraph.mcp_server`) on its own, with no web server |
+| `[all]` | everything above — what a checkout of this repo wants |
+| `[dev]` | contributors (pytest, ruff) |
+
+Each of those is imported lazily at its one call site, and a missing one
+raises an `ImportError` naming the exact `pip install` line rather than
+degrading quietly.
+
+## Public surface and stability
+
+`openstategraph.__all__` and `openstategraph.abc.__all__` are the semver-public
+surface, plus `openstategraph.errors` and the `workflow.json` schema itself.
+Everything under `openstategraph.api.*` and `openstategraph.mcp_server` is
+internal and carries no stability guarantee. See
+[`docs/stability.md`](../docs/stability.md) for the deprecation policy — the
+short version is that pre-1.0, a breaking change bumps the **minor**, never the
+patch.
+
+MIT licensed. Full documentation lives in the repository's `docs/`.

openstategraph-0.3.0rc18/hatch_build.py

@@ -0,0 +1,269 @@
+"""The wheel carries the canvas — scale-and-adopt ticket 01.
+
+`pip install openstategraph` used to deliver a *visual* workflow builder with
+no visuals: 215 KB of Python, and a canvas that existed only inside a git clone
+or the Docker image. This hook is what puts the built editor in the
+distribution, so `pip install "openstategraph[server]" && openstategraph serve`
+opens the real product on a machine that has never seen the repository.
+
+**Where the assets come from**, in order:
+
+1. `OPENSTATEGRAPH_EDITOR_DIST` — an explicit directory, for a release job that
+   builds the front end somewhere else.
+2. `<repo>/dist` — what `npm run build` writes in a checkout.
+3. `openstategraph/api/static/editor` — already in place, which is the case
+   when a wheel is being built *from our sdist*. Nothing to copy; hatchling
+   ships it as ordinary package data.
+
+**Sourcemaps are excluded.** They are 18 MB against the bundle's 5, they are a
+debugging aid for people working on this repository, and nobody debugging their
+own workflow needs to step through our minified React.
+
+**A standard build with no editor anywhere FAILS, loudly.** That is the whole
+point of the ticket: a wheel that silently ships without the canvas is exactly
+the artifact we are replacing. Editable installs (`pip install -e backend`) are
+exempt, because that is the contributor path — CI installs the backend that way
+with no Node.js in the job, and a source checkout is expected to run the dev
+stack or `npm run build` when it wants the editor.
+
+The decision lives in `editor_force_include`, a free function over paths, so
+`backend/tests/test_distribution_metadata.py` can exercise the failure without
+running a build. The class below is the hatchling adapter and nothing else.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+try:
+    from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+except ModuleNotFoundError:  # pragma: no cover — outside a build environment
+    # hatchling is a build-time dependency and is not installed in the dev
+    # venv. The adapter is unusable without it; the logic below is not, and
+    # that is the half worth testing.
+    BuildHookInterface = object  # type: ignore[assignment,misc]
+
+#: Inside the package, so it is ordinary package data once written and every
+#: consumer (`api/editor_assets.py`) has one place to look.
+EDITOR_DEST = "openstategraph/api/static/editor"
+
+#: The /chat live-flow view's Mermaid, served by `api/main.py:chat_mermaid_asset`
+#: with no CDN. Kept out of `editor/` so that directory stays a faithful copy of
+#: `dist/`.
+VENDOR_DEST = "openstategraph/api/static/vendor"
+
+MERMAID_SOURCE = "node_modules/mermaid/dist/mermaid.min.js"
+
+#: The hand-written story pages — landing, gallery, and the five-artifact
+#: walk-through — served by `api/routes/site.py`. Production-ready ticket 28:
+#: their only route to a reader was GitHub Pages, which has never once
+#: published them, so the wheel carries them and `serve` hands them out.
+SITE_DEST = "openstategraph/api/static/site"
+
+#: Debugging aids for this repository, not for an adopter. 18 MB of the 23 MB
+#: `dist/` weighs.
+EXCLUDED_SUFFIXES = (".map",)
+
+NOT_BUILT = (
+    "no built editor found — the wheel would ship a visual workflow builder "
+    "with no visuals.\n"
+    "Build it first:\n"
+    "    npm ci && npm run build\n"
+    "or point the build at an existing one:\n"
+    "    OPENSTATEGRAPH_EDITOR_DIST=/path/to/dist python -m build backend"
+)
+
+
+STALE = (
+    "the built editor is stale — `dist/` is older than `src/`, so the wheel "
+    "would ship an editor built before the code it is packaged with.\n"
+    "Rebuild it:\n"
+    "    npm run build\n"
+    "or point the build at a current one:\n"
+    "    OPENSTATEGRAPH_EDITOR_DIST=/path/to/dist python -m build backend"
+)
+
+#: Suffixes worth comparing. Everything the editor is actually built from;
+#: a stray `.md` beside a component should not force a rebuild.
+_SOURCE_SUFFIXES = (".ts", ".tsx", ".css", ".html")
+
+
+#: What makes a glob a *test* glob rather than any other glob in those configs.
+#:
+#: The discriminator is the safety property, not a convenience. `vite.config.ts`
+#: also carries `coverage.include` (`src/core/**`, `src/controller/**`) — real
+#: bundle inputs, in the same file, one array away. Taking one of those for an
+#: exclusion would hide the entire core from the staleness walk: a false
+#: negative, which is the side `editor_is_stale` says is unacceptable to pay.
+#: A glob naming `*.test.*`, `*.spec.*` or `*.stories.*` cannot be a bundle
+#: input, whichever array it was found in.
+_TEST_FILE_MARKERS = (".test.", ".spec.", ".stories.")
+
+
+def bundle_excluded_globs(repo_root: Path) -> tuple[str, ...]:
+    """The globs naming files `vite build` cannot put in the bundle.
+
+    Read out of the vitest configs (`vite*.config.ts`) rather than kept here as
+    a second list of suffixes. The JavaScript side already declares what a test
+    file is — `include: ['src/**/*.test.ts']` and the generator's
+    `['src/nodes/portSpecs.emit.spec.ts']` — and two lists of the same fact
+    drift the first time either side adds a convention.
+
+    Empty when there is no config to read, which excludes nothing: not knowing
+    is a reason to compare more files, never fewer.
+    """
+    globs: list[str] = []
+    for config in sorted(repo_root.glob("vite*.config.ts")):
+        try:
+            source = config.read_text(encoding="utf-8")
+        except OSError:  # pragma: no cover — unreadable config, compare everything
+            continue
+        for quoted in re.findall(r"""['"]([^'"\n]+)['"]""", source):
+            leaf = quoted.rsplit("/", 1)[-1]
+            if any(marker in leaf for marker in _TEST_FILE_MARKERS) and quoted not in globs:
+                globs.append(quoted)
+    return tuple(globs)
+
+
+@lru_cache(maxsize=None)
+def _glob_pattern(glob: str) -> re.Pattern[str]:
+    escaped = re.escape(glob)
+    body = escaped.replace(r"\*\*/", "(?:[^/]+/)*").replace(r"\*\*", ".*").replace(r"\*", "[^/]*")
+    return re.compile(f"{body}$")
+
+
+def _is_excluded(relative: str, globs: tuple[str, ...]) -> bool:
+    return any(_glob_pattern(glob).match(relative) for glob in globs)
+
+
+def editor_is_stale(dist: Path, src: Path, repo_root: Path | None = None) -> bool:
+    """Whether `dist/` predates the sources it was supposed to be built from.
+
+    Modification times, not hashes: the question is "did somebody edit the
+    editor and forget to rebuild", and an mtime answers it in milliseconds
+    without a content index. False negatives are possible (a touched file with
+    no change) and cost one needless rebuild; a false *positive* would ship the
+    defect this exists to catch, which is the asymmetry that decides the
+    method.
+
+    `False` when there is no source tree at all — a wheel built from our own
+    sdist has package data and no `src/`, and refusing there would break every
+    downstream repackager over a check that cannot apply.
+
+    **Only files the bundle can contain are compared.** Test files are `.ts`,
+    `vitest` collects them and Vite never bundles them, so touching one cannot
+    change a byte of what the wheel ships — yet it used to demand
+    `npm run build`, and did, at `HEAD`, over
+    `src/nodes/guard/GuardrailNode.test.ts`. That is the harmless direction of
+    the asymmetry above, and it is still the expensive one: a gate that is red
+    for a reason nobody believes is a gate people clear with a reflex rebuild,
+    and then it is checking nothing. `bundle_excluded_globs` narrows the input;
+    the rule is unchanged.
+    """
+    index = dist / "index.html"
+    if not index.is_file() or not src.is_dir():
+        return False
+
+    root = repo_root if repo_root is not None else src.parent
+    excluded = bundle_excluded_globs(root)
+
+    built = index.stat().st_mtime
+    for path in src.rglob("*"):
+        if path.suffix in _SOURCE_SUFFIXES and path.is_file():
+            if path.stat().st_mtime <= built:
+                continue
+            try:
+                relative = path.relative_to(root).as_posix()
+            except ValueError:  # pragma: no cover — src outside the repo root
+                return True
+            if not _is_excluded(relative, excluded):
+                return True
+    return False
+
+
+def _editor_source(root: Path) -> Path | None:
+    explicit = os.environ.get("OPENSTATEGRAPH_EDITOR_DIST", "").strip()
+    candidate = Path(explicit) if explicit else root.parent / "dist"
+    return candidate if (candidate / "index.html").is_file() else None
+
+
+def _mermaid_source(root: Path) -> Path | None:
+    """Optional, and only because it is optional at runtime too: without it
+    `/chat` still works and its flow panel says so."""
+    explicit = os.environ.get("OPENSTATEGRAPH_MERMAID_ASSET", "").strip()
+    candidate = Path(explicit) if explicit else root.parent / MERMAID_SOURCE
+    return candidate if candidate.is_file() else None
+
+
+def editor_force_include(root: Path, version: str) -> dict[str, str]:
+    """Source path → path inside the distribution, for every asset to ship."""
+    if (root / EDITOR_DEST / "index.html").is_file():
+        # Building from our own sdist: the assets are already package data.
+        return {}
+
+    source = _editor_source(root)
+    if source is None:
+        if version == "editable":
+            return {}
+        raise RuntimeError(NOT_BUILT)
+
+    # A missing editor already fails loudly; an *old* one used to ship in
+    # silence. The wheel carried an editor three days behind the backend it was
+    # packaged with — including a schema version, which the two sides must
+    # agree on or the editor refuses documents the backend writes.
+    if version != "editable" and editor_is_stale(source, root.parent / "src"):
+        raise RuntimeError(STALE)
+
+    include = {
+        str(path): f"{EDITOR_DEST}/{path.relative_to(source).as_posix()}"
+        for path in sorted(source.rglob("*"))
+        if path.is_file() and path.suffix not in EXCLUDED_SUFFIXES
+    }
+
+    mermaid = _mermaid_source(root)
+    if mermaid is not None:
+        include[str(mermaid)] = f"{VENDOR_DEST}/mermaid.min.js"
+    return include
+
+
+def site_force_include(root: Path) -> dict[str, str]:
+    """The `site/*.html` pages, source path → path inside the distribution.
+
+    Its own function rather than a few more lines inside `editor_force_include`,
+    because that one returns early in two cases that have nothing to do with
+    these files — an sdist rebuild, and an editable install with no `dist/` —
+    and folding the pages in there would make shipping them depend on whether
+    somebody had run `npm run build`.
+
+    Optional, like the mermaid asset and unlike the editor: absence is a 404
+    with a sentence rather than a broken product, so it is not worth failing a
+    build over. `test_site_pages.py` asserts *this* repository ships all three,
+    which is the case that would otherwise regress in silence.
+    """
+    if (root / SITE_DEST / "gallery.html").is_file():
+        # Building from our own sdist: already package data.
+        return {}
+
+    source = root.parent / "site"
+    if not (source / "gallery.html").is_file():
+        return {}
+
+    return {
+        str(path): f"{SITE_DEST}/{path.name}"
+        for path in sorted(source.glob("*.html"))
+    }
+
+
+class EditorAssetsBuildHook(BuildHookInterface):  # type: ignore[misc,valid-type]
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if self.target_name not in ("wheel", "sdist"):
+            return
+        include = build_data.setdefault("force_include", {})
+        include.update(editor_force_include(Path(self.root), version))
+        include.update(site_force_include(Path(self.root)))