Add incremental adapter compiler boundary

src/docforge/models.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from dataclasses import asdict, dataclass
 from pathlib import Path
-from typing import Protocol
+from typing import Protocol, runtime_checkable
 
 
 @dataclass(frozen=True)
@@ -111,6 +111,51 @@ class Edge:
         return asdict(self)
 
 
+@dataclass(frozen=True)
+class LogicNode:
+    """One function-scoped control-flow node kept outside the primary graph."""
+
+    logic_id: str
+    kind: str
+    label: str
+    source_anchor: str | None
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class LogicEdge:
+    """One directed control-flow transition with an explicit branch label."""
+
+    source_id: str
+    relation: str
+    target_id: str
+    label: str | None = None
+    ordinal: int = 0
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class LogicProjection:
+    """A lazy control-flow projection owned by one primary graph symbol."""
+
+    owner_node_id: str
+    source_id: str
+    nodes: tuple[LogicNode, ...]
+    edges: tuple[LogicEdge, ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "owner_node_id": self.owner_node_id,
+            "source_id": self.source_id,
+            "nodes": [node.as_dict() for node in self.nodes],
+            "edges": [edge.as_dict() for edge in self.edges],
+        }
+
+
 @dataclass(frozen=True)
 class ProjectSnapshot:
     descriptor: ProjectDescriptor
@@ -120,6 +165,14 @@ class ProjectSnapshot:
     revision: str
 
 
+@dataclass(frozen=True)
+class ProjectState:
+    """Cheap canonical identity used to prove a derived snapshot is current."""
+
+    source_hash: str
+    revision: str
+
+
 class ProjectService(Protocol):
     """Minimum immutable project boundary required by derived read services."""
 
@@ -137,6 +190,20 @@ class ProjectService(Protocol):
     ) -> None: ...
 
 
+@runtime_checkable
+class BuildReportingProject(ProjectService, Protocol):
+    """Optional project boundary exposing extraction metrics for builds."""
+
+    def build_report(self) -> dict[str, object]: ...
+
+
+@runtime_checkable
+class IncrementalStateProject(ProjectService, Protocol):
+    """Optional project boundary for manifest-only stale-state checks."""
+
+    def incremental_state(self) -> ProjectState | None: ...
+
+
 @dataclass(frozen=True)
 class ContextEntry:
     node_id: str