signalsafe-tree-spec 0.1.1__tar.gz

signalsafe_tree_spec-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Martin
+
+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.

signalsafe_tree_spec-0.1.1/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: signalsafe-tree-spec
+Version: 0.1.1
+Summary: SignalSafe TreeSpec wire contract for Python: models, parsing, lint, and patch helpers.
+Author: Josh Martin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SignalSafeSoftware/tree-spec-python
+Project-URL: Repository, https://github.com/SignalSafeSoftware/tree-spec-python
+Project-URL: Documentation, https://github.com/SignalSafeSoftware/tree-spec-python#readme
+Project-URL: Issues, https://github.com/SignalSafeSoftware/tree-spec-python/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2.11.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Requires-Dist: flake8>=7; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Dynamic: license-file
+
+# signalsafe-tree-spec (Python)
+
+Python implementation of the **TreeSpec wire contract**: Pydantic models, parsing, lint, patch helpers, and constants. Backend counterpart to [`@signalsafe/tree-spec`](https://github.com/SignalSafeSoftware/tree-spec) on npm.
+
+| | |
+|---|---|
+| **PyPI distribution name** | `signalsafe-tree-spec` |
+| **Import path** | `deliveryplus_tree_spec` (stable; historical name) |
+| **GitHub** | [SignalSafeSoftware/tree-spec-python](https://github.com/SignalSafeSoftware/tree-spec-python) |
+| **Python** | 3.12+ (`requires-python >=3.12,<4.0`) |
+| **Runtime dependency** | Pydantic v2 (`pydantic>=2.11.3,<3`) |
+
+> **License:** MIT — see [LICENSE](./LICENSE). See [SECURITY.md](./SECURITY.md) for vulnerability reporting.
+
+## What this package does
+
+- Validate and parse **TreeSpec wire JSON** into typed Pydantic models (`TreeSpec`, `Node`, `Transition`, …).
+- **Lint** wire payloads (`lint_tree_spec`) with structured issues.
+- **Build** wire documents programmatically (`TreeSpecBuilder`).
+- **Apply JSON patches** to wire dicts (`apply_patch_to_spec_dict`).
+- Expose wire constants (`END_NODE_ID`, `TREESPEC_WIRE_VERSION`).
+
+## What this package does not do
+
+- HTTP APIs, authentication, persistence, or training UI.
+- Scenario simulation (use `@signalsafe/simulator-core` / `simulator-react` in TypeScript stacks).
+- Graph editor UI (use `@signalsafe/tree-spec-editor-*` packages).
+- General sandboxing or authorization — contract validation only; host apps decide trust and access control.
+
+## Install
+
+```bash
+pip install signalsafe-tree-spec
+```
+
+Development (this repo uses [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## Distribution name vs import path
+
+```bash
+pip install signalsafe-tree-spec
+```
+
+```python
+import deliveryplus_tree_spec
+from deliveryplus_tree_spec import TreeSpec, lint_tree_spec, TreeSpecBuilder
+```
+
+The PyPI name (`signalsafe-tree-spec`) differs from the import path (`deliveryplus_tree_spec`) for backward compatibility with existing backends.
+
+## Quick start
+
+```python
+from deliveryplus_tree_spec import (
+    END_NODE_ID,
+    TREESPEC_WIRE_VERSION,
+    TreeSpec,
+    TreeSpecBuilder,
+    lint_tree_spec,
+)
+
+wire = {
+    "wire_version": TREESPEC_WIRE_VERSION,
+    "start_node": "start",
+    "nodes": {
+        "start": {
+            "type": "prompt",
+            "prompt": "Verify the sender before clicking?",
+            "choices": [{"id": "inspect", "label": "Inspect sender"}],
+        }
+    },
+    "transitions": [
+        {"from": ["start", "inspect"], "to": END_NODE_ID, "outcome": "safe"},
+    ],
+}
+
+issues = lint_tree_spec(wire)
+assert not issues
+
+spec = TreeSpec.model_validate(wire)
+builder = TreeSpecBuilder()
+# builder.add_node(...) — see tests/ for full builder flows
+```
+
+## Public API
+
+All symbols below are exported from the top-level `deliveryplus_tree_spec` package:
+
+| Category | Symbols |
+|---|---|
+| Constants | `END_NODE_ID`, `TREESPEC_WIRE_VERSION` |
+| Models | `TreeSpec`, `Node`, `Transition`, `Choice`, `Delta`, `MicroFeedback`, `ABMeta`, `ABVariant`, … |
+| Lint | `lint_tree_spec`, `TreeSpecIssue` |
+| Builder | `TreeSpecBuilder`, `TreeSpecError` |
+| Patch | `apply_patch_to_spec_dict`, `PatchApplyError`, `PatchDict`, `ReplacePatch`, … |
+
+There are no subpath exports — import from `deliveryplus_tree_spec` only.
+
+## Wire contract (high level)
+
+- **`wire_version`:** optional; omit for implicit v1. Constant `TREESPEC_WIRE_VERSION` documents the current version string.
+- **`start_node`:** entry node id.
+- **`nodes`:** map of node id → node object (`type`, `prompt`, `choices` or legacy `options`, optional `render_hints`).
+- **`transitions`:** list of `{ from: [nodeId, choiceId], to, outcome? }`. Terminal transitions target `END_NODE_ID` and require `outcome`.
+- **`_meta`:** optional tree-level metadata (for example graph-editor viewport persisted by editor packages).
+
+Legacy payloads may use `options` instead of `choices` and legacy terminal ids; the TypeScript package normalizes these on compile/decompile. Python lint validates the wire shape your backend accepts.
+
+## Python / TypeScript parity
+
+| Concern | Python (`tree-spec-python`) | TypeScript (`@signalsafe/tree-spec`) |
+|---|---|---|
+| Wire models & lint | Pydantic models, `lint_tree_spec` | `TreeSpecWire`, `lintTreeSpecWire` |
+| Authoring graph compile | — | `compileTreeSpec` / `decompileTreeSpec` |
+| Cross-language fixtures | Share JSON fixtures in your product repo or CI | Same |
+
+Keep fixture JSON in sync when changing wire rules in either language. Full compile/decompile parity lives in TypeScript today; Python focuses on validation, lint, builder, and patch flows used by backends.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run flake8 .
+uv run python -m build   # wheel/sdist smoke — full artifact tests in Batch 6
+```
+
+## Security
+
+See [SECURITY.md](./SECURITY.md). TreeSpec parsing is **contract validation**, not a sandbox. Validate and authorize TreeSpec JSON in your application layer before treating content as trusted.
+
+## Changelog and releases
+
+- [CHANGELOG.md](./CHANGELOG.md)
+- [RELEASING.md](./RELEASING.md)
+
+## Related packages
+
+- [`@signalsafe/tree-spec`](https://github.com/SignalSafeSoftware/tree-spec) — TypeScript wire contract and compile/lint.
+- [`tree-spec-editor-*`](https://github.com/SignalSafeSoftware/tree-spec-editor) — authoring UI (TypeScript/React).

signalsafe_tree_spec-0.1.1/README.md

@@ -0,0 +1,145 @@
+# signalsafe-tree-spec (Python)
+
+Python implementation of the **TreeSpec wire contract**: Pydantic models, parsing, lint, patch helpers, and constants. Backend counterpart to [`@signalsafe/tree-spec`](https://github.com/SignalSafeSoftware/tree-spec) on npm.
+
+| | |
+|---|---|
+| **PyPI distribution name** | `signalsafe-tree-spec` |
+| **Import path** | `deliveryplus_tree_spec` (stable; historical name) |
+| **GitHub** | [SignalSafeSoftware/tree-spec-python](https://github.com/SignalSafeSoftware/tree-spec-python) |
+| **Python** | 3.12+ (`requires-python >=3.12,<4.0`) |
+| **Runtime dependency** | Pydantic v2 (`pydantic>=2.11.3,<3`) |
+
+> **License:** MIT — see [LICENSE](./LICENSE). See [SECURITY.md](./SECURITY.md) for vulnerability reporting.
+
+## What this package does
+
+- Validate and parse **TreeSpec wire JSON** into typed Pydantic models (`TreeSpec`, `Node`, `Transition`, …).
+- **Lint** wire payloads (`lint_tree_spec`) with structured issues.
+- **Build** wire documents programmatically (`TreeSpecBuilder`).
+- **Apply JSON patches** to wire dicts (`apply_patch_to_spec_dict`).
+- Expose wire constants (`END_NODE_ID`, `TREESPEC_WIRE_VERSION`).
+
+## What this package does not do
+
+- HTTP APIs, authentication, persistence, or training UI.
+- Scenario simulation (use `@signalsafe/simulator-core` / `simulator-react` in TypeScript stacks).
+- Graph editor UI (use `@signalsafe/tree-spec-editor-*` packages).
+- General sandboxing or authorization — contract validation only; host apps decide trust and access control.
+
+## Install
+
+```bash
+pip install signalsafe-tree-spec
+```
+
+Development (this repo uses [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## Distribution name vs import path
+
+```bash
+pip install signalsafe-tree-spec
+```
+
+```python
+import deliveryplus_tree_spec
+from deliveryplus_tree_spec import TreeSpec, lint_tree_spec, TreeSpecBuilder
+```
+
+The PyPI name (`signalsafe-tree-spec`) differs from the import path (`deliveryplus_tree_spec`) for backward compatibility with existing backends.
+
+## Quick start
+
+```python
+from deliveryplus_tree_spec import (
+    END_NODE_ID,
+    TREESPEC_WIRE_VERSION,
+    TreeSpec,
+    TreeSpecBuilder,
+    lint_tree_spec,
+)
+
+wire = {
+    "wire_version": TREESPEC_WIRE_VERSION,
+    "start_node": "start",
+    "nodes": {
+        "start": {
+            "type": "prompt",
+            "prompt": "Verify the sender before clicking?",
+            "choices": [{"id": "inspect", "label": "Inspect sender"}],
+        }
+    },
+    "transitions": [
+        {"from": ["start", "inspect"], "to": END_NODE_ID, "outcome": "safe"},
+    ],
+}
+
+issues = lint_tree_spec(wire)
+assert not issues
+
+spec = TreeSpec.model_validate(wire)
+builder = TreeSpecBuilder()
+# builder.add_node(...) — see tests/ for full builder flows
+```
+
+## Public API
+
+All symbols below are exported from the top-level `deliveryplus_tree_spec` package:
+
+| Category | Symbols |
+|---|---|
+| Constants | `END_NODE_ID`, `TREESPEC_WIRE_VERSION` |
+| Models | `TreeSpec`, `Node`, `Transition`, `Choice`, `Delta`, `MicroFeedback`, `ABMeta`, `ABVariant`, … |
+| Lint | `lint_tree_spec`, `TreeSpecIssue` |
+| Builder | `TreeSpecBuilder`, `TreeSpecError` |
+| Patch | `apply_patch_to_spec_dict`, `PatchApplyError`, `PatchDict`, `ReplacePatch`, … |
+
+There are no subpath exports — import from `deliveryplus_tree_spec` only.
+
+## Wire contract (high level)
+
+- **`wire_version`:** optional; omit for implicit v1. Constant `TREESPEC_WIRE_VERSION` documents the current version string.
+- **`start_node`:** entry node id.
+- **`nodes`:** map of node id → node object (`type`, `prompt`, `choices` or legacy `options`, optional `render_hints`).
+- **`transitions`:** list of `{ from: [nodeId, choiceId], to, outcome? }`. Terminal transitions target `END_NODE_ID` and require `outcome`.
+- **`_meta`:** optional tree-level metadata (for example graph-editor viewport persisted by editor packages).
+
+Legacy payloads may use `options` instead of `choices` and legacy terminal ids; the TypeScript package normalizes these on compile/decompile. Python lint validates the wire shape your backend accepts.
+
+## Python / TypeScript parity
+
+| Concern | Python (`tree-spec-python`) | TypeScript (`@signalsafe/tree-spec`) |
+|---|---|---|
+| Wire models & lint | Pydantic models, `lint_tree_spec` | `TreeSpecWire`, `lintTreeSpecWire` |
+| Authoring graph compile | — | `compileTreeSpec` / `decompileTreeSpec` |
+| Cross-language fixtures | Share JSON fixtures in your product repo or CI | Same |
+
+Keep fixture JSON in sync when changing wire rules in either language. Full compile/decompile parity lives in TypeScript today; Python focuses on validation, lint, builder, and patch flows used by backends.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run flake8 .
+uv run python -m build   # wheel/sdist smoke — full artifact tests in Batch 6
+```
+
+## Security
+
+See [SECURITY.md](./SECURITY.md). TreeSpec parsing is **contract validation**, not a sandbox. Validate and authorize TreeSpec JSON in your application layer before treating content as trusted.
+
+## Changelog and releases
+
+- [CHANGELOG.md](./CHANGELOG.md)
+- [RELEASING.md](./RELEASING.md)
+
+## Related packages
+
+- [`@signalsafe/tree-spec`](https://github.com/SignalSafeSoftware/tree-spec) — TypeScript wire contract and compile/lint.
+- [`tree-spec-editor-*`](https://github.com/SignalSafeSoftware/tree-spec-editor) — authoring UI (TypeScript/React).

signalsafe_tree_spec-0.1.1/VERSION

@@ -0,0 +1 @@
+0.1.1

signalsafe_tree_spec-0.1.1/__init__.py

@@ -0,0 +1,54 @@
+"""
+Reusable TreeSpec contract and validation (backend counterpart to ``packages/tree-spec``).
+
+No , HTTP, or simulator UI — wire models, parsing, lint, and patch helpers only.
+
+See ``README.md`` in this package for scope, dependency rules, and cross-language fixtures
+(``contracts/tree-spec/``).
+"""
+
+from deliveryplus_tree_spec.builder import TreeSpecBuilder
+from deliveryplus_tree_spec.builder import TreeSpecError
+from deliveryplus_tree_spec.constants import END_NODE_ID
+from deliveryplus_tree_spec.constants import TREESPEC_WIRE_VERSION
+from deliveryplus_tree_spec.lint import lint_tree_spec
+from deliveryplus_tree_spec.lint import TreeSpecIssue
+from deliveryplus_tree_spec.models import ABMeta
+from deliveryplus_tree_spec.models import ABVariant
+from deliveryplus_tree_spec.models import Choice
+from deliveryplus_tree_spec.models import Delta
+from deliveryplus_tree_spec.models import FeedbackDict
+from deliveryplus_tree_spec.models import MicroFeedback
+from deliveryplus_tree_spec.models import Node
+from deliveryplus_tree_spec.models import PatchDict
+from deliveryplus_tree_spec.models import ReplaceMatch
+from deliveryplus_tree_spec.models import ReplacePatch
+from deliveryplus_tree_spec.models import ReplaceSet
+from deliveryplus_tree_spec.models import Transition
+from deliveryplus_tree_spec.models import TreeSpec
+from deliveryplus_tree_spec.patch import apply_patch_to_spec_dict
+from deliveryplus_tree_spec.patch import PatchApplyError
+
+__all__ = [
+    "ABMeta",
+    "ABVariant",
+    "Choice",
+    "Delta",
+    "END_NODE_ID",
+    "FeedbackDict",
+    "MicroFeedback",
+    "Node",
+    "PatchApplyError",
+    "PatchDict",
+    "ReplaceMatch",
+    "ReplacePatch",
+    "ReplaceSet",
+    "TREESPEC_WIRE_VERSION",
+    "Transition",
+    "TreeSpec",
+    "TreeSpecBuilder",
+    "TreeSpecError",
+    "TreeSpecIssue",
+    "apply_patch_to_spec_dict",
+    "lint_tree_spec",
+]

signalsafe_tree_spec-0.1.1/builder.py

@@ -0,0 +1,98 @@
+"""Parse and navigate TreeSpec; no DB, API, or training heuristics."""
+
+from __future__ import annotations
+from typing import Any
+from typing import Dict
+from typing import Optional
+from pydantic import ValidationError as PydanticValidationError
+from deliveryplus_tree_spec.models import ABMeta
+from deliveryplus_tree_spec.models import MicroFeedback
+from deliveryplus_tree_spec.models import Node
+from deliveryplus_tree_spec.models import Transition
+from deliveryplus_tree_spec.models import TreeSpec
+
+_TREE_SPEC_PARSE_ERRORS = (ValueError, TypeError, KeyError, PydanticValidationError)
+
+
+class TreeSpecError(Exception):
+    """TreeSpec is malformed or internally inconsistent."""
+
+
+class TreeSpecBuilder:
+    """
+    Pure TreeSpec domain logic.
+
+    - Parses and validates TreeSpec
+    - Resolves nodes, choices, transitions
+    - Extracts micro-feedback
+
+    Training/simulator heuristics (e.g. inferring flags from choice id) live in
+    `vega.common.tree_spec.builder`, which extends this class.
+    """
+
+    def __init__(self, spec: TreeSpec):
+        self.spec = spec
+
+    @staticmethod
+    def _parse_tree_spec_or_none(raw: Dict[str, Any]) -> Optional[TreeSpec]:
+        try:
+            return TreeSpec.parse_tree_spec(raw)
+        except _TREE_SPEC_PARSE_ERRORS:
+            return None
+
+    @classmethod
+    def from_raw(cls, raw: Dict[str, Any]) -> "TreeSpecBuilder":
+        try:
+            spec = TreeSpec.parse_tree_spec(raw)
+        except _TREE_SPEC_PARSE_ERRORS as e:
+            raise TreeSpecError(f"Invalid tree_spec: {e}") from e
+        return cls(spec)
+
+    def get_start_node_id(self) -> str:
+        return str(self.spec.start_node)
+
+    def get_node(self, node_id: str) -> Node:
+        try:
+            return self.spec.get_node(node_id)
+        except KeyError as e:
+            raise TreeSpecError(str(e)) from e
+
+    def choice_exists(self, node: Node, choice_id: str) -> bool:
+        return any(c.id == choice_id for c in node.choices)
+
+    def find_transition(self, node_id: str, choice_id: str) -> Transition:
+        for t in self.spec.transitions:
+            if t.from_[0] == node_id and t.from_[1] == choice_id:
+                return t
+        raise TreeSpecError(f"Missing transition for ({node_id}, {choice_id})")
+
+    def extract_micro_feedback(
+        self, *, node_id: str, choice_id: str, transition: Transition
+    ) -> Optional[MicroFeedback]:
+        if transition.feedback:
+            return transition.feedback
+        node = self.get_node(node_id)
+        for c in node.choices:
+            if c.id == choice_id:
+                return c.feedback
+        return None
+
+    @staticmethod
+    def get_ab_meta_from_spec(spec_dict: Dict[str, Any]) -> ABMeta:
+        """Get A/B metadata from tree_spec dict as ABMeta model."""
+        tree_spec = TreeSpecBuilder._parse_tree_spec_or_none(spec_dict)
+        if tree_spec is None:
+            return ABMeta()
+        return tree_spec.ab or ABMeta()
+
+    @staticmethod
+    def update_spec_with_ab_meta(spec_dict: Dict[str, Any], ab_meta: ABMeta) -> None:
+        """Update tree_spec dict with ABMeta. Writes canonical key '_ab' only."""
+        tree_spec = TreeSpecBuilder._parse_tree_spec_or_none(spec_dict)
+        if tree_spec is not None:
+            tree_spec.ab = ab_meta
+            serialized = tree_spec.model_dump(by_alias=True, exclude_none=False).get("_ab")
+            spec_dict["_ab"] = serialized
+            return
+        serialized = ab_meta.model_dump(exclude_none=True)
+        spec_dict["_ab"] = serialized

signalsafe_tree_spec-0.1.1/constants.py

@@ -0,0 +1,12 @@
+"""TreeSpec wire-format constants (aligned with TypeScript `packages/tree-spec`)."""
+
+from __future__ import annotations
+
+# Canonical id for the terminal node in the wire format.
+END_NODE_ID = "END"
+
+# Legacy alias seen in older payloads; may be normalized on read in consumers.
+LEGACY_END_NODE_ID = "__END__"
+
+# Bump when the JSON shape changes (interoperability with TS `TREESPEC_WIRE_VERSION`).
+TREESPEC_WIRE_VERSION = 1

signalsafe_tree_spec-0.1.1/lint.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import List
+from typing import Optional
+from deliveryplus_tree_spec.builder import TreeSpecBuilder
+from deliveryplus_tree_spec.constants import END_NODE_ID
+
+
+@dataclass(frozen=True)
+class TreeSpecIssue:
+    level: str  # "error" | "warning"
+    code: str
+    message: str
+    node_id: Optional[str] = None
+    choice_id: Optional[str] = None
+
+
+def _find_duplicate_transition_keys(builder: TreeSpecBuilder) -> list[tuple[str, str]]:
+    seen: set[tuple[str, str]] = set()
+    dupes: set[tuple[str, str]] = set()
+    for transition in builder.spec.transitions:
+        key = (transition.from_[0], transition.from_[1])
+        if key in seen:
+            dupes.add(key)
+        else:
+            seen.add(key)
+    return sorted(dupes)
+
+
+def _build_duplicate_transition_issues(
+    duplicate_keys: list[tuple[str, str]],
+) -> list[TreeSpecIssue]:
+    return [
+        TreeSpecIssue(
+            level="error",
+            code="duplicate_transition",
+            message=(
+                f"Duplicate transition for ({from_node}, {choice_id}). Each choice must have exactly one transition."
+            ),
+            node_id=from_node,
+            choice_id=choice_id,
+        )
+        for from_node, choice_id in duplicate_keys
+    ]
+
+
+def _build_transition_map(builder: TreeSpecBuilder) -> dict[tuple[str, str], str]:
+    return {
+        (transition.from_[0], transition.from_[1]): transition.to
+        for transition in builder.spec.transitions
+    }
+
+
+def _find_missing_transition_issues(
+    builder: TreeSpecBuilder,
+    trans_map: dict[tuple[str, str], str],
+) -> list[TreeSpecIssue]:
+    issues: list[TreeSpecIssue] = []
+    for node_id, node in builder.spec.nodes.items():
+        for choice in node.choices:
+            if (node_id, choice.id) in trans_map:
+                continue
+            issues.append(
+                TreeSpecIssue(
+                    level="error",
+                    code="missing_transition",
+                    message=f"Missing transition for choice '{choice.id}' on node '{node_id}'.",
+                    node_id=node_id,
+                    choice_id=choice.id,
+                )
+            )
+    return issues
+
+
+def _find_missing_target_node_issues(
+    builder: TreeSpecBuilder,
+    trans_map: dict[tuple[str, str], str],
+) -> list[TreeSpecIssue]:
+    issues: list[TreeSpecIssue] = []
+    for (from_node, choice_id), to_node in trans_map.items():
+        if to_node == END_NODE_ID or to_node in builder.spec.nodes:
+            continue
+        issues.append(
+            TreeSpecIssue(
+                level="error",
+                code="missing_target_node",
+                message=f"Transition ({from_node}, {choice_id}) points to missing node '{to_node}'.",
+                node_id=from_node,
+                choice_id=choice_id,
+            )
+        )
+    return issues
+
+
+def _collect_reachable_nodes(
+    builder: TreeSpecBuilder,
+    trans_map: dict[tuple[str, str], str],
+) -> set[str]:
+    reachable: set[str] = set()
+    stack: list[str] = [builder.get_start_node_id()]
+    while stack:
+        node_id = stack.pop()
+        if node_id in reachable:
+            continue
+        reachable.add(node_id)
+        current = builder.spec.nodes.get(node_id)
+        if current is None:
+            continue
+        for choice in current.choices:
+            next_node = trans_map.get((node_id, choice.id))
+            if not next_node or next_node == END_NODE_ID or next_node in reachable:
+                continue
+            stack.append(next_node)
+    return reachable
+
+
+def _find_unreachable_node_issues(
+    builder: TreeSpecBuilder,
+    reachable: set[str],
+) -> list[TreeSpecIssue]:
+    start_node_id = builder.get_start_node_id()
+    return [
+        TreeSpecIssue(
+            level="warning",
+            code="unreachable_node",
+            message=f"Node '{node_id}' is unreachable from start node '{start_node_id}'.",
+            node_id=node_id,
+        )
+        for node_id in builder.spec.nodes.keys()
+        if node_id not in reachable
+    ]
+
+
+def lint_tree_spec(builder: TreeSpecBuilder) -> List[TreeSpecIssue]:
+    """Domain linting beyond Pydantic shape validation.
+
+    The TreeSpec models enforce structural invariants, but lints catch authoring mistakes:
+    - missing transitions for choices
+    - transitions that point to missing nodes
+    - unreachable nodes
+
+    Keep these rules stable and re-use them across:
+    - seed_demo (--training-content-only)
+    - admin validate endpoint
+    - publish gating
+    """
+
+    duplicate_keys = _find_duplicate_transition_keys(builder)
+    trans_map = _build_transition_map(builder)
+    reachable = _collect_reachable_nodes(builder, trans_map)
+
+    return [
+        *_build_duplicate_transition_issues(duplicate_keys),
+        *_find_missing_transition_issues(builder, trans_map),
+        *_find_missing_target_node_issues(builder, trans_map),
+        *_find_unreachable_node_issues(builder, reachable),
+    ]