flowharness-inspection 0.1.0__tar.gz

flowharness_inspection-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

flowharness_inspection-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: flowharness-inspection
+Version: 0.1.0
+Summary: Inspection context — Architectural Drift Index and risk scan (FLOWHARNESS_SPEC.md §6.12)
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: flowharness-core==0.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/flowharness-ai
+Description-Content-Type: text/markdown
+
+# flowharness-inspection
+
+Inspection context — the static, local, deterministic agent-rules surface scanner. Provides the domain layer for classifying agent-rules surfaces (CLAUDE.md, .cursorrules, AGENTS.md, agent-harness bundles, etc.), reading and parsing them, running architectural drift/contradiction/divergence/risk checks, and scoring findings into a quarantine verdict and drift index.
+
+This is an **internal library package** of the FlowHarness toolchain, published to PyPI as a transitive dependency of [`flowharness`](https://github.com/flowharness-ai) (the scan CLI) and [`flowharness-ci-runner`](https://github.com/flowharness-ai). Install those packages instead of depending on `flowharness-inspection` directly.
+
+> **Note:** this package currently installs a top-level module named `inspection`. Prefer `uvx` (isolated environments) over `pip install` into a shared venv until the 0.2 module-namespace rename lands.
+
+**License:** Apache-2.0  
+**Homepage:** https://github.com/flowharness-ai

flowharness_inspection-0.1.0/README.md

@@ -0,0 +1,10 @@
+# flowharness-inspection
+
+Inspection context — the static, local, deterministic agent-rules surface scanner. Provides the domain layer for classifying agent-rules surfaces (CLAUDE.md, .cursorrules, AGENTS.md, agent-harness bundles, etc.), reading and parsing them, running architectural drift/contradiction/divergence/risk checks, and scoring findings into a quarantine verdict and drift index.
+
+This is an **internal library package** of the FlowHarness toolchain, published to PyPI as a transitive dependency of [`flowharness`](https://github.com/flowharness-ai) (the scan CLI) and [`flowharness-ci-runner`](https://github.com/flowharness-ai). Install those packages instead of depending on `flowharness-inspection` directly.
+
+> **Note:** this package currently installs a top-level module named `inspection`. Prefer `uvx` (isolated environments) over `pip install` into a shared venv until the 0.2 module-namespace rename lands.
+
+**License:** Apache-2.0  
+**Homepage:** https://github.com/flowharness-ai

flowharness_inspection-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "flowharness-inspection"
+version = "0.1.0"
+readme = "README.md"
+description = "Inspection context — Architectural Drift Index and risk scan (FLOWHARNESS_SPEC.md §6.12)"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "flowharness-core==0.1.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/flowharness-ai"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "inspection"
+
+[tool.uv.sources.flowharness-core]
+workspace = true

flowharness_inspection-0.1.0/pyproject.toml.orig

@@ -0,0 +1,29 @@
+[project]
+name = "flowharness-inspection"
+version = "0.1.0"
+readme = "README.md"
+description = "Inspection context — Architectural Drift Index and risk scan (FLOWHARNESS_SPEC.md §6.12)"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# Internal deps pin ==0.1.0: the six OSS packages version in lockstep (release.yml builds
+# them from one tag), and [tool.uv.sources] workspace=true overrides these locally.
+dependencies = ["flowharness-core==0.1.0", "pyyaml>=6.0"]
+
+[project.urls]
+Homepage = "https://github.com/flowharness-ai"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "inspection"
+
+[tool.uv.sources]
+flowharness-core = { workspace = true }

flowharness_inspection-0.1.0/src/inspection/__init__.py

@@ -0,0 +1,5 @@
+"""Inspection context (FLOWHARNESS_SPEC.md §6.12) — the Phase-0 wedge.
+
+Static, local, deterministic scan over a project's agent-rules surface.
+Zero network, zero model calls on the default path.
+"""

flowharness_inspection-0.1.0/src/inspection/api/__init__.py

@@ -0,0 +1 @@
+"""Inspection api layer — edge schemas and adapters; never imported by domain or application."""

flowharness_inspection-0.1.0/src/inspection/api/exit_codes.py

@@ -0,0 +1,17 @@
+"""Verdict -> process exit code (adapter concern, not domain).
+
+PASS=0, NEEDS_HUMAN=1, FAIL=2 (SPEC §6.12.2). NEEDS_HUMAN is a distinct non-zero
+code so CI can hold differently from a hard FAIL; NEEDS_HUMAN is never auto-approved.
+"""
+
+from core import Verdict
+
+_EXIT_CODES: dict[Verdict, int] = {
+    Verdict.PASS: 0,
+    Verdict.NEEDS_HUMAN: 1,
+    Verdict.FAIL: 2,
+}
+
+
+def exit_code_for(verdict: Verdict) -> int:
+    return _EXIT_CODES[verdict]

flowharness_inspection-0.1.0/src/inspection/application/__init__.py

@@ -0,0 +1 @@
+"""Inspection service layer — the only orchestration point (P&G ch.4)."""

flowharness_inspection-0.1.0/src/inspection/application/services.py

@@ -0,0 +1,98 @@
+"""Inspection service layer — the scan use case (P&G ch.4).
+
+PR 0.5: the report carries the RulesSnapshot, the drift + risk findings, the
+RiskAssessment (verdict from the QuarantineGate), the DriftIndex (scored), and the
+content-addressed report_hash. Report assembly lives in domain/report.py.
+"""
+
+import json
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, cast
+
+from core import Check, Finding
+from inspection.domain.baseline import (
+    BaselineDiff,
+    BaselineRecord,
+    diff_against_baseline,
+    take_baseline,
+)
+from inspection.domain.checks import CheckContext, default_drift_checks, default_risk_checks
+from inspection.domain.checks.quarantine import RiskAssessment
+from inspection.domain.report import build_inspection_report
+from inspection.domain.scoring import DriftIndex, score_drift, scoring_policy_fingerprint
+from inspection.domain.snapshot import RawSurfaceFile, take_snapshot
+
+
+class SurfaceReader(Protocol):
+    """Port: enumerate the raw agent-rules surface of a directory."""
+
+    def read(self, root: Path) -> Iterable[RawSurfaceFile]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ScanResult:
+    report: bytes
+    assessment: RiskAssessment
+    drift_index: DriftIndex
+    findings: tuple[Finding, ...]
+    baseline_record: BaselineRecord  # this scan as a committable baseline (--set-baseline)
+    baseline_diff: BaselineDiff | None  # populated only when a baseline was provided
+
+
+def scan_directory(
+    root: Path,
+    reader: SurfaceReader,
+    context: CheckContext,
+    baseline: BaselineRecord | None = None,
+    checks: Sequence[Check] | None = None,
+) -> ScanResult:
+    """Run the scan and render the canonical report bytes plus the risk verdict and index.
+
+    `checks` injects the check composition via the `core.Check` port (DIP, mirroring
+    the `SurfaceReader` seam); `None` keeps the default drift+risk tuple byte-for-byte.
+
+    Byte-level canonicalisation lives here, once: sorted keys, no whitespace
+    drift, UTF-8, trailing newline, and no timestamps in the body (§6.12.5).
+    """
+    if checks is None:
+        # WHY: each element implements the core.Check port; the cast performs the
+        # heterogeneous-tuple→Sequence widening (mypy infers the concrete per-element
+        # tuple type rather than the common Check supertype).
+        checks = cast("Sequence[Check]", (*default_drift_checks(), *default_risk_checks()))
+    snapshot, reader_findings = take_snapshot(reader.read(root))
+    findings: list[Finding] = list(reader_findings)
+    for check in checks:
+        findings.extend(check.run(snapshot, context))
+    findings.sort(key=lambda f: (f.check_id, f.subject_ref, f.evidence))
+
+    assessment = RiskAssessment.from_findings(findings, context.quarantine_policy)
+    drift_index = score_drift(
+        findings,
+        context.scoring_policy,
+        baseline_ref=context.baseline_ref if baseline is None else "lockfile",
+        snapshot_hash=snapshot.snapshot_hash,
+    )
+    diff = (
+        diff_against_baseline(findings, baseline, drift_index.display)
+        if baseline is not None
+        else None
+    )
+    report = build_inspection_report(
+        snapshot,
+        findings,
+        assessment,
+        drift_index,
+        scoring_policy_fingerprint(context.scoring_policy),
+        baseline_diff=diff,
+    )
+    report_bytes = json.dumps(report, sort_keys=True, ensure_ascii=False).encode() + b"\n"
+    return ScanResult(
+        report=report_bytes,
+        assessment=assessment,
+        drift_index=drift_index,
+        findings=tuple(findings),
+        baseline_record=take_baseline(findings, snapshot.snapshot_hash, drift_index.display),
+        baseline_diff=diff,
+    )

flowharness_inspection-0.1.0/src/inspection/domain/__init__.py

@@ -0,0 +1 @@
+"""Inspection domain layer — frozen VOs and invariants. Imports stdlib + core only."""

flowharness_inspection-0.1.0/src/inspection/domain/agent_config.py

@@ -0,0 +1,157 @@
+"""AgentConfigGraph — normalized VO for orchestration-graph inspection (CI-PR2 §Step 2).
+
+A single normalized shape that CrewAI Python configs, LangGraph YAML/JSON, and future
+harness readers all reduce to. Integer-only limits (bp/micro-units at the display edge)
+so `content_hash()` is stable and CI-PR3's loop/cycle/ceiling checks stay pure. Producers
+(readers, CI-PR2b): the stdlib-`ast` CrewAI reader lives in the domain peer
+`inspection/domain/agent_config_reader.py` (ast is stdlib → domain-legal); the PyYAML
+reader lives in `inspection/infrastructure/agent_config.py` (third-party ⇒ infrastructure).
+
+Design (docs/architecture/flowharness-ci-PR-ROADMAP.md §CI-PR2 Step 2):
+
+- **Node** carries the safety-relevant ceilings CI-PR3 checks: `max_iterations`,
+  `max_rpm`, `max_execution_time_s`, `token_ceiling`, `cost_ceiling_micro`,
+  `allow_delegation`. All optional (a static reader can't always determine them);
+  `None` MEANS "unbounded" for the loop/ceiling checks.
+- **DelegationEdge** connects two node ids; CI-PR3's recursive_delegation_check does
+  DFS over these.
+- **AgentConfigGraph** freezes the whole thing and mixes in `ContentHashable` so
+  identical graphs from two readers produce identical hashes (byte-parity across
+  languages, D8-14).
+
+`node_ids` are stable strings the reader picks (typically the CrewAI class name or the
+LangGraph node id); the graph rejects duplicate ids and dangling edges at construction.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from core import DomainError
+from core.content_hash import ContentHashable
+
+
+@dataclass(frozen=True, slots=True)
+class AgentNode:
+    """One node in the agent orchestration graph. CI-PR3 loop/cycle/ceiling checks read
+    from this. `None` on a limit means UNBOUNDED — the exact signal that triggers
+    HIGH/MEDIUM findings in CI-PR3.
+
+    Fields extended in CI-PR2b (per docs/architecture/ci_governance_spec.md §3.4):
+    `name`, `source_ref`, `line`, `llm_ref`. All defaulted so CI-PR2a tests stay green;
+    CI-PR3's `token_ceiling_check` needs `llm_ref` to discriminate spending vs
+    non-spending nodes and `line` for the SourceAnchor on findings."""
+
+    node_id: str
+    role: str = ""
+    max_iterations: int | None = None
+    max_rpm: int | None = None
+    max_execution_time_s: int | None = None
+    token_ceiling: int | None = None
+    cost_ceiling_micro: int | None = None  # cost in USD x 1_000_000 (integer, float-free)
+    allow_delegation: bool = False
+    # CI-PR2b VO extension (spec §3.4). Defaulted for backwards compat.
+    name: str = ""
+    source_ref: str = ""  # posix relpath of the source file
+    line: int | None = None  # 1-based; parser's lineno for the Agent() call / class def
+    llm_ref: str | None = None  # e.g. "gpt-4o" — presence means the node WILL spend
+
+    def __post_init__(self) -> None:
+        if not self.node_id:
+            raise DomainError("agent_node_id_blank")
+        for attr, value in (
+            ("max_iterations", self.max_iterations),
+            ("max_rpm", self.max_rpm),
+            ("max_execution_time_s", self.max_execution_time_s),
+            ("token_ceiling", self.token_ceiling),
+            ("cost_ceiling_micro", self.cost_ceiling_micro),
+        ):
+            if value is not None and value < 0:
+                raise DomainError(f"agent_node_{attr}_negative")
+        if self.line is not None and self.line <= 0:
+            raise DomainError("agent_node_line_invalid")
+
+
+# CI-PR2b: edge kinds enumerated (spec §3.4). Strings not StrEnum so the VO hash
+# stays JSON-native and cross-language byte-parity survives.
+DELEGATION_EDGE_KINDS: frozenset[str] = frozenset({"delegation", "task_chain", "tool"})
+
+
+@dataclass(frozen=True, slots=True)
+class DelegationEdge:
+    """`source` may delegate to `target`. CI-PR3's recursive_delegation_check walks
+    these to detect cycles. `kind` (spec §3.4) discriminates a delegating hierarchy
+    from task-chain dependencies and tool-use edges."""
+
+    source: str
+    target: str
+    kind: str = "delegation"
+
+    def __post_init__(self) -> None:
+        if not self.source or not self.target:
+            raise DomainError("delegation_edge_endpoints_blank")
+        if self.kind not in DELEGATION_EDGE_KINDS:
+            raise DomainError("delegation_edge_kind_unknown")
+
+
+@dataclass(frozen=True, slots=True)
+class AgentConfigGraph(ContentHashable):
+    """A frozen orchestration graph — the reader's output, CI-PR3's input.
+
+    `nodes` MUST have unique ids; every edge endpoint MUST refer to a known node
+    (otherwise the graph would silently classify unreachable branches as bounded).
+    Producers set `harness_ref` to a stable string identifying the source
+    ("crewai", "langgraph", …) so consumers can route findings back to a spec section."""
+
+    nodes: tuple[AgentNode, ...] = field(default_factory=tuple)
+    edges: tuple[DelegationEdge, ...] = field(default_factory=tuple)
+    harness_ref: str = ""
+
+    def __post_init__(self) -> None:
+        ids: set[str] = set()
+        for n in self.nodes:
+            if n.node_id in ids:
+                raise DomainError("agent_graph_duplicate_node_id")
+            ids.add(n.node_id)
+        for e in self.edges:
+            if e.source not in ids or e.target not in ids:
+                raise DomainError("agent_graph_edge_endpoint_unknown")
+
+    def _hash_payload(self) -> object:
+        # Sort so a producer's node/edge iteration order doesn't leak into the hash;
+        # CI-PR3 needs stable output regardless of reader ordering.
+        # NB: `line` is NOT hashed — it's a rendering-only anchor and is not
+        # cross-Python-version stable (per adversarial review, ast lineno drift).
+        return {
+            "harness_ref": self.harness_ref,
+            "nodes": [
+                {
+                    "node_id": n.node_id,
+                    "role": n.role,
+                    "name": n.name,
+                    "source_ref": n.source_ref,
+                    "llm_ref": n.llm_ref,
+                    "max_iterations": n.max_iterations,
+                    "max_rpm": n.max_rpm,
+                    "max_execution_time_s": n.max_execution_time_s,
+                    "token_ceiling": n.token_ceiling,
+                    "cost_ceiling_micro": n.cost_ceiling_micro,
+                    "allow_delegation": n.allow_delegation,
+                }
+                for n in sorted(self.nodes, key=lambda x: x.node_id)
+            ],
+            "edges": [
+                {"source": e.source, "target": e.target, "kind": e.kind}
+                for e in sorted(self.edges, key=lambda x: (x.source, x.target, x.kind))
+            ],
+        }
+
+    def graph_hash(self) -> str:
+        """Alias for `content_hash()` — spec-named identifier CI-PR3 fixtures use."""
+        return self.content_hash()
+
+    def node(self, node_id: str) -> AgentNode | None:
+        for n in self.nodes:
+            if n.node_id == node_id:
+                return n
+        return None