Close Milestone 4 with adapter adoption evidence

docs/ADAPTER_AUTHORING_GUIDE.md

@@ -8,6 +8,30 @@ Use this guide after the repository assessment in
 [Project Onboarding](PROJECT_ONBOARDING.md). The onboarding checklist decides whether an adapter
 is needed. This guide defines how to build and prove one.
 
+## Public authoring surface
+
+Adapter authors should import typed contracts, validation helpers, graph models, and the
+conformance helper from `docforge.adapter_sdk`:
+
+```python
+from docforge.adapter_sdk import (
+    AdapterAssembly,
+    AdapterImplementation,
+    AdapterManifest,
+    AdapterProject,
+    AdapterProjectSettings,
+    AdapterProjection,
+    AdapterSource,
+    AdapterSourceProjection,
+    LogicProjection,
+    verify_adapter_conformance,
+)
+```
+
+Language-specific modules under `docforge.adapters` are repository reference implementations, not
+the general authoring namespace. Their exact, deliberately narrow behavior is documented in
+[Reference Adapters](REFERENCE_ADAPTERS.md).
+
 ## Required outcome
 
 A production adapter must provide one reproducible public graph from authoritative project
@@ -51,11 +75,39 @@ class MyAdapter:
         manifest: AdapterManifest,
         contributions: tuple[AdapterSourceProjection, ...],
     ) -> AdapterAssembly: ...
+    def load_complete_assembly(self) -> AdapterAssembly: ...
     def load_projection(self) -> AdapterProjection: ...
 ```
 
 `assemble_projection()` is optional only when extraction units already have disjoint ownership.
-`load_projection()` is always required. It is the clean rebuild and equivalence oracle.
+`load_projection()` is always required. It is the clean primary-graph compatibility oracle.
+`load_complete_assembly()` supplies the cache-independent complete graph-plus-Logic oracle. It is
+required when incremental contributions publish Logic; without it, DocForge cannot prove Logic
+parity.
+
+## What the conformance helper proves
+
+Run the public helper against a fresh confined cache root:
+
+```python
+report = verify_adapter_conformance(
+    MyAdapter(project_root),
+    cache_root=project_root / ".docforge" / "cache" / "adapter-conformance",
+)
+```
+
+`verify_adapter_conformance()` proves:
+
+- two repeated complete assemblies are exactly deterministic, including Logic;
+- when `load_complete_assembly()` exists, its primary graph exactly matches
+  `load_projection()`; and
+- when the incremental methods exist, the assembled incremental graph and Logic exactly match the
+  independent complete oracle.
+
+The report records stable identity, counts, and an assembly hash. This helper does not by itself
+prove process confinement, implementation restart behavior, corrupt-cache recovery, warm zero
+parsing, retrieval, or every case in the proof matrix below. Keep those as separate focused and
+integration tests.
 
 ## Step 1: define authority before parsing
 
@@ -324,6 +376,25 @@ The manifest remains a current source snapshot, not a Git-index snapshot. A Git-
 omit a deleted source whether its deletion is unstaged or staged. Staging is never a required
 DocForge synchronization step.
 
+### Current aggregate bounds
+
+DocForge limits one extraction-cache generation to 10,000 source contributions and 64,000,000
+encoded bytes. Malformed, incompatible, missing, oversized, or unsafe cache data is treated as a
+cache miss.
+
+The assembled graph is bounded by the effective project `Limits.max_nodes`. When adapter settings
+do not override limits, DocForge selects at least 10,000 nodes and raises that bound to the
+manifest's `estimated_nodes` when larger. Aggregate assembly ceilings are:
+
+- nodes: `max_nodes`;
+- relationships: `max_nodes * 32`;
+- Logic nodes across all functions: `max_nodes * 32`; and
+- Logic edges across all functions: `max_nodes * 64`.
+
+Adapters should set realistic limits and fail before retaining unbounded frontend evidence. The
+cache and assembly bounds do not replace each adapter's own bounded source, command, parser, or
+per-function limits.
+
 ## Step 9: keep the complete path independent
 
 The full rebuild must not read the incremental extraction cache. Otherwise equivalence compares
@@ -470,7 +541,8 @@ For every such change:
 - [ ] Two independent complete builds match exactly.
 - [ ] Incremental extraction uses authoritative dependencies.
 - [ ] The complete oracle is independent of the cache.
-- [ ] Complete and incremental public projections match exactly.
+- [ ] Complete and incremental public graph and Logic projections match exactly.
+- [ ] `verify_adapter_conformance()` passes, and the separate proof-matrix cases also pass.
 - [ ] Corrupt, missing, and interrupted cache cases fail safely.
 - [ ] Session composition and family isolation are proven.
 - [ ] Viewer, query, context, and Logic retrieval are proven.