taskdependencygraph 0.1.0__tar.gz → 0.2.0__tar.gz

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/dependabot.yml

@@ -9,8 +9,6 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"
-    reviewers:
-      - "@Hochfrequenz/python-developers-review-team"
   # Maintain dependencies for GitHub Actions
   - package-ecosystem: "github-actions"
     directory: "/"

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/codeql-analysis.yml

@@ -38,11 +38,11 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
+        uses: github/codeql-action/init@v4
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -53,7 +53,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v3
+        uses: github/codeql-action/autobuild@v4
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -67,4 +67,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
+        uses: github/codeql-action/analyze@v4

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/coverage.yml

@@ -6,17 +6,13 @@ on:
   pull_request: {}
 jobs:
   coverage:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        python-version: ["3.13"]
-        os: [ubuntu-latest]
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.14"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/dev_test.yml

@@ -11,12 +11,12 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Dependencies

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/formatting.yml

@@ -6,18 +6,16 @@ on:
   pull_request: {}
 jobs:
   black:
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.13"]
-        os: [ubuntu-latest]
         tool: ["black", "isort"]
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.14"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/no_byte_order_mark.yml

@@ -10,6 +10,6 @@ jobs:
   bom-check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: arma-actions/bom-check@v1
         name: Check for BOM

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/packaging_test.yml

@@ -12,9 +12,9 @@ jobs:
         python-version: ["3.13"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/python-publish.yml

@@ -20,9 +20,9 @@
          python-version: ["3.13"]
          os: [ubuntu-latest]
      steps:
-       - uses: actions/checkout@v4
+       - uses: actions/checkout@v6
        - name: Set up Python ${{ matrix.python-version }}
-         uses: actions/setup-python@v5
+         uses: actions/setup-python@v6
          with:
            python-version: ${{ matrix.python-version }}
        - name: Install tox
@@ -48,9 +48,9 @@
          id-token: write
      needs: tests
      steps:
-       - uses: actions/checkout@v4
+       - uses: actions/checkout@v6
        - name: Set up Python ${{ matrix.python-version }}
-         uses: actions/setup-python@v5
+         uses: actions/setup-python@v6
          with:
            python-version: ${{ matrix.python-version }}
        - name: Install dependencies

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/pythonlint.yml

@@ -7,18 +7,16 @@ on:
 jobs:
   pylint:
     name: Python Code Quality and Lint
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.13"]
-        os: [ubuntu-latest]
         linter-env: ["linting", "type_check", "spell_check"]
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.14"
       - name: Install Dependencies
         run: |
           python -m pip install --upgrade pip

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/.github/workflows/unittests.yml

@@ -9,12 +9,12 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Dependencies

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskdependencygraph
-Version: 0.1.0
+Version: 0.2.0
 Summary: Wrapper around a NetworkX Digraph to model and visualize tasks/todos, their duration and interdependencies
 Project-URL: Changelog, https://github.com/Hochfrequenz/task-dependency-graph/releases
 Project-URL: Homepage, https://github.com/Hochfrequenz/task-dependency-graph
@@ -17,31 +17,32 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Requires-Dist: aiohttp
 Requires-Dist: networkx
 Requires-Dist: pydantic-settings
 Requires-Dist: pydantic[email]>=2
 Provides-Extra: coverage
-Requires-Dist: coverage==7.6.12; extra == 'coverage'
+Requires-Dist: coverage==7.9.1; extra == 'coverage'
 Provides-Extra: dev
 Requires-Dist: pip-tools; extra == 'dev'
 Provides-Extra: formatting
-Requires-Dist: black==25.1.0; extra == 'formatting'
-Requires-Dist: isort==6.0.1; extra == 'formatting'
+Requires-Dist: black==26.5.1; extra == 'formatting'
+Requires-Dist: isort==8.0.1; extra == 'formatting'
 Provides-Extra: linting
-Requires-Dist: pylint==3.3.4; extra == 'linting'
+Requires-Dist: pylint==4.0.5; extra == 'linting'
 Provides-Extra: packaging
 Requires-Dist: build==1.2.2.post1; extra == 'packaging'
 Requires-Dist: twine==6.1.0; extra == 'packaging'
 Provides-Extra: spell-check
 Requires-Dist: codespell==2.4.1; extra == 'spell-check'
 Provides-Extra: tests
-Requires-Dist: pytest-asyncio==0.21.2; extra == 'tests'
-Requires-Dist: pytest==8.3.5; extra == 'tests'
+Requires-Dist: pytest-asyncio==1.1.0; extra == 'tests'
+Requires-Dist: pytest==8.4.2; extra == 'tests'
 Requires-Dist: testcontainers; extra == 'tests'
 Provides-Extra: type-check
-Requires-Dist: mypy==1.15.0; extra == 'type-check'
+Requires-Dist: mypy==2.1.0; extra == 'type-check'
 Requires-Dist: types-docker; extra == 'type-check'
 Description-Content-Type: text/markdown
 
@@ -87,9 +88,7 @@ my_task = TaskNode(
     name="Shop groceries",  # human readable description
     external_id="some unique string",  # technical ID for those who don't like uuids ;)
     planned_duration=timedelta(minutes=15)  # how long it probably takes
-    # You may also add an assignees or an earliest_possible_start
-    # (The latter is useful, when e.g. the supermarket opens at 7am and you cannot shop groceries before,
-    # even if you were awake and have nothing else todo.)
+    # You may also add an assignee, phase, tags, earliest_starttime, is_milestone, or execution_status
 )
 ```
 
@@ -147,12 +146,14 @@ tdg = TaskDependencyGraph(
 )
 ```
 
-Now you can
+Once you have a graph, you can:
 
-* calculate at which time which task is scheduled to start depending on which predecessors it has,
-* find out which tasks are 'critical' in sense that if they're delayed, then the finishing time of the last node is also
-  delayed,
-* assign persons to tasks and check if any person has more than one task assigned at a time.
+* **Validate the definition** before construction — `TaskDependencyGraph.validate_definition(task_list, dependency_list)` checks for duplicate task/dependency IDs, duplicate external IDs, missing edge endpoints, invalid milestone durations, duplicate edge pairs, and cycles, returning a `GraphDefinitionValidationResult`.
+* **Get the full schedule** — `tdg.create_schedule_report()` returns a `ScheduleReport` with planned start/finish, critical-path flag, and total slack for every task.
+* **Inspect the critical path** — `tdg.get_critical_path_tasks()` returns the ordered list of `TaskNode` objects on the critical path.
+* **Calculate total slack** — `tdg.calculate_total_slack_of_task(task_id)` returns how much a task can slip without affecting the deadline.
+* **Query finish times** — `tdg.calculate_planned_finish_time_of_task(task_id)` and `tdg.calculate_planned_finish_time_of_graph()`.
+* Assign persons to tasks and check if any person has more than one task assigned at a time.
 
 Find a complete working example in [the demo unittest](unittests/test_demonstration.py).
 This demo test is also the basis for the following visualization examples.
@@ -166,7 +167,7 @@ docker container:
 # docker-compose.yaml
 services:
   kroki: # see https://docs.kroki.io/kroki/setup/use-docker-or-podman/#_run_multiple_kroki_containers_together
-    image: yuzutech/kroki:0.24.1
+    image: yuzutech/kroki:0.30.1
     depends_on:
       - mermaid
     environment:
@@ -213,6 +214,9 @@ Shopping' done before starting with the next step, even though there's no "real"
 buying the strawberries.)
 The Gantt chart is useful to get an overview of your project and to identify which tasks are crucial.
 
+The Gantt output is customizable via `MermaidGanttConfig` — you can set the title, axis format, tick interval, and
+group tasks into sections by their `phase` field.
+
 ### Raw Graph ("dot" engine)
 
 ![](unittests/baking_a_cake_dot.svg)

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/README.md

@@ -40,9 +40,7 @@ my_task = TaskNode(
     name="Shop groceries",  # human readable description
     external_id="some unique string",  # technical ID for those who don't like uuids ;)
     planned_duration=timedelta(minutes=15)  # how long it probably takes
-    # You may also add an assignees or an earliest_possible_start
-    # (The latter is useful, when e.g. the supermarket opens at 7am and you cannot shop groceries before,
-    # even if you were awake and have nothing else todo.)
+    # You may also add an assignee, phase, tags, earliest_starttime, is_milestone, or execution_status
 )
 ```
 
@@ -100,12 +98,14 @@ tdg = TaskDependencyGraph(
 )
 ```
 
-Now you can
+Once you have a graph, you can:
 
-* calculate at which time which task is scheduled to start depending on which predecessors it has,
-* find out which tasks are 'critical' in sense that if they're delayed, then the finishing time of the last node is also
-  delayed,
-* assign persons to tasks and check if any person has more than one task assigned at a time.
+* **Validate the definition** before construction — `TaskDependencyGraph.validate_definition(task_list, dependency_list)` checks for duplicate task/dependency IDs, duplicate external IDs, missing edge endpoints, invalid milestone durations, duplicate edge pairs, and cycles, returning a `GraphDefinitionValidationResult`.
+* **Get the full schedule** — `tdg.create_schedule_report()` returns a `ScheduleReport` with planned start/finish, critical-path flag, and total slack for every task.
+* **Inspect the critical path** — `tdg.get_critical_path_tasks()` returns the ordered list of `TaskNode` objects on the critical path.
+* **Calculate total slack** — `tdg.calculate_total_slack_of_task(task_id)` returns how much a task can slip without affecting the deadline.
+* **Query finish times** — `tdg.calculate_planned_finish_time_of_task(task_id)` and `tdg.calculate_planned_finish_time_of_graph()`.
+* Assign persons to tasks and check if any person has more than one task assigned at a time.
 
 Find a complete working example in [the demo unittest](unittests/test_demonstration.py).
 This demo test is also the basis for the following visualization examples.
@@ -119,7 +119,7 @@ docker container:
 # docker-compose.yaml
 services:
   kroki: # see https://docs.kroki.io/kroki/setup/use-docker-or-podman/#_run_multiple_kroki_containers_together
-    image: yuzutech/kroki:0.24.1
+    image: yuzutech/kroki:0.30.1
     depends_on:
       - mermaid
     environment:
@@ -166,6 +166,9 @@ Shopping' done before starting with the next step, even though there's no "real"
 buying the strawberries.)
 The Gantt chart is useful to get an overview of your project and to identify which tasks are crucial.
 
+The Gantt output is customizable via `MermaidGanttConfig` — you can set the title, axis format, tick interval, and
+group tasks into sections by their `phase` field.
+
 ### Raw Graph ("dot" engine)
 
 ![](unittests/baking_a_cake_dot.svg)

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/pyproject.toml

@@ -16,6 +16,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
     "pydantic[email]>=2",
@@ -27,27 +28,27 @@ dynamic = ["readme", "version"]
 
 [project.optional-dependencies]
 tests = [
-    "pytest==8.3.5",
-    "pytest-asyncio==0.21.2",
+    "pytest==8.4.2",
+    "pytest-asyncio==1.1.0",
     "testcontainers",
     # "syrupy==4.8.2"
 ]
 linting = [
-    "pylint==3.3.4"
+    "pylint==4.0.5"
 ]
 type_check = [
-    "mypy==1.15.0",
+    "mypy==2.1.0",
     "types-docker"
 ]
 spell_check = [
     "codespell==2.4.1"
 ]
 coverage = [
-    "coverage==7.6.12"
+    "coverage==7.9.1"
 ]
 formatting = [
-    "black==25.1.0",
-    "isort==6.0.1"
+    "black==26.5.1",
+    "isort==8.0.1"
 ]
 packaging = [
     "build==1.2.2.post1",
@@ -64,7 +65,7 @@ Homepage = "https://github.com/Hochfrequenz/task-dependency-graph"
 
 [tool.black]
 line-length = 120
-target_version = ["py311", "py312", "py313"]
+target_version = ["py311", "py312", "py313", "py314"]
 
 [tool.isort]
 line_length = 120
@@ -109,4 +110,4 @@ sources = ["src"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-# markers = ["snapshot: mark a test as a snapshot test"]
+# markers = ["snapshot: mark a test as a snapshot test"]

taskdependencygraph-0.2.0/requirements.txt

@@ -0,0 +1,60 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile pyproject.toml
+#
+aiohappyeyeballs==2.6.2
+    # via aiohttp
+aiohttp==3.13.5
+    # via taskdependencygraph (pyproject.toml)
+aiosignal==1.4.0
+    # via aiohttp
+annotated-types==0.7.0
+    # via pydantic
+attrs==26.1.0
+    # via aiohttp
+dnspython==2.8.0
+    # via email-validator
+email-validator==2.3.0
+    # via pydantic
+frozenlist==1.8.0
+    # via
+    #   aiohttp
+    #   aiosignal
+idna==3.16
+    # via
+    #   email-validator
+    #   yarl
+multidict==6.7.1
+    # via
+    #   aiohttp
+    #   yarl
+networkx==3.6.1
+    # via taskdependencygraph (pyproject.toml)
+propcache==0.5.2
+    # via
+    #   aiohttp
+    #   yarl
+pydantic[email]==2.13.4
+    # via
+    #   pydantic-settings
+    #   taskdependencygraph (pyproject.toml)
+pydantic-core==2.46.4
+    # via pydantic
+pydantic-settings==2.14.1
+    # via taskdependencygraph (pyproject.toml)
+python-dotenv==1.2.2
+    # via pydantic-settings
+typing-extensions==4.15.0
+    # via
+    #   aiosignal
+    #   pydantic
+    #   pydantic-core
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   pydantic
+    #   pydantic-settings
+yarl==1.24.2
+    # via aiohttp

taskdependencygraph-0.2.0/src/_taskdependencygraph_version.py

@@ -0,0 +1 @@
+version = "0.2.0"

taskdependencygraph-0.2.0/src/taskdependencygraph/__init__.py

@@ -0,0 +1,59 @@
+"""
+taskdependencygraph is a library to model tasks and dependencies between tasks in a networkx DiGraph
+and give estimates when which task will be done
+"""
+
+# pylint: disable=duplicate-code
+# The __all__ list here intentionally mirrors models/__init__.py — re-exporting is the purpose of this file.
+
+from .models import (
+    ID_OF_ARTIFICIAL_ENDNODE,
+    ID_OF_ARTIFICIAL_STARTNODE,
+    AddEdgeToGraphPreviewResponse,
+    AddNodeToGraphPreviewResponse,
+    GraphDefinitionValidationFinding,
+    GraphDefinitionValidationResult,
+    MermaidGanttConfig,
+    Person,
+    PersonId,
+    RunGroupId,
+    RunGroupPersonRelationId,
+    RunId,
+    ScheduleEntry,
+    ScheduleReport,
+    TaskDependencyEdge,
+    TaskDependencyId,
+    TaskExecutionStatus,
+    TaskId,
+    TaskNode,
+    ValidationCode,
+    task_node_as_artificial_endnode,
+    task_node_as_artificial_startnode,
+)
+from .task_dependency_graph import TaskDependencyGraph
+
+__all__ = [
+    "AddEdgeToGraphPreviewResponse",
+    "AddNodeToGraphPreviewResponse",
+    "GraphDefinitionValidationFinding",
+    "GraphDefinitionValidationResult",
+    "ID_OF_ARTIFICIAL_ENDNODE",
+    "ID_OF_ARTIFICIAL_STARTNODE",
+    "MermaidGanttConfig",
+    "Person",
+    "PersonId",
+    "RunGroupId",
+    "RunGroupPersonRelationId",
+    "RunId",
+    "ScheduleEntry",
+    "ScheduleReport",
+    "TaskDependencyEdge",
+    "TaskDependencyId",
+    "TaskDependencyGraph",
+    "TaskExecutionStatus",
+    "TaskId",
+    "TaskNode",
+    "ValidationCode",
+    "task_node_as_artificial_endnode",
+    "task_node_as_artificial_startnode",
+]

{taskdependencygraph-0.1.0 → taskdependencygraph-0.2.0}/src/taskdependencygraph/models/__init__.py

@@ -1,24 +1,42 @@
 """models are python objects which we use to model tasks, dependencies and the graph they form"""
 
+from .graph_definition_validation import (
+    GraphDefinitionValidationFinding,
+    GraphDefinitionValidationResult,
+    ValidationCode,
+)
 from .ids import PersonId, RunGroupId, RunGroupPersonRelationId, RunId, TaskDependencyId, TaskId
+from .mermaid_gantt_config import MermaidGanttConfig
 from .person import Person
+from .schedule_report import ScheduleEntry, ScheduleReport
 from .task_dependency_edge import TaskDependencyEdge
+from .task_dependency_update import AddEdgeToGraphPreviewResponse, AddNodeToGraphPreviewResponse
 from .task_execution_status import TaskExecutionStatus
 from .task_node import TaskNode
-from .task_node_as_artificial_endnode import ID_OF_ARTIFICIAL_ENDNODE
-from .task_node_as_artificial_startnode import ID_OF_ARTIFICIAL_STARTNODE
+from .task_node_as_artificial_endnode import ID_OF_ARTIFICIAL_ENDNODE, task_node_as_artificial_endnode
+from .task_node_as_artificial_startnode import ID_OF_ARTIFICIAL_STARTNODE, task_node_as_artificial_startnode
 
 __all__ = [
+    "AddEdgeToGraphPreviewResponse",
+    "AddNodeToGraphPreviewResponse",
+    "GraphDefinitionValidationFinding",
+    "GraphDefinitionValidationResult",
+    "ID_OF_ARTIFICIAL_ENDNODE",
+    "ID_OF_ARTIFICIAL_STARTNODE",
+    "MermaidGanttConfig",
     "Person",
-    "RunId",
+    "PersonId",
     "RunGroupId",
     "RunGroupPersonRelationId",
-    "TaskId",
-    "TaskDependencyId",
-    "PersonId",
-    "TaskNode",
+    "RunId",
+    "ScheduleEntry",
+    "ScheduleReport",
     "TaskDependencyEdge",
+    "TaskDependencyId",
     "TaskExecutionStatus",
-    "ID_OF_ARTIFICIAL_ENDNODE",
-    "ID_OF_ARTIFICIAL_STARTNODE",
+    "TaskId",
+    "TaskNode",
+    "ValidationCode",
+    "task_node_as_artificial_endnode",
+    "task_node_as_artificial_startnode",
 ]

taskdependencygraph-0.2.0/src/taskdependencygraph/models/graph_definition_validation.py

@@ -0,0 +1,50 @@
+"""
+Graph definition validation models.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+from taskdependencygraph.models.ids import TaskDependencyId, TaskId
+
+
+class ValidationCode(str, Enum):
+    """Stable codes identifying the kind of graph definition problem found."""
+
+    DUPLICATE_TASK_ID = "DUPLICATE_TASK_ID"
+    DUPLICATE_EXTERNAL_ID = "DUPLICATE_EXTERNAL_ID"
+    MISSING_EDGE_ENDPOINT = "MISSING_EDGE_ENDPOINT"
+    DUPLICATE_DEPENDENCY_ID = "DUPLICATE_DEPENDENCY_ID"
+    DUPLICATE_EDGE_PAIR = "DUPLICATE_EDGE_PAIR"
+    CYCLE = "CYCLE"
+    INVALID_MILESTONE_DURATION = "INVALID_MILESTONE_DURATION"
+
+
+class GraphDefinitionValidationFinding(BaseModel):
+    """A single validation problem found in a graph definition."""
+
+    model_config = ConfigDict(frozen=True)
+
+    code: ValidationCode
+    message: str
+    task_id: TaskId | None = None
+    """The task ID involved in this finding.
+    For MISSING_EDGE_ENDPOINT this may be an ID that does not exist in the task list."""
+    dependency_id: TaskDependencyId | None = None
+
+
+class GraphDefinitionValidationResult(BaseModel):
+    """The aggregated result of validating a raw task/dependency list before graph construction."""
+
+    model_config = ConfigDict(frozen=True)
+
+    is_valid: bool
+    findings: tuple[GraphDefinitionValidationFinding, ...]
+
+
+__all__ = [
+    "GraphDefinitionValidationFinding",
+    "GraphDefinitionValidationResult",
+    "ValidationCode",
+]