Search for a node to inspect its neighborhood.
Visualization disconnected
diff --git a/src/docforge/cli.py b/src/docforge/cli.py
index 35b55d2..9e5f507 100644
--- a/src/docforge/cli.py
+++ b/src/docforge/cli.py
@@ -13,9 +13,11 @@ from .client_config import CLIENT_NAMES, generate_client_configuration
from .context import compile_context
from .doctor import run_doctor
from .errors import DocForgeError
+from .graph_rendering import GraphRenderService
from .index import ProjectIndex
from .onboarding import assess_project, scaffold_project
from .project import Project, project_root_fingerprint
+from .projection_policy import compose_projection_policy
from .rendering import RenderService
from .telemetry import request
from .viewer_manager import ViewerManagerClient
@@ -29,6 +31,18 @@ def _parser() -> argparse.ArgumentParser:
action="store_true",
help="Attach bounded request-local stage timings and counters",
)
+ parser.add_argument(
+ "--manual-render-policy",
+ choices=("auto", "explicit", "disabled"),
+ )
+ parser.add_argument(
+ "--portable-graph-policy",
+ choices=("explicit", "disabled"),
+ )
+ parser.add_argument(
+ "--live-viewer-policy",
+ choices=("on-demand", "disabled"),
+ )
commands = parser.add_subparsers(dest="command", required=True)
configure = commands.add_parser("configure")
configure.add_argument("client", choices=CLIENT_NAMES)
@@ -42,6 +56,21 @@ def _parser() -> argparse.ArgumentParser:
configure.add_argument("--proposal-writer")
configure.add_argument("--canonical-applier")
configure.add_argument("--no-ast", action="store_true")
+ configure.add_argument(
+ "--manual-render-policy",
+ choices=("auto", "explicit", "disabled"),
+ default=argparse.SUPPRESS,
+ )
+ configure.add_argument(
+ "--portable-graph-policy",
+ choices=("explicit", "disabled"),
+ default=argparse.SUPPRESS,
+ )
+ configure.add_argument(
+ "--live-viewer-policy",
+ choices=("on-demand", "disabled"),
+ default=argparse.SUPPRESS,
+ )
configure.add_argument("--startup-timeout", type=int, default=30)
configure.add_argument("--tool-timeout", type=int, default=300)
configure.add_argument("--output", type=Path)
@@ -95,6 +124,12 @@ def _parser() -> argparse.ArgumentParser:
render_status = commands.add_parser("render-status")
render_status.add_argument("view_id", nargs="?")
render_status.add_argument("--deep", action="store_true")
+ graph_plan = commands.add_parser("graph-plan")
+ graph_plan.add_argument("view_id")
+ graph_render = commands.add_parser("graph-render")
+ graph_render.add_argument("view_id")
+ graph_render_status = commands.add_parser("graph-render-status")
+ graph_render_status.add_argument("view_id", nargs="?")
preview = commands.add_parser("preview")
preview.add_argument("changeset_id")
preview.add_argument("view_id")
@@ -124,6 +159,9 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
proposal_writer=arguments.proposal_writer,
canonical_applier=arguments.canonical_applier,
no_ast=arguments.no_ast,
+ manual_render_policy=arguments.manual_render_policy,
+ portable_graph_policy=arguments.portable_graph_policy,
+ live_viewer_policy=arguments.live_viewer_policy,
startup_timeout=arguments.startup_timeout,
tool_timeout=arguments.tool_timeout,
output=arguments.output,
@@ -152,12 +190,39 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
content_root=arguments.content_root,
)
project = Project.open(arguments.project_root)
+ projection_policy = compose_projection_policy(
+ manual=arguments.manual_render_policy,
+ portable_graph=arguments.portable_graph_policy,
+ live_viewer=arguments.live_viewer_policy,
+ manual_configured=project.descriptor.render is not None,
+ portable_graph_configured=project.descriptor.graph_render is not None,
+ application_enabled=False,
+ )
build = ProjectIndex(project).build()
- render = RenderService(project).render("manual")
+ render = (
+ {
+ "status": "ok",
+ "state": "skipped",
+ "reason": "projection_policy_disabled",
+ }
+ if projection_policy.manual == "disabled"
+ else RenderService(
+ project,
+ manual_policy=projection_policy.manual,
+ ).render("manual")
+ )
return {**scaffold, "build": build, "render": render}
return assess_project(arguments.project_root, requested_languages=languages)
project = Project.open(arguments.project_root)
index = ProjectIndex(project)
+ projection_policy = compose_projection_policy(
+ manual=arguments.manual_render_policy,
+ portable_graph=arguments.portable_graph_policy,
+ live_viewer=arguments.live_viewer_policy,
+ manual_configured=project.descriptor.render is not None,
+ portable_graph_configured=project.descriptor.graph_render is not None,
+ application_enabled=arguments.command == "apply",
+ )
if arguments.command == "info":
snapshot = project.load()
return {
@@ -250,24 +315,52 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
cursor=arguments.cursor,
)
if arguments.command == "render":
- return RenderService(project).render(arguments.view_id)
+ return RenderService(
+ project,
+ manual_policy=projection_policy.manual,
+ ).render(arguments.view_id)
if arguments.command == "render-status":
- rendering = RenderService(project)
+ rendering = RenderService(
+ project,
+ manual_policy=projection_policy.manual,
+ )
return (
rendering.deep_status(arguments.view_id)
if arguments.deep
else rendering.status(arguments.view_id)
)
+ if arguments.command == "graph-plan":
+ return GraphRenderService(
+ project,
+ portable_graph_policy=projection_policy.portable_graph,
+ ).plan(arguments.view_id)
+ if arguments.command == "graph-render":
+ return GraphRenderService(
+ project,
+ portable_graph_policy=projection_policy.portable_graph,
+ ).render(arguments.view_id)
+ if arguments.command == "graph-render-status":
+ return GraphRenderService(
+ project,
+ portable_graph_policy=projection_policy.portable_graph,
+ ).status(arguments.view_id)
if arguments.command == "preview":
- return RenderService(project).preview(arguments.changeset_id, arguments.view_id)
+ return RenderService(
+ project,
+ manual_policy=projection_policy.manual,
+ ).preview(arguments.changeset_id, arguments.view_id)
if arguments.command == "apply":
return CanonicalApplicationService(
project,
applier_id=arguments.applier,
applier=GenericCanonicalApplier(project),
+ manual_policy=projection_policy.manual,
).apply(arguments.changeset_id, arguments.changeset_hash)
if arguments.command == "visualize":
- visualization = ViewerManagerClient(index).start(
+ visualization = ViewerManagerClient(
+ index,
+ live_viewer_policy=projection_policy.live_viewer,
+ ).start(
node_id=arguments.node,
query=arguments.query,
depth=arguments.depth,
@@ -284,9 +377,15 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
"visualization": visualization,
}
if arguments.command == "visualization-status":
- return ViewerManagerClient(index).status()
+ return ViewerManagerClient(
+ index,
+ live_viewer_policy=projection_policy.live_viewer,
+ ).status()
if arguments.command == "visualization-stop":
- return ViewerManagerClient(index).stop()
+ return ViewerManagerClient(
+ index,
+ live_viewer_policy=projection_policy.live_viewer,
+ ).stop()
raise DocForgeError("invalid_command", "Unknown command")
diff --git a/src/docforge/client_config.py b/src/docforge/client_config.py
index 7b482d5..18c9de6 100644
--- a/src/docforge/client_config.py
+++ b/src/docforge/client_config.py
@@ -18,9 +18,10 @@ from typing import Literal, cast
from .changeset_contract import document_hash
from .errors import DocForgeError
-from .models import ProjectService
+from .models import ProjectDescriptor, ProjectService
from .policy import CapabilityMode, compose_effective_policy
-from .project import project_root_fingerprint, validate_descriptor_binding
+from .project import Project, project_root_fingerprint, validate_descriptor_binding
+from .projection_policy import compose_projection_policy
ClientName = Literal["codex", "claude", "openclaw"]
CLIENT_NAMES: tuple[ClientName, ...] = ("codex", "claude", "openclaw")
@@ -605,11 +606,37 @@ def _atomic_write(
os.close(directory_fd)
-def _validate_configuration_result(result: dict[str, object]) -> None:
+def _validate_configuration_result(
+ result: dict[str, object],
+ *,
+ trusted_descriptor: ProjectDescriptor | None = None,
+) -> None:
artifact = cast(dict[str, object], result["artifact"])
binding = cast(dict[str, object], result["binding"])
policy = cast(dict[str, object], result["effective_policy"])
+ projection_policy = cast(dict[str, object], result["projection_policy"])
+ projection_availability = cast(
+ dict[str, object],
+ result["projection_availability"],
+ )
project = cast(dict[str, object], result["project"])
+ if trusted_descriptor is None:
+ try:
+ bound_descriptor = Project.open(cast(str, project["project_root"])).descriptor
+ except (DocForgeError, KeyError, TypeError) as error:
+ raise AssertionError(
+ "Generated client project binding cannot be independently validated"
+ ) from error
+ else:
+ bound_descriptor = trusted_descriptor
+ if (
+ project["project_id"] != bound_descriptor.project_id
+ or project["project_root"] != str(bound_descriptor.root)
+ or project["project_root_fingerprint"] != project_root_fingerprint(bound_descriptor.root)
+ or project["adapter"] != bound_descriptor.adapter
+ or project["descriptor_hash"] != bound_descriptor.descriptor_hash
+ ):
+ raise AssertionError("Generated client project binding drifted")
content = cast(str, artifact["content"])
if artifact["content_sha256"] != hashlib.sha256(content.encode("utf-8")).hexdigest():
raise AssertionError("Generated client content hash drifted")
@@ -644,6 +671,29 @@ def _validate_configuration_result(result: dict[str, object]) -> None:
if remaining[-1:] != ["--no-ast"] or arguments.count("--no-ast") != 1:
raise AssertionError("Generated no-AST argument layout drifted")
remaining = remaining[:-1]
+ projection_arguments: dict[str, str] = {}
+ authority_arguments: list[str] = []
+ position = 0
+ projection_options = {
+ "--manual-render-policy": "manual",
+ "--portable-graph-policy": "portable_graph",
+ "--live-viewer-policy": "live_viewer",
+ }
+ while position < len(remaining):
+ option = remaining[position]
+ field = projection_options.get(option)
+ if field is None:
+ authority_arguments.append(option)
+ position += 1
+ continue
+ if position + 1 >= len(remaining) or option in projection_arguments:
+ raise AssertionError("Generated projection policy argument layout drifted")
+ value = remaining[position + 1]
+ projection_arguments[option] = value
+ if projection_policy[field] != value:
+ raise AssertionError("Generated projection policy argument drifted")
+ position += 2
+ remaining = authority_arguments
mode = binding["capability_mode"]
if (
(mode == "read" and remaining)
@@ -663,6 +713,34 @@ def _validate_configuration_result(result: dict[str, object]) -> None:
)
):
raise AssertionError("Generated authority argument layout drifted")
+ expected_projection_policy = compose_projection_policy(
+ manual=projection_arguments.get("--manual-render-policy"),
+ portable_graph=projection_arguments.get("--portable-graph-policy"),
+ live_viewer=projection_arguments.get("--live-viewer-policy"),
+ manual_configured=cast(bool, projection_availability["manual_configured"]),
+ portable_graph_configured=cast(
+ bool,
+ projection_availability["portable_graph_configured"],
+ ),
+ application_enabled=cast(
+ bool,
+ projection_availability["application_enabled"],
+ ),
+ live_viewer_available=cast(
+ bool,
+ projection_availability["live_viewer_available"],
+ ),
+ )
+ if (
+ projection_policy != expected_projection_policy.as_dict()
+ or projection_availability["manual_configured"] != (render_policy["manual"] != "disabled")
+ or projection_availability["manual_configured"] != (bound_descriptor.render is not None)
+ or projection_availability["portable_graph_configured"]
+ != (bound_descriptor.graph_render is not None)
+ or projection_availability["application_enabled"] != (mode == "application")
+ or projection_availability["live_viewer_available"] is not True
+ ):
+ raise AssertionError("Generated projection policy drifted from its availability")
composed_policy = compose_effective_policy(
selected_mode=cast(CapabilityMode, mode),
capability_source="explicit",
@@ -698,6 +776,18 @@ def _validate_configuration_result(result: dict[str, object]) -> None:
)
):
raise AssertionError("Generated client policy drifted from its binding")
+ if (
+ result["projection_policy_hash"]
+ != hashlib.sha256(
+ json.dumps(
+ projection_policy,
+ sort_keys=True,
+ separators=(",", ":"),
+ ensure_ascii=False,
+ ).encode("utf-8")
+ ).hexdigest()
+ ):
+ raise AssertionError("Generated projection policy hash drifted")
expected_hash = document_hash(
{
"schema_version": 1,
@@ -706,6 +796,9 @@ def _validate_configuration_result(result: dict[str, object]) -> None:
"project": project,
"binding": binding,
"effective_policy": policy,
+ "projection_policy": projection_policy,
+ "projection_policy_hash": result["projection_policy_hash"],
+ "projection_availability": projection_availability,
"artifact_format": artifact["format"],
"artifact_content_sha256": artifact["content_sha256"],
}
@@ -723,6 +816,9 @@ def generate_client_configuration(
proposal_writer: str | None = None,
canonical_applier: str | None = None,
no_ast: bool = False,
+ manual_render_policy: str | None = None,
+ portable_graph_policy: str | None = None,
+ live_viewer_policy: str | None = None,
startup_timeout: int = 30,
tool_timeout: int = 300,
output: Path | None = None,
@@ -839,9 +935,6 @@ def generate_client_configuration(
arguments.extend(("--proposal-writer", proposal_writer))
if canonical_applier is not None:
arguments.extend(("--canonical-applier", canonical_applier))
- if no_ast:
- arguments.append("--no-ast")
-
policy = compose_effective_policy(
selected_mode=selected_mode,
capability_source="explicit",
@@ -850,6 +943,40 @@ def generate_client_configuration(
render_configured=descriptor.render is not None,
application_enabled=canonical_applier is not None,
)
+ projection_policy = compose_projection_policy(
+ manual=manual_render_policy,
+ portable_graph=portable_graph_policy,
+ live_viewer=live_viewer_policy,
+ manual_configured=descriptor.render is not None,
+ portable_graph_configured=descriptor.graph_render is not None,
+ application_enabled=canonical_applier is not None,
+ )
+ default_projection_policy = compose_projection_policy(
+ manual_configured=descriptor.render is not None,
+ portable_graph_configured=descriptor.graph_render is not None,
+ application_enabled=canonical_applier is not None,
+ )
+ for option, selected, default in (
+ (
+ "--manual-render-policy",
+ projection_policy.manual,
+ default_projection_policy.manual,
+ ),
+ (
+ "--portable-graph-policy",
+ projection_policy.portable_graph,
+ default_projection_policy.portable_graph,
+ ),
+ (
+ "--live-viewer-policy",
+ projection_policy.live_viewer,
+ default_projection_policy.live_viewer,
+ ),
+ ):
+ if selected != default:
+ arguments.extend((option, selected))
+ if no_ast:
+ arguments.append("--no-ast")
artifact_format, content, warning = _artifact(
selected_client,
server_name=selected_name,
@@ -902,6 +1029,7 @@ def generate_client_configuration(
"project_root": str(descriptor.root),
"project_root_fingerprint": fingerprint,
"adapter": descriptor.adapter,
+ "descriptor_hash": descriptor.descriptor_hash,
}
policy_payload = policy.as_dict()
plan_hash = document_hash(
@@ -912,6 +1040,14 @@ def generate_client_configuration(
"project": project_binding,
"binding": binding,
"effective_policy": policy_payload,
+ "projection_policy": projection_policy.as_dict(),
+ "projection_policy_hash": projection_policy.policy_hash,
+ "projection_availability": {
+ "manual_configured": descriptor.render is not None,
+ "portable_graph_configured": descriptor.graph_render is not None,
+ "application_enabled": canonical_applier is not None,
+ "live_viewer_available": True,
+ },
"artifact_format": artifact_format,
"artifact_content_sha256": artifact["content_sha256"],
}
@@ -926,6 +1062,14 @@ def generate_client_configuration(
"project": project_binding,
"binding": binding,
"effective_policy": policy_payload,
+ "projection_policy": projection_policy.as_dict(),
+ "projection_policy_hash": projection_policy.policy_hash,
+ "projection_availability": {
+ "manual_configured": descriptor.render is not None,
+ "portable_graph_configured": descriptor.graph_render is not None,
+ "application_enabled": canonical_applier is not None,
+ "live_viewer_available": True,
+ },
"artifact": artifact,
"configuration_hash": plan_hash,
"warnings": [
@@ -933,5 +1077,5 @@ def generate_client_configuration(
*([] if publication_warning is None else [{"code": publication_warning}]),
],
}
- _validate_configuration_result(result)
+ _validate_configuration_result(result, trusted_descriptor=descriptor)
return result
diff --git a/src/docforge/doctor.py b/src/docforge/doctor.py
index e79ed61..89fd345 100644
--- a/src/docforge/doctor.py
+++ b/src/docforge/doctor.py
@@ -20,6 +20,7 @@ from .project import (
project_root_fingerprint,
validate_descriptor_binding,
)
+from .projection_policy import compose_projection_policy
MAX_CLIENT_CONFIG_BYTES = 1_000_000
MAX_CLIENT_SERVERS = 256
@@ -614,6 +615,9 @@ def _parse_binding(arguments: list[str]) -> dict[str, object]:
"--proposal-writer",
"--canonical-applier",
"--capability-mode",
+ "--manual-render-policy",
+ "--portable-graph-policy",
+ "--live-viewer-policy",
}
flag_options = {"--no-ast", "--diagnostics"}
position = 0
@@ -662,6 +666,9 @@ def _parse_binding(arguments: list[str]) -> dict[str, object]:
"capability_mode_implicit": implicit,
"no_ast": "--no-ast" in flags,
"diagnostics": "--diagnostics" in flags,
+ "manual_render_policy": values.get("--manual-render-policy"),
+ "portable_graph_policy": values.get("--portable-graph-policy"),
+ "live_viewer_policy": values.get("--live-viewer-policy"),
}
@@ -749,6 +756,16 @@ def _runtime_policy_check(
canonical_applier is not None and selected_mode in {"application", "operator"}
),
)
+ compose_projection_policy(
+ manual=cast(str | None, binding["manual_render_policy"]),
+ portable_graph=cast(str | None, binding["portable_graph_policy"]),
+ live_viewer=cast(str | None, binding["live_viewer_policy"]),
+ manual_configured=project.descriptor.render is not None,
+ portable_graph_configured=project.descriptor.graph_render is not None,
+ application_enabled=(
+ canonical_applier is not None and selected_mode in {"application", "operator"}
+ ),
+ )
if cast(bool, binding["capability_mode_implicit"]):
return (
"warning",
diff --git a/src/docforge/graph_projection.py b/src/docforge/graph_projection.py
new file mode 100644
index 0000000..d716389
--- /dev/null
+++ b/src/docforge/graph_projection.py
@@ -0,0 +1,525 @@
+"""Pure, bounded portable-graph planning over one immutable graph generation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from .errors import DocForgeError
+from .models import Edge, Node, ProjectSnapshot
+from .project import project_root_fingerprint
+from .projection_contract import (
+ MAX_GRAPH_VIEW_DEPTH,
+ MAX_GRAPH_VIEW_EDGES,
+ MAX_GRAPH_VIEW_FILTERS,
+ MAX_GRAPH_VIEW_NODES,
+ MAX_GRAPH_VIEW_QUERY_CHARS,
+ MAX_GRAPH_VIEW_STRING_CHARS,
+ MAX_GRAPH_VIEW_WORK,
+ GraphViewPlanV1,
+ ProjectionPackageV1,
+)
+
+GraphViewMode = Literal["nodes", "flow", "web", "logic"]
+
+_QUERY_TOKEN = re.compile(r"\w+", re.UNICODE)
+_DETAIL_FIELDS = (
+ "node_id",
+ "title",
+ "family",
+ "authority",
+ "status",
+ "tags",
+ "summary",
+ "content_hash",
+)
+
+
+@dataclass(frozen=True)
+class GraphViewRequestV1:
+ """One closed, inert graph selection request."""
+
+ view_id: str
+ title: str
+ root_node_id: str | None = None
+ query: str | None = None
+ initial_mode: GraphViewMode = "nodes"
+ depth: int = 1
+ max_nodes: int = 100
+ max_edges: int = 400
+ max_work: int = 100_000
+ families: tuple[str, ...] = ()
+ relations: tuple[str, ...] = ()
+ authorities: tuple[str, ...] = ()
+ statuses: tuple[str, ...] = ()
+ tags: tuple[str, ...] = ()
+ include_logic: bool = False
+
+
+@dataclass(frozen=True)
+class _ValidatedRequest:
+ view_id: str
+ title: str
+ root_node_id: str | None
+ query: str | None
+ initial_mode: GraphViewMode
+ depth: int
+ max_nodes: int
+ max_edges: int
+ max_work: int
+ families: tuple[str, ...]
+ relations: tuple[str, ...]
+ authorities: tuple[str, ...]
+ statuses: tuple[str, ...]
+ tags: tuple[str, ...]
+ include_logic: bool
+
+
+def _invalid(message: str, **details: object) -> DocForgeError:
+ return DocForgeError("invalid_graph_view_request", message, **details)
+
+
+def _string(value: object, *, field: str, maximum: int = MAX_GRAPH_VIEW_STRING_CHARS) -> str:
+ if not isinstance(value, str) or not value.strip() or len(value) > maximum or "\0" in value:
+ raise _invalid("Graph view request string is invalid", field=field)
+ return value.strip()
+
+
+def _filter_values(values: object, *, field: str) -> tuple[str, ...]:
+ if not isinstance(values, tuple):
+ raise _invalid("Graph view filter is invalid", field=field)
+ tuple_values = cast(tuple[object, ...], values)
+ if not all(isinstance(value, str) for value in tuple_values):
+ raise _invalid("Graph view filter is invalid", field=field)
+ if len(tuple_values) > MAX_GRAPH_VIEW_FILTERS:
+ raise _invalid("Graph view filter is invalid", field=field)
+ normalized = tuple(_string(value, field=field) for value in cast(tuple[str, ...], tuple_values))
+ if len(normalized) != len(set(normalized)):
+ raise _invalid("Graph view filter contains duplicates", field=field)
+ return tuple(sorted(normalized))
+
+
+def _validated_request(request: GraphViewRequestV1) -> _ValidatedRequest:
+ view_id = _string(request.view_id, field="view_id")
+ title = _string(request.title, field="title")
+ if (request.root_node_id is None) == (request.query is None):
+ raise _invalid("Choose exactly one exact root or lexical query")
+ root_node_id = (
+ None
+ if request.root_node_id is None
+ else _string(request.root_node_id, field="root_node_id")
+ )
+ query = (
+ None
+ if request.query is None
+ else _string(
+ request.query,
+ field="query",
+ maximum=MAX_GRAPH_VIEW_QUERY_CHARS,
+ )
+ )
+ if request.initial_mode not in {"nodes", "flow", "web", "logic"}:
+ raise _invalid("Graph view initial mode is unsupported")
+ if type(request.depth) is not int or not 1 <= request.depth <= MAX_GRAPH_VIEW_DEPTH:
+ raise _invalid(
+ "Graph view depth is outside the fixed boundary",
+ maximum=MAX_GRAPH_VIEW_DEPTH,
+ )
+ for field, value, minimum, maximum in (
+ ("max_nodes", request.max_nodes, 1, MAX_GRAPH_VIEW_NODES),
+ ("max_edges", request.max_edges, 0, MAX_GRAPH_VIEW_EDGES),
+ ("max_work", request.max_work, 1, MAX_GRAPH_VIEW_WORK),
+ ):
+ if type(value) is not int or not minimum <= value <= maximum:
+ raise _invalid(
+ "Graph view bound is outside the fixed boundary",
+ field=field,
+ minimum=minimum,
+ maximum=maximum,
+ )
+ if type(request.include_logic) is not bool:
+ raise _invalid("Graph view Logic selection must be Boolean")
+ return _ValidatedRequest(
+ view_id=view_id,
+ title=title,
+ root_node_id=root_node_id,
+ query=query,
+ initial_mode=request.initial_mode,
+ depth=request.depth,
+ max_nodes=request.max_nodes,
+ max_edges=request.max_edges,
+ max_work=request.max_work,
+ families=_filter_values(request.families, field="families"),
+ relations=_filter_values(request.relations, field="relations"),
+ authorities=_filter_values(request.authorities, field="authorities"),
+ statuses=_filter_values(request.statuses, field="statuses"),
+ tags=_filter_values(request.tags, field="tags"),
+ include_logic=request.include_logic,
+ )
+
+
+def _validated_graph(
+ snapshot: ProjectSnapshot,
+) -> tuple[tuple[Node, ...], tuple[Edge, ...], dict[str, Node]]:
+ nodes = tuple(sorted(snapshot.nodes, key=lambda node: node.node_id))
+ node_by_id = {node.node_id: node for node in nodes}
+ if len(node_by_id) != len(nodes):
+ raise DocForgeError(
+ "invalid_projection",
+ "Graph view snapshot contains duplicate node identities",
+ )
+ edges = tuple(
+ sorted(
+ snapshot.edges,
+ key=lambda edge: (edge.source_id, edge.relation, edge.target_id),
+ )
+ )
+ edge_keys = {(edge.source_id, edge.relation, edge.target_id) for edge in edges}
+ if len(edge_keys) != len(edges) or any(
+ edge.source_id not in node_by_id or edge.target_id not in node_by_id for edge in edges
+ ):
+ raise DocForgeError(
+ "invalid_projection",
+ "Graph view snapshot contains invalid relationships",
+ )
+ return nodes, edges, node_by_id
+
+
+def _eligible(node: Node, request: _ValidatedRequest) -> bool:
+ return (
+ (not request.families or node.family in request.families)
+ and (not request.authorities or node.authority in request.authorities)
+ and (not request.statuses or node.status in request.statuses)
+ and (not request.tags or set(request.tags).issubset(node.tags))
+ )
+
+
+def _relation_allowed(edge: Edge, request: _ValidatedRequest) -> bool:
+ return not request.relations or edge.relation in request.relations
+
+
+def _lexical_text(node: Node) -> str:
+ return " ".join(
+ (
+ node.node_id,
+ node.title,
+ node.summary,
+ node.family,
+ node.authority,
+ node.status,
+ *node.tags,
+ )
+ ).casefold()
+
+
+def _lexical_nodes(
+ nodes: tuple[Node, ...],
+ request: _ValidatedRequest,
+ omissions: list[dict[str, object]],
+) -> tuple[set[str], int, bool]:
+ query = request.query
+ maximum_nodes = request.max_nodes
+ maximum_work = request.max_work
+ assert query is not None
+ terms = tuple(dict.fromkeys(_QUERY_TOKEN.findall(query.casefold())))
+ if not terms:
+ raise _invalid("Lexical graph scope contains no searchable text")
+ selected: set[str] = set()
+ work = 0
+ work_limited = False
+ for node in nodes:
+ if work >= maximum_work:
+ work_limited = True
+ break
+ work += 1
+ if not _eligible(node, request) or not all(term in _lexical_text(node) for term in terms):
+ continue
+ if len(selected) >= maximum_nodes:
+ omissions.append(
+ {
+ "code": "node_result_limit",
+ "subject": "nodes",
+ "limit": maximum_nodes,
+ "minimum_omitted": 1,
+ }
+ )
+ break
+ selected.add(node.node_id)
+ return selected, work, work_limited
+
+
+def _root_nodes(
+ edges: tuple[Edge, ...],
+ node_by_id: dict[str, Node],
+ request: _ValidatedRequest,
+ omissions: list[dict[str, object]],
+) -> tuple[set[str], int, bool]:
+ root_node_id = request.root_node_id
+ maximum_nodes = request.max_nodes
+ maximum_work = request.max_work
+ depth = request.depth
+ assert root_node_id is not None
+ root = node_by_id.get(root_node_id)
+ if root is None:
+ raise DocForgeError(
+ "missing_node",
+ "No node has the requested stable ID",
+ node_id=root_node_id,
+ )
+ if not _eligible(root, request):
+ raise _invalid("Exact graph root is excluded by the closed node filters")
+
+ selected = {root_node_id}
+ frontier = {root_node_id}
+ work = 0
+ work_limited = False
+ node_limited = False
+ for _ in range(depth):
+ if not frontier:
+ break
+ next_frontier: set[str] = set()
+ for edge in edges:
+ if work >= maximum_work:
+ work_limited = True
+ break
+ work += 1
+ if not _relation_allowed(edge, request):
+ continue
+ candidate: str | None = None
+ if edge.source_id in frontier:
+ candidate = edge.target_id
+ elif edge.target_id in frontier:
+ candidate = edge.source_id
+ if candidate is None or candidate in selected:
+ continue
+ node = node_by_id[candidate]
+ if not _eligible(node, request):
+ continue
+ if len(selected) >= maximum_nodes:
+ node_limited = True
+ continue
+ selected.add(candidate)
+ next_frontier.add(candidate)
+ if work_limited:
+ break
+ frontier = next_frontier
+ if node_limited:
+ omissions.append(
+ {
+ "code": "node_result_limit",
+ "subject": "nodes",
+ "limit": maximum_nodes,
+ "minimum_omitted": 1,
+ }
+ )
+ return selected, work, work_limited
+
+
+def _selected_edges(
+ edges: tuple[Edge, ...],
+ selected_ids: set[str],
+ request: _ValidatedRequest,
+ *,
+ initial_work: int,
+ omissions: list[dict[str, object]],
+) -> tuple[list[Edge], int, bool]:
+ maximum_edges = request.max_edges
+ maximum_work = request.max_work
+ selected: list[Edge] = []
+ work = initial_work
+ work_limited = False
+ edge_limited = False
+ for edge in edges:
+ if work >= maximum_work:
+ work_limited = True
+ break
+ work += 1
+ if (
+ edge.source_id not in selected_ids
+ or edge.target_id not in selected_ids
+ or not _relation_allowed(edge, request)
+ ):
+ continue
+ if len(selected) >= maximum_edges:
+ edge_limited = True
+ break
+ selected.append(edge)
+ if edge_limited:
+ omissions.append(
+ {
+ "code": "edge_result_limit",
+ "subject": "edges",
+ "limit": maximum_edges,
+ "minimum_omitted": 1,
+ }
+ )
+ return selected, work, work_limited
+
+
+def _node_payload(node: Node) -> dict[str, object]:
+ return {
+ "node_id": node.node_id,
+ "title": node.title,
+ "family": node.family,
+ "authority": node.authority,
+ "status": node.status,
+ "tags": sorted(node.tags),
+ "summary": node.summary,
+ "content_hash": node.content_hash,
+ }
+
+
+def _edge_payload(edge: Edge) -> dict[str, str]:
+ return {
+ "source_id": edge.source_id,
+ "relation": edge.relation,
+ "target_id": edge.target_id,
+ }
+
+
+def build_graph_view_plan(
+ snapshot: ProjectSnapshot,
+ request: GraphViewRequestV1,
+ allow_logic: bool,
+) -> GraphViewPlanV1:
+ """Build one deterministic, path-free graph plan without rendering or storage access."""
+
+ if type(allow_logic) is not bool:
+ raise _invalid("Graph view Logic policy must be Boolean")
+ normalized = _validated_request(request)
+ nodes, edges, node_by_id = _validated_graph(snapshot)
+ omissions: list[dict[str, object]] = []
+ if normalized.root_node_id is not None:
+ selected_ids, work, work_limited = _root_nodes(
+ edges,
+ node_by_id,
+ normalized,
+ omissions,
+ )
+ scope: dict[str, object] = {
+ "kind": "exact_root",
+ "root_node_id": normalized.root_node_id,
+ "depth": normalized.depth,
+ }
+ else:
+ selected_ids, work, work_limited = _lexical_nodes(
+ nodes,
+ normalized,
+ omissions,
+ )
+ scope = {
+ "kind": "lexical",
+ "query": normalized.query,
+ }
+ selected_edges, work, edge_work_limited = _selected_edges(
+ edges,
+ selected_ids,
+ normalized,
+ initial_work=work,
+ omissions=omissions,
+ )
+ work_limited = work_limited or edge_work_limited
+ if work_limited:
+ omissions.append(
+ {
+ "code": "work_limit",
+ "subject": "selection",
+ "limit": normalized.max_work,
+ "examined": work,
+ "minimum_omitted": 1,
+ }
+ )
+ logic_requested = normalized.include_logic
+ if logic_requested and not allow_logic:
+ omissions.append(
+ {
+ "code": "logic_forbidden",
+ "subject": "logic",
+ "minimum_omitted": 1,
+ }
+ )
+ omissions.sort(key=lambda item: (str(item["code"]), str(item["subject"])))
+ selected_nodes = [node_by_id[node_id] for node_id in sorted(selected_ids)]
+ filters: dict[str, list[str]] = {
+ "families": list(normalized.families),
+ "relations": list(normalized.relations),
+ "authorities": list(normalized.authorities),
+ "statuses": list(normalized.statuses),
+ "tags": list(normalized.tags),
+ }
+ return GraphViewPlanV1.create(
+ {
+ "project": {
+ "project_id": snapshot.descriptor.project_id,
+ "project_root_fingerprint": project_root_fingerprint(snapshot.descriptor.root),
+ "adapter": snapshot.descriptor.adapter,
+ "revision": snapshot.revision,
+ "source_hash": snapshot.source_hash,
+ },
+ "view": {
+ "view_id": normalized.view_id,
+ "title": normalized.title,
+ "initial_mode": normalized.initial_mode,
+ "scope": scope,
+ "filters": filters,
+ "detail_fields": list(_DETAIL_FIELDS),
+ },
+ "bounds": {
+ "depth": normalized.depth,
+ "max_nodes": normalized.max_nodes,
+ "max_edges": normalized.max_edges,
+ "max_work": normalized.max_work,
+ },
+ "policy": {
+ "visibility": "selected_graph_only",
+ "source_paths": "excluded",
+ "source_bodies": "excluded",
+ "database_queries": "forbidden",
+ "executable_content": "forbidden",
+ "logic": "allowed" if allow_logic else "forbidden",
+ "logic_requested": logic_requested,
+ },
+ "graph": {
+ "root_node_id": normalized.root_node_id,
+ "nodes": [_node_payload(node) for node in selected_nodes],
+ "edges": [_edge_payload(edge) for edge in selected_edges],
+ "logic_projections": [],
+ },
+ "omissions": omissions,
+ "diagnostics": {
+ "selection": scope["kind"],
+ "returned_nodes": len(selected_nodes),
+ "returned_edges": len(selected_edges),
+ "examined_work_units": work,
+ "truncated": bool(omissions),
+ "ordering": "node_id;source_id,relation,target_id",
+ },
+ }
+ )
+
+
+def build_graph_projection_package(
+ plan: GraphViewPlanV1,
+ *,
+ renderer_id: str,
+ renderer_version: str,
+ max_output_bytes: int,
+) -> ProjectionPackageV1:
+ """Bind a graph plan to the fixed portable renderer without adding runtime authority."""
+
+ return ProjectionPackageV1.create(
+ kind="graph",
+ plan=plan,
+ renderer={"renderer_id": renderer_id, "renderer_version": renderer_version},
+ components=[
+ {"component_id": "graph.portable-document@1"},
+ {"component_id": "graph.accessible-list@1"},
+ {"component_id": "graph.relationship-table@1"},
+ ],
+ assets=[],
+ output_policy={
+ "artifact_ids": ["portable-graph.html"],
+ "max_total_bytes": max_output_bytes,
+ },
+ )
diff --git a/src/docforge/graph_render_config.py b/src/docforge/graph_render_config.py
new file mode 100644
index 0000000..dfd3ade
--- /dev/null
+++ b/src/docforge/graph_render_config.py
@@ -0,0 +1,285 @@
+"""Strict parsing and confinement for optional portable graph artifacts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, cast
+
+from .config_validation import (
+ ID_PATTERN,
+ confined_path,
+ positive_int,
+ require_string,
+ string_list,
+)
+from .errors import DocForgeError
+from .models import GraphRenderConfig, GraphRenderView, Limits, RenderConfig
+from .projection_contract import (
+ MAX_GRAPH_VIEW_DEPTH,
+ MAX_GRAPH_VIEW_EDGES,
+ MAX_GRAPH_VIEW_FILTERS,
+ MAX_GRAPH_VIEW_NODES,
+ MAX_GRAPH_VIEW_QUERY_CHARS,
+ MAX_GRAPH_VIEW_STRING_CHARS,
+ MAX_GRAPH_VIEW_WORK,
+)
+
+_CONFIG_KEYS = frozenset({"output_root", "views"})
+_VIEW_KEYS = frozenset(
+ {
+ "id",
+ "renderer",
+ "output",
+ "title",
+ "root",
+ "query",
+ "initial_mode",
+ "depth",
+ "max_nodes",
+ "max_edges",
+ "max_work",
+ "families",
+ "relations",
+ "authorities",
+ "statuses",
+ "tags",
+ "include_logic",
+ }
+)
+_MODES = frozenset({"nodes", "flow", "web"})
+
+
+def _overlaps(first: Path, second: Path) -> bool:
+ return first == second or first.is_relative_to(second) or second.is_relative_to(first)
+
+
+def _optional_string(document: dict[str, object], key: str, source: Path) -> str | None:
+ if key not in document:
+ return None
+ return require_string(document, key, source)
+
+
+def _bounded_string(
+ document: dict[str, object],
+ key: str,
+ source: Path,
+ *,
+ maximum: int,
+) -> str:
+ value = require_string(document, key, source)
+ if len(value) > maximum:
+ raise DocForgeError("invalid_config", f"{key} exceeds its fixed character limit")
+ return value
+
+
+def _bounded_strings(
+ value: object,
+ *,
+ key: str,
+ source: Path,
+) -> tuple[str, ...]:
+ values = string_list(value, key=key, source=source)
+ if len(values) > MAX_GRAPH_VIEW_FILTERS or any(
+ len(item) > MAX_GRAPH_VIEW_STRING_CHARS for item in values
+ ):
+ raise DocForgeError("invalid_config", f"{key} exceeds its fixed bounds")
+ return values
+
+
+def load_graph_render_config(
+ root: Path,
+ document: object,
+ *,
+ descriptor_path: Path,
+ content_roots: tuple[Path, ...],
+ authority_files: tuple[Path, ...],
+ cache_root: Path,
+ index_path: Path,
+ changeset_root: Path,
+ manual_render: RenderConfig | None,
+ limits: Limits,
+) -> GraphRenderConfig | None:
+ if document is None:
+ return None
+ if not isinstance(document, dict):
+ raise DocForgeError("invalid_config", "graph_render must be a table")
+ document = cast(dict[str, object], document)
+ unknown = sorted(set(document) - _CONFIG_KEYS)
+ if unknown:
+ raise DocForgeError("invalid_config", "graph_render has unknown fields", fields=unknown)
+ output_root = confined_path(
+ root,
+ document.get("output_root"),
+ field="graph_render.output_root",
+ must_exist=False,
+ )
+ protected = [*content_roots, cache_root, changeset_root]
+ if manual_render is not None:
+ protected.extend((manual_render.template_root, manual_render.preview_root))
+ protected.extend(view.output_path for view in manual_render.views)
+ if any(_overlaps(output_root, path) for path in protected):
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph output must not overlap canonical or other derived roots",
+ )
+ protected_files = (descriptor_path, index_path, *authority_files)
+ if any(path == output_root or path.is_relative_to(output_root) for path in protected_files):
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph output overlaps a protected project path",
+ )
+ view_values_value = document.get("views")
+ if not isinstance(view_values_value, list) or not view_values_value:
+ raise DocForgeError(
+ "invalid_config",
+ "graph_render.views must contain at least one view",
+ )
+ view_values = cast(list[object], view_values_value)
+ if len(view_values) > limits.max_render_views:
+ raise DocForgeError("invalid_config", "graph_render.views exceeds the configured limit")
+ views: list[GraphRenderView] = []
+ view_ids: set[str] = set()
+ outputs: set[Path] = set()
+ for value in view_values:
+ if not isinstance(value, dict):
+ raise DocForgeError("invalid_config", "Each portable graph view must be a table")
+ view = cast(dict[str, object], value)
+ unknown_view = sorted(set(view) - _VIEW_KEYS)
+ if unknown_view:
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph view has unknown fields",
+ fields=unknown_view,
+ )
+ view_id = require_string(view, "id", descriptor_path)
+ if ID_PATTERN.fullmatch(view_id) is None or view_id in view_ids:
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph view ID is invalid or duplicated",
+ id=view_id,
+ )
+ view_ids.add(view_id)
+ renderer = require_string(view, "renderer", descriptor_path)
+ if renderer != "portable_graph_html":
+ raise DocForgeError(
+ "unsupported_renderer",
+ "Portable graph view names an unsupported built-in renderer",
+ renderer=renderer,
+ )
+ output = confined_path(
+ output_root,
+ view.get("output"),
+ field="graph_render.view.output",
+ must_exist=False,
+ )
+ if output.suffix != ".html" or output in outputs:
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph outputs must be unique HTML files",
+ )
+ outputs.add(output)
+ root_node_id = _optional_string(view, "root", descriptor_path)
+ query = _optional_string(view, "query", descriptor_path)
+ if (root_node_id is None) == (query is None):
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph view requires exactly one root or query",
+ )
+ if root_node_id is not None and len(root_node_id) > MAX_GRAPH_VIEW_STRING_CHARS:
+ raise DocForgeError("invalid_config", "Portable graph root exceeds its fixed limit")
+ if query is not None and len(query) > MAX_GRAPH_VIEW_QUERY_CHARS:
+ raise DocForgeError("invalid_config", "Portable graph query exceeds its fixed limit")
+ initial_mode_value = view.get("initial_mode", "nodes")
+ if not isinstance(initial_mode_value, str):
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph initial mode is unsupported",
+ )
+ initial_mode = cast(
+ Literal["nodes", "flow", "web", "logic"],
+ initial_mode_value,
+ )
+ if initial_mode not in _MODES:
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph initial mode is unsupported",
+ )
+ depth = positive_int(view.get("depth", 1), "graph_render.view.depth")
+ max_nodes = positive_int(view.get("max_nodes", 100), "graph_render.view.max_nodes")
+ max_edges = positive_int(
+ view.get("max_edges", 400),
+ "graph_render.view.max_edges",
+ allow_zero=True,
+ )
+ max_work = positive_int(view.get("max_work", 100_000), "graph_render.view.max_work")
+ if (
+ depth > min(limits.max_traversal_depth, MAX_GRAPH_VIEW_DEPTH)
+ or max_nodes > min(limits.max_nodes, MAX_GRAPH_VIEW_NODES)
+ or max_edges > MAX_GRAPH_VIEW_EDGES
+ or max_work > MAX_GRAPH_VIEW_WORK
+ ):
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph view exceeds project or fixed safety limits",
+ )
+ include_logic = view.get("include_logic", False)
+ if type(include_logic) is not bool:
+ raise DocForgeError(
+ "invalid_config",
+ "Portable graph include_logic must be Boolean",
+ )
+ if include_logic:
+ raise DocForgeError(
+ "unsupported_renderer",
+ "Portable graph renderer version 1 does not support Logic projections",
+ )
+ views.append(
+ GraphRenderView(
+ view_id=view_id,
+ renderer=renderer,
+ output_path=output,
+ title=_bounded_string(
+ view,
+ "title",
+ descriptor_path,
+ maximum=MAX_GRAPH_VIEW_STRING_CHARS,
+ ),
+ root_node_id=root_node_id,
+ query=query,
+ initial_mode=initial_mode,
+ depth=depth,
+ max_nodes=max_nodes,
+ max_edges=max_edges,
+ max_work=max_work,
+ families=_bounded_strings(
+ view.get("families", []),
+ key="graph_render.view.families",
+ source=descriptor_path,
+ ),
+ relations=_bounded_strings(
+ view.get("relations", []),
+ key="graph_render.view.relations",
+ source=descriptor_path,
+ ),
+ authorities=_bounded_strings(
+ view.get("authorities", []),
+ key="graph_render.view.authorities",
+ source=descriptor_path,
+ ),
+ statuses=_bounded_strings(
+ view.get("statuses", []),
+ key="graph_render.view.statuses",
+ source=descriptor_path,
+ ),
+ tags=_bounded_strings(
+ view.get("tags", []),
+ key="graph_render.view.tags",
+ source=descriptor_path,
+ ),
+ include_logic=include_logic,
+ )
+ )
+ return GraphRenderConfig(
+ output_root=output_root,
+ views=tuple(sorted(views, key=lambda item: item.view_id)),
+ )
diff --git a/src/docforge/graph_rendering.py b/src/docforge/graph_rendering.py
new file mode 100644
index 0000000..ee5c1a7
--- /dev/null
+++ b/src/docforge/graph_rendering.py
@@ -0,0 +1,815 @@
+"""Declared portable graph planning, publication, and receipt-only status."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import cast
+
+from ._fs_safety import (
+ atomic_replace_bytes_at,
+ open_confined_directory,
+ read_bounded_file_at,
+ require_bound_directory,
+ safe_file_identity_at,
+)
+from .errors import DocForgeError
+from .graph_projection import (
+ GraphViewRequestV1,
+ build_graph_projection_package,
+ build_graph_view_plan,
+)
+from .models import (
+ GenerationRecordingProject,
+ GraphRenderConfig,
+ GraphRenderView,
+ IncrementalStateProject,
+ ProjectService,
+ ProjectSnapshot,
+ ProjectState,
+)
+from .project import project_root_fingerprint
+from .projection_contract import GraphViewPlanV1, ProjectionReceiptV1, projection_hash
+from .projection_policy import (
+ PortableGraphProjectionMode,
+ validate_portable_graph_projection_mode,
+)
+from .projection_worker import render_projection_in_worker
+
+GRAPH_RENDERER_ID = "portable_graph_html"
+GRAPH_RENDERER_VERSION = "1"
+GRAPH_PUBLICATION_MANIFEST_VERSION = 1
+GRAPH_PUBLICATION_CONTRACT = "docforge.graph-publication"
+MAX_GRAPH_PUBLICATION_BYTES = 256_000
+
+
+class GraphRenderService:
+ """Publish one declared artifact while keeping planning and rendering independent."""
+
+ def __init__(
+ self,
+ project: ProjectService,
+ *,
+ allow_logic: bool = False,
+ portable_graph_policy: PortableGraphProjectionMode = "explicit",
+ ) -> None:
+ self.project = project
+ self.allow_logic = allow_logic
+ self.portable_graph_policy = validate_portable_graph_projection_mode(portable_graph_policy)
+
+ def _require_rendering(self, operation: str) -> None:
+ if self.portable_graph_policy == "disabled":
+ raise DocForgeError(
+ "projection_policy_forbids_operation",
+ "Portable graph projection policy disables rendering work",
+ projection="portable_graph",
+ mode=self.portable_graph_policy,
+ operation=operation,
+ )
+
+ def plan(self, view_id: str) -> dict[str, object]:
+ self._require_rendering("plan")
+ snapshot = self.project.load()
+ view = self._view(self._config(snapshot), view_id)
+ plan = self._plan(snapshot, view)
+ return {
+ "status": "ok",
+ **self._identity(snapshot),
+ "view_id": view.view_id,
+ "plan": plan.as_dict(),
+ }
+
+ def status(self, view_id: str | None = None) -> dict[str, object]:
+ config = self.project.descriptor.graph_render
+ current = self._current_state()
+ if config is None:
+ return self._status_result(
+ current,
+ configured=False,
+ state="not_configured",
+ outputs=[],
+ )
+ views = config.views if view_id is None else (self._view(config, view_id),)
+ first_outputs = [self._manifest_status(view, current) for view in views]
+ outputs = [self._manifest_status(view, current) for view in views]
+ if outputs != first_outputs:
+ for output in outputs:
+ if output["state"] == "current":
+ output["state"] = "stale"
+ output["reason"] = "publication_changed_during_status"
+ final = self._current_state()
+ if final != current:
+ for output in outputs:
+ if output["state"] == "current":
+ output["state"] = "stale"
+ output["reason"] = "source_changed_during_status"
+ identity = final if final is not None else current
+ return self._status_result(
+ identity,
+ configured=True,
+ state="current" if all(item["state"] == "current" for item in outputs) else "stale",
+ outputs=outputs,
+ )
+
+ def render(self, view_id: str) -> dict[str, object]:
+ self._require_rendering("render")
+ with self._lock():
+ current_status = self.status(view_id)
+ current_outputs = cast(list[dict[str, object]], current_status["outputs"])
+ if current_status["state"] == "current" and current_outputs:
+ return {
+ **current_status,
+ "publication": "unchanged",
+ "output": current_outputs[0],
+ }
+ snapshot = self.project.load()
+ view = self._view(self._config(snapshot), view_id)
+ plan = self._plan(snapshot, view)
+ package = build_graph_projection_package(
+ plan,
+ renderer_id=GRAPH_RENDERER_ID,
+ renderer_version=GRAPH_RENDERER_VERSION,
+ max_output_bytes=snapshot.descriptor.limits.max_render_bytes,
+ )
+ result = render_projection_in_worker(package)
+ if len(result.artifacts) != 1:
+ raise DocForgeError(
+ "invalid_projection",
+ "Portable graph renderer returned an unsupported artifact set",
+ )
+ artifact = result.artifacts[0]
+
+ def verify() -> None:
+ current = self.project.load()
+ if (
+ current.revision != snapshot.revision
+ or current.source_hash != snapshot.source_hash
+ ):
+ raise DocForgeError(
+ "render_input_changed",
+ "Canonical input changed during portable graph rendering",
+ )
+
+ verify()
+ if isinstance(self.project, GenerationRecordingProject):
+ self.project.record_generation(snapshot)
+ artifact_evidence = artifact.evidence()
+ try:
+ store_identity = self._publish_artifact(
+ snapshot,
+ artifact_evidence["sha256"],
+ artifact.content,
+ verify=verify,
+ )
+ except DocForgeError as error:
+ if self._mutation_committed(error):
+ return self._degraded_publication(
+ snapshot,
+ view,
+ plan,
+ package.package_id,
+ result.receipt.as_dict(),
+ artifact_evidence,
+ stage="artifact_store",
+ error=error,
+ output_published=False,
+ )
+ raise
+ try:
+ output_identity = self._publish_output(
+ snapshot,
+ view,
+ artifact.content,
+ verify=verify,
+ )
+ except DocForgeError as error:
+ if self._mutation_committed(error):
+ return self._degraded_publication(
+ snapshot,
+ view,
+ plan,
+ package.package_id,
+ result.receipt.as_dict(),
+ artifact_evidence,
+ stage="output",
+ error=error,
+ output_published=True,
+ )
+ raise
+ manifest = self._manifest(
+ snapshot,
+ view,
+ plan,
+ package.package_id,
+ result.receipt.as_dict(),
+ artifact_evidence,
+ store_identity,
+ output_identity,
+ )
+ try:
+ self._publish_manifest(snapshot, view, manifest, verify=verify)
+ except DocForgeError as error:
+ return self._degraded_publication(
+ snapshot,
+ view,
+ plan,
+ package.package_id,
+ result.receipt.as_dict(),
+ artifact_evidence,
+ stage="manifest",
+ error=error,
+ output_published=True,
+ )
+ return {
+ "status": "ok",
+ **self._identity(snapshot),
+ "view_id": view.view_id,
+ "state": "current",
+ "publication": "published",
+ "plan_id": plan.plan_id,
+ "package_id": package.package_id,
+ "output": {
+ **artifact.evidence(),
+ "path": view.output_path.relative_to(snapshot.descriptor.root).as_posix(),
+ },
+ "receipt": result.receipt.as_dict(),
+ "manifest": {
+ "state": "current",
+ "publication_id": manifest["publication_id"],
+ },
+ }
+
+ @staticmethod
+ def _mutation_committed(error: DocForgeError) -> bool:
+ return error.details.get("mutation_committed") is True
+
+ def _degraded_publication(
+ self,
+ snapshot: ProjectSnapshot,
+ view: GraphRenderView,
+ plan: GraphViewPlanV1,
+ package_id: str,
+ receipt: dict[str, object],
+ artifact: dict[str, object],
+ *,
+ stage: str,
+ error: DocForgeError,
+ output_published: bool,
+ ) -> dict[str, object]:
+ return {
+ "status": "ok",
+ **self._identity(snapshot),
+ "view_id": view.view_id,
+ "state": "degraded",
+ "publication": "published" if output_published else "partial",
+ "committed_stage": stage,
+ "plan_id": plan.plan_id,
+ "package_id": package_id,
+ "artifact": artifact,
+ "output": {
+ **artifact,
+ "path": view.output_path.relative_to(snapshot.descriptor.root).as_posix(),
+ "state": "unverified" if output_published else "not_published",
+ },
+ "receipt": receipt,
+ "manifest": {
+ "state": "failed",
+ "error": error.as_dict(),
+ },
+ }
+
+ def _manifest_status(
+ self,
+ view: GraphRenderView,
+ current: ProjectState | None,
+ ) -> dict[str, object]:
+ manifest = self._read_manifest(view)
+ base = {
+ "view_id": view.view_id,
+ "renderer": GRAPH_RENDERER_ID,
+ "renderer_version": GRAPH_RENDERER_VERSION,
+ "path": view.output_path.relative_to(self.project.descriptor.root).as_posix(),
+ "verification": "manifest",
+ }
+ if manifest is None:
+ return {**base, "state": "missing", "reason": "manifest_missing"}
+ if not self._valid_manifest(view, manifest):
+ return {**base, "state": "unverified", "reason": "manifest_invalid"}
+ if current is None:
+ reason = (
+ "source_generation_changed"
+ if isinstance(self.project, GenerationRecordingProject)
+ else "source_generation_unavailable"
+ )
+ return {
+ **base,
+ "state": (
+ "stale"
+ if isinstance(self.project, GenerationRecordingProject)
+ else "unverified"
+ ),
+ "reason": reason,
+ "plan_id": manifest.get("plan_id"),
+ "package_id": manifest.get("package_id"),
+ }
+ project = cast(dict[str, object], manifest["project"])
+ if project["revision"] != current.revision or project["source_hash"] != current.source_hash:
+ return {
+ **base,
+ "state": "stale",
+ "reason": "source_generation_changed",
+ "plan_id": manifest["plan_id"],
+ "package_id": manifest["package_id"],
+ }
+ artifact = cast(dict[str, object], manifest["artifact"])
+ store = cast(dict[str, object], manifest["store"])
+ artifact_root = self.project.descriptor.cache_root / "projection-artifacts"
+ if not artifact_root.exists():
+ return {
+ **base,
+ "state": "stale",
+ "reason": "artifact_store_missing",
+ "plan_id": manifest["plan_id"],
+ "package_id": manifest["package_id"],
+ }
+ if artifact_root.is_symlink() or not artifact_root.is_dir():
+ return {
+ **base,
+ "state": "unsafe",
+ "reason": "artifact_store_unsafe",
+ "plan_id": manifest["plan_id"],
+ "package_id": manifest["package_id"],
+ }
+ artifact_directory: int | None = None
+ try:
+ artifact_directory = open_confined_directory(
+ self.project.descriptor.root,
+ artifact_root,
+ create=False,
+ )
+ artifact_identity = safe_file_identity_at(
+ artifact_root,
+ artifact_directory,
+ f"{artifact['sha256']}.html",
+ )
+ except DocForgeError:
+ return {
+ **base,
+ "state": "unsafe",
+ "reason": "artifact_store_unsafe",
+ "plan_id": manifest["plan_id"],
+ "package_id": manifest["package_id"],
+ }
+ finally:
+ if artifact_directory is not None:
+ os.close(artifact_directory)
+ if artifact_identity is None:
+ return {
+ **base,
+ "state": "stale",
+ "reason": "artifact_store_missing",
+ "plan_id": manifest["plan_id"],
+ "package_id": manifest["package_id"],
+ }
+ if artifact_identity != store:
+ return {
+ **base,
+ "state": "stale",
+ "reason": "artifact_store_changed",
+ "plan_id": manifest["plan_id"],
+ "package_id": manifest["package_id"],
+ }
+ try:
+ directory = open_confined_directory(
+ self.project.descriptor.root,
+ view.output_path.parent,
+ create=False,
+ )
+ except DocForgeError:
+ return {**base, "state": "unsafe", "reason": "output_root_unsafe"}
+ try:
+ identity = safe_file_identity_at(
+ view.output_path.parent, directory, view.output_path.name
+ )
+ except DocForgeError:
+ return {**base, "state": "unsafe", "reason": "output_unsafe"}
+ finally:
+ os.close(directory)
+ expected = cast(dict[str, object], manifest["output"])
+ if identity != expected:
+ return {
+ **base,
+ "state": "stale",
+ "reason": "output_changed",
+ "plan_id": manifest["plan_id"],
+ "package_id": manifest["package_id"],
+ }
+ return {
+ **base,
+ "state": "current",
+ "reason": None,
+ "plan_id": manifest["plan_id"],
+ "package_id": manifest["package_id"],
+ "publication_id": manifest["publication_id"],
+ "artifact": manifest["artifact"],
+ }
+
+ def _read_manifest(self, view: GraphRenderView) -> dict[str, object] | None:
+ root = self._manifest_root()
+ if not root.is_dir() or root.is_symlink():
+ return None
+ try:
+ descriptor = open_confined_directory(
+ self.project.descriptor.root,
+ root,
+ create=False,
+ )
+ except DocForgeError:
+ return None
+ try:
+ raw = read_bounded_file_at(
+ descriptor,
+ f"{view.view_id}.json",
+ MAX_GRAPH_PUBLICATION_BYTES,
+ )
+ except DocForgeError:
+ return None
+ finally:
+ os.close(descriptor)
+ if raw is None:
+ return None
+ try:
+ value: object = json.loads(raw)
+ except (UnicodeDecodeError, json.JSONDecodeError):
+ return None
+ return cast(dict[str, object], value) if isinstance(value, dict) else None
+
+ def _valid_manifest(self, view: GraphRenderView, manifest: dict[str, object]) -> bool:
+ required = {
+ "schema_version",
+ "contract",
+ "publication_id",
+ "project",
+ "view_id",
+ "view_config_hash",
+ "plan_id",
+ "package_id",
+ "renderer",
+ "receipt",
+ "artifact",
+ "store",
+ "output",
+ }
+ try:
+ if (
+ set(manifest) != required
+ or manifest.get("schema_version") != GRAPH_PUBLICATION_MANIFEST_VERSION
+ or manifest.get("contract") != GRAPH_PUBLICATION_CONTRACT
+ or manifest.get("view_id") != view.view_id
+ or manifest.get("view_config_hash") != self._view_hash(view)
+ or not self._hash(manifest.get("plan_id"))
+ or not self._hash(manifest.get("package_id"))
+ ):
+ return False
+ project = manifest.get("project")
+ descriptor = self.project.descriptor
+ if not isinstance(project, dict):
+ return False
+ project_document = cast(dict[str, object], project)
+ if (
+ set(project_document)
+ != {
+ "project_id",
+ "project_root_fingerprint",
+ "adapter",
+ "revision",
+ "source_hash",
+ }
+ or project_document.get("project_id") != descriptor.project_id
+ or project_document.get("project_root_fingerprint")
+ != project_root_fingerprint(descriptor.root)
+ or project_document.get("adapter") != descriptor.adapter
+ or not isinstance(project_document.get("revision"), str)
+ or not project_document["revision"]
+ or not self._hash(project_document.get("source_hash"))
+ ):
+ return False
+ renderer = manifest.get("renderer")
+ if renderer != {
+ "renderer_id": GRAPH_RENDERER_ID,
+ "renderer_version": GRAPH_RENDERER_VERSION,
+ }:
+ return False
+ receipt_value = manifest.get("receipt")
+ if not isinstance(receipt_value, dict):
+ return False
+ receipt = ProjectionReceiptV1.from_dict(
+ dict(cast(dict[str, object], receipt_value))
+ ).as_dict()
+ artifacts = receipt.get("artifacts")
+ if not isinstance(artifacts, list):
+ return False
+ artifact_values = cast(list[object], artifacts)
+ if (
+ receipt.get("kind") != "graph"
+ or receipt.get("plan_id") != manifest["plan_id"]
+ or receipt.get("package_id") != manifest["package_id"]
+ or receipt.get("renderer") != renderer
+ or len(artifact_values) != 1
+ or manifest.get("artifact") != artifact_values[0]
+ ):
+ return False
+ artifact = artifact_values[0]
+ if not isinstance(artifact, dict):
+ return False
+ artifact_document = cast(dict[str, object], artifact)
+ if (
+ artifact_document.get("artifact_id") != "portable-graph.html"
+ or artifact_document.get("media_type") != "text/html; charset=utf-8"
+ ):
+ return False
+ artifact_hash = artifact_document.get("sha256")
+ artifact_bytes = artifact_document.get("bytes")
+ store = manifest.get("store")
+ output = manifest.get("output")
+ if (
+ not self._file_identity(store, expected_name=f"{artifact_hash}.html")
+ or not self._file_identity(output, expected_name=view.output_path.name)
+ or type(artifact_bytes) is not int
+ or cast(dict[str, object], store)["size"] != artifact_bytes
+ or cast(dict[str, object], output)["size"] != artifact_bytes
+ ):
+ return False
+ body = dict(manifest)
+ publication_id = body.pop("publication_id", None)
+ return self._hash(publication_id) and publication_id == projection_hash(body)
+ except (DocForgeError, KeyError, TypeError, ValueError):
+ return False
+
+ @staticmethod
+ def _hash(value: object) -> bool:
+ return (
+ isinstance(value, str)
+ and len(value) == 64
+ and all(character in "0123456789abcdef" for character in value)
+ )
+
+ @staticmethod
+ def _file_identity(value: object, *, expected_name: str) -> bool:
+ if not isinstance(value, dict):
+ return False
+ document = cast(dict[str, object], value)
+ required = {"path", "device", "inode", "mode", "size", "mtime_ns", "ctime_ns"}
+ return (
+ set(document) == required
+ and document.get("path") == expected_name
+ and all(
+ type(document.get(field)) is int and cast(int, document[field]) >= 0
+ for field in required - {"path"}
+ )
+ )
+
+ def _manifest(
+ self,
+ snapshot: ProjectSnapshot,
+ view: GraphRenderView,
+ plan: GraphViewPlanV1,
+ package_id: str,
+ receipt: dict[str, object],
+ artifact: dict[str, object],
+ store: dict[str, object],
+ output: dict[str, object],
+ ) -> dict[str, object]:
+ body: dict[str, object] = {
+ "schema_version": GRAPH_PUBLICATION_MANIFEST_VERSION,
+ "contract": GRAPH_PUBLICATION_CONTRACT,
+ "project": self._identity(snapshot),
+ "view_id": view.view_id,
+ "view_config_hash": self._view_hash(view),
+ "plan_id": plan.plan_id,
+ "package_id": package_id,
+ "renderer": {
+ "renderer_id": GRAPH_RENDERER_ID,
+ "renderer_version": GRAPH_RENDERER_VERSION,
+ },
+ "receipt": receipt,
+ "artifact": artifact,
+ "store": store,
+ "output": output,
+ }
+ return {**body, "publication_id": projection_hash(body)}
+
+ def _publish_artifact(
+ self,
+ snapshot: ProjectSnapshot,
+ artifact_hash: object,
+ content: bytes,
+ *,
+ verify: Callable[[], None],
+ ) -> dict[str, object]:
+ if not isinstance(artifact_hash, str):
+ raise DocForgeError("invalid_projection", "Artifact hash is invalid")
+ root = snapshot.descriptor.cache_root / "projection-artifacts"
+ descriptor = open_confined_directory(snapshot.descriptor.root, root, create=True)
+ name = f"{artifact_hash}.html"
+ try:
+ try:
+ existing = read_bounded_file_at(descriptor, name, len(content))
+ except DocForgeError as error:
+ if error.code != "invalid_projection":
+ raise
+ existing = None
+ if existing == content:
+ identity = safe_file_identity_at(root, descriptor, name)
+ assert identity is not None
+ return identity
+ return atomic_replace_bytes_at(root, descriptor, name, content, verify=verify)
+ finally:
+ os.close(descriptor)
+
+ def _publish_output(
+ self,
+ snapshot: ProjectSnapshot,
+ view: GraphRenderView,
+ content: bytes,
+ *,
+ verify: Callable[[], None],
+ ) -> dict[str, object]:
+ root = view.output_path.parent
+ descriptor = open_confined_directory(snapshot.descriptor.root, root, create=True)
+ try:
+ try:
+ existing = read_bounded_file_at(
+ descriptor,
+ view.output_path.name,
+ len(content),
+ )
+ except DocForgeError as error:
+ if error.code != "invalid_projection":
+ raise
+ existing = None
+ if existing == content:
+ identity = safe_file_identity_at(root, descriptor, view.output_path.name)
+ assert identity is not None
+ return identity
+ return atomic_replace_bytes_at(
+ root,
+ descriptor,
+ view.output_path.name,
+ content,
+ verify=verify,
+ )
+ finally:
+ os.close(descriptor)
+
+ def _publish_manifest(
+ self,
+ snapshot: ProjectSnapshot,
+ view: GraphRenderView,
+ manifest: dict[str, object],
+ *,
+ verify: Callable[[], None],
+ ) -> None:
+ raw = json.dumps(manifest, sort_keys=True, indent=2).encode() + b"\n"
+ if len(raw) > MAX_GRAPH_PUBLICATION_BYTES:
+ raise DocForgeError(
+ "projection_too_large",
+ "Portable graph publication manifest exceeds its fixed limit",
+ )
+ root = self._manifest_root()
+ descriptor = open_confined_directory(snapshot.descriptor.root, root, create=True)
+ try:
+ atomic_replace_bytes_at(
+ root,
+ descriptor,
+ f"{view.view_id}.json",
+ raw,
+ verify=verify,
+ )
+ finally:
+ os.close(descriptor)
+
+ @contextmanager
+ def _lock(self) -> Generator[None]:
+ root = self.project.descriptor.cache_root
+ descriptor = open_confined_directory(self.project.descriptor.root, root, create=True)
+ lock_descriptor: int | None = None
+ try:
+ lock_descriptor = os.open(
+ "graph-render.lock",
+ os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW,
+ 0o600,
+ dir_fd=descriptor,
+ )
+ fcntl.flock(lock_descriptor, fcntl.LOCK_EX)
+ require_bound_directory(root, descriptor)
+ yield
+ except OSError as error:
+ raise DocForgeError(
+ "publication_failure",
+ "Portable graph render lock is unavailable",
+ ) from error
+ finally:
+ if lock_descriptor is not None:
+ os.close(lock_descriptor)
+ os.close(descriptor)
+
+ def _plan(self, snapshot: ProjectSnapshot, view: GraphRenderView) -> GraphViewPlanV1:
+ return build_graph_view_plan(
+ snapshot,
+ GraphViewRequestV1(
+ view_id=view.view_id,
+ title=view.title,
+ root_node_id=view.root_node_id,
+ query=view.query,
+ initial_mode=view.initial_mode,
+ depth=view.depth,
+ max_nodes=view.max_nodes,
+ max_edges=view.max_edges,
+ max_work=view.max_work,
+ families=view.families,
+ relations=view.relations,
+ authorities=view.authorities,
+ statuses=view.statuses,
+ tags=view.tags,
+ include_logic=view.include_logic,
+ ),
+ self.allow_logic,
+ )
+
+ def _current_state(self) -> ProjectState | None:
+ if isinstance(self.project, IncrementalStateProject):
+ return self.project.incremental_state()
+ return None
+
+ def _config(self, snapshot: ProjectSnapshot) -> GraphRenderConfig:
+ config = snapshot.descriptor.graph_render
+ if config is None:
+ raise DocForgeError(
+ "graph_render_not_configured",
+ "Project has no portable graph render configuration",
+ )
+ return config
+
+ @staticmethod
+ def _view(config: GraphRenderConfig, view_id: str) -> GraphRenderView:
+ for view in config.views:
+ if view.view_id == view_id:
+ return view
+ raise DocForgeError(
+ "unknown_graph_render_view",
+ "Portable graph view is not declared",
+ view_id=view_id,
+ )
+
+ def _manifest_root(self) -> Path:
+ return self.project.descriptor.cache_root / "projection-publications" / "graph"
+
+ @staticmethod
+ def _view_hash(view: GraphRenderView) -> str:
+ return projection_hash(
+ {
+ "view_id": view.view_id,
+ "renderer": view.renderer,
+ "title": view.title,
+ "root_node_id": view.root_node_id,
+ "query": view.query,
+ "initial_mode": view.initial_mode,
+ "depth": view.depth,
+ "max_nodes": view.max_nodes,
+ "max_edges": view.max_edges,
+ "max_work": view.max_work,
+ "families": list(view.families),
+ "relations": list(view.relations),
+ "authorities": list(view.authorities),
+ "statuses": list(view.statuses),
+ "tags": list(view.tags),
+ "include_logic": view.include_logic,
+ }
+ )
+
+ def _status_result(self, current: ProjectState | None, **payload: object) -> dict[str, object]:
+ descriptor = self.project.descriptor
+ return {
+ "status": "ok",
+ "project_id": descriptor.project_id,
+ "project_root_fingerprint": project_root_fingerprint(descriptor.root),
+ "adapter": descriptor.adapter,
+ "revision": current.revision if current is not None else "unknown",
+ "source_hash": current.source_hash if current is not None else None,
+ **payload,
+ }
+
+ @staticmethod
+ def _identity(snapshot: ProjectSnapshot) -> dict[str, object]:
+ return {
+ "project_id": snapshot.descriptor.project_id,
+ "project_root_fingerprint": project_root_fingerprint(snapshot.descriptor.root),
+ "adapter": snapshot.descriptor.adapter,
+ "revision": snapshot.revision,
+ "source_hash": snapshot.source_hash,
+ }
diff --git a/src/docforge/manual_projection.py b/src/docforge/manual_projection.py
new file mode 100644
index 0000000..a249d38
--- /dev/null
+++ b/src/docforge/manual_projection.py
@@ -0,0 +1,208 @@
+"""Pure manual planning over one immutable validated graph generation."""
+
+from __future__ import annotations
+
+import hashlib
+from collections import defaultdict
+from collections.abc import Sequence
+
+from .errors import DocForgeError
+from .models import Edge, ProjectSnapshot, RenderView
+from .project import project_root_fingerprint
+from .projection_contract import ManualRenderPlanV1, ProjectionPackageV1
+
+
+def _edge_dict(edge: Edge) -> dict[str, str]:
+ return {
+ "source_id": edge.source_id,
+ "relation": edge.relation,
+ "target_id": edge.target_id,
+ }
+
+
+def _cycles(node_ids: tuple[str, ...], edges: tuple[Edge, ...]) -> list[list[str]]:
+ """Return deterministic strongly connected components that represent cycles."""
+
+ adjacency: dict[str, list[str]] = {node_id: [] for node_id in node_ids}
+ reverse_adjacency: dict[str, list[str]] = {node_id: [] for node_id in node_ids}
+ for edge in edges:
+ adjacency[edge.source_id].append(edge.target_id)
+ reverse_adjacency[edge.target_id].append(edge.source_id)
+ for targets in (*adjacency.values(), *reverse_adjacency.values()):
+ targets.sort()
+
+ visited: set[str] = set()
+ finished: list[str] = []
+ for node_id in node_ids:
+ if node_id in visited:
+ continue
+ visited.add(node_id)
+ traversal: list[tuple[str, int]] = [(node_id, 0)]
+ while traversal:
+ current, position = traversal[-1]
+ targets = adjacency[current]
+ if position < len(targets):
+ target = targets[position]
+ traversal[-1] = (current, position + 1)
+ if target not in visited:
+ visited.add(target)
+ traversal.append((target, 0))
+ continue
+ finished.append(current)
+ traversal.pop()
+
+ assigned: set[str] = set()
+ components: list[list[str]] = []
+ for node_id in reversed(finished):
+ if node_id in assigned:
+ continue
+ assigned.add(node_id)
+ component: list[str] = []
+ component_stack = [node_id]
+ while component_stack:
+ current = component_stack.pop()
+ component.append(current)
+ for target in reversed(reverse_adjacency[current]):
+ if target not in assigned:
+ assigned.add(target)
+ component_stack.append(target)
+ component.sort()
+ if len(component) > 1 or component[0] in adjacency[component[0]]:
+ components.append(component)
+ return sorted(components)
+
+
+def build_manual_render_plan(
+ snapshot: ProjectSnapshot,
+ view: RenderView,
+ *,
+ changeset_hash: str | None,
+) -> ManualRenderPlanV1:
+ """Select and describe a complete manual without rendering markup."""
+
+ selected = tuple(
+ node for node in snapshot.nodes if not view.families or node.family in view.families
+ )
+ selected_ids = {node.node_id for node in selected}
+ edges = tuple(
+ edge
+ for edge in snapshot.edges
+ if edge.source_id in selected_ids and edge.target_id in selected_ids
+ )
+ outgoing: dict[str, list[Edge]] = defaultdict(list)
+ incoming: dict[str, list[Edge]] = defaultdict(list)
+ for edge in edges:
+ outgoing[edge.source_id].append(edge)
+ incoming[edge.target_id].append(edge)
+ for values in (*outgoing.values(), *incoming.values()):
+ values.sort(key=lambda edge: (edge.source_id, edge.relation, edge.target_id))
+
+ pages = [
+ {
+ "node_id": node.node_id,
+ "title": node.title,
+ "family": node.family,
+ "authority": node.authority,
+ "status": node.status,
+ "tags": list(node.tags),
+ "summary": node.summary,
+ "content": node.content,
+ "content_hash": node.content_hash,
+ "components": [
+ "manual.node-metadata@1",
+ "manual.summary@1",
+ "manual.commonmark@1",
+ "manual.relationships@1",
+ ],
+ "breadcrumbs": [],
+ "cross_references": [_edge_dict(edge) for edge in outgoing[node.node_id]],
+ "backlinks": [_edge_dict(edge) for edge in incoming[node.node_id]],
+ }
+ for node in selected
+ ]
+ node_ids = tuple(node.node_id for node in selected)
+ connected = {endpoint for edge in edges for endpoint in (edge.source_id, edge.target_id)}
+ return ManualRenderPlanV1.create(
+ {
+ "project": {
+ "project_id": snapshot.descriptor.project_id,
+ "project_root_fingerprint": project_root_fingerprint(snapshot.descriptor.root),
+ "adapter": snapshot.descriptor.adapter,
+ "revision": snapshot.revision,
+ "source_hash": snapshot.source_hash,
+ },
+ "view": {
+ "view_id": view.view_id,
+ "title": view.title,
+ "families": list(view.families),
+ "renderer": view.renderer,
+ },
+ "changeset_hash": changeset_hash,
+ "pages": pages,
+ "navigation": [{"node_id": node.node_id, "title": node.title} for node in selected],
+ "search_documents": [
+ {
+ "node_id": node.node_id,
+ "title": node.title,
+ "summary": node.summary,
+ "family": node.family,
+ "status": node.status,
+ "tags": list(node.tags),
+ }
+ for node in selected
+ ],
+ "diagnostics": {
+ "orphans": [node_id for node_id in node_ids if node_id not in connected],
+ "cycles": _cycles(node_ids, edges),
+ },
+ }
+ )
+
+
+def build_manual_projection_package(
+ plan: ManualRenderPlanV1,
+ template_bytes: bytes,
+ *,
+ renderer_id: str,
+ renderer_version: str,
+ max_output_bytes: int,
+ render_identity: str | None = None,
+ fragment_records: Sequence[dict[str, object]] = (),
+) -> ProjectionPackageV1:
+ """Bind one plan and inert template asset for a path-free manual renderer."""
+
+ try:
+ template = template_bytes.decode("utf-8")
+ except UnicodeDecodeError as error:
+ raise DocForgeError("invalid_template", "Render template is not valid UTF-8") from error
+ template_asset: dict[str, object] = {
+ "asset_id": "manual.template",
+ "media_type": "text/html; charset=utf-8",
+ "sha256": hashlib.sha256(template_bytes).hexdigest(),
+ "text": template,
+ }
+ if render_identity is not None:
+ template_asset["render_identity"] = render_identity
+ assets = [template_asset]
+ if fragment_records:
+ assets.append(
+ {
+ "asset_id": "manual.fragments",
+ "media_type": "application/vnd.docforge.projection-fragments.v1+json",
+ "records": list(fragment_records),
+ }
+ )
+ return ProjectionPackageV1.create(
+ kind="manual",
+ plan=plan,
+ renderer={"renderer_id": renderer_id, "renderer_version": renderer_version},
+ components=[
+ {"component_id": "manual.document@1"},
+ {"component_id": "manual.commonmark@1"},
+ ],
+ assets=assets,
+ output_policy={
+ "artifact_ids": ["manual.html"],
+ "max_total_bytes": max_output_bytes,
+ },
+ )
diff --git a/src/docforge/mcp_server.py b/src/docforge/mcp_server.py
index d90e7b2..21e6544 100644
--- a/src/docforge/mcp_server.py
+++ b/src/docforge/mcp_server.py
@@ -15,11 +15,13 @@ from .application import CanonicalApplicationService, CanonicalApplier, GenericC
from .changesets import ChangesetStore
from .context import compile_context
from .errors import DocForgeError
+from .graph_rendering import GraphRenderService
from .index import ProjectIndex
from .models import IncrementalStateProject, ProjectService, RuntimeValidatedProject
from .pagination import canonical_hash, decode_cursor, page_limit, page_receipt
from .policy import CapabilityMode, capability_mode, compose_effective_policy
from .project import Project, project_root_fingerprint
+from .projection_policy import compose_projection_policy
from .rendering import RenderService
from .retrieval import MAX_TASK_EVIDENCE, TaskKind, build_retrieval_plan
from .telemetry import request, stage
@@ -47,6 +49,8 @@ READ_TOOLS = (
"docforge_get_task_context",
"docforge_validate_project",
"docforge_render_status",
+ "docforge_graph_plan",
+ "docforge_graph_render_status",
"docforge_visualize",
"docforge_stop_visualization",
"docforge_visualization_status",
@@ -134,6 +138,9 @@ class DocForgeService:
no_ast: bool = False,
diagnostics: bool = False,
capability_mode_name: str | None = None,
+ manual_projection_policy: str | None = None,
+ portable_graph_policy: str | None = None,
+ live_viewer_policy: str | None = None,
) -> None:
self.project = project
default_mode: CapabilityMode = (
@@ -153,19 +160,40 @@ class DocForgeService:
render_configured=project.descriptor.render is not None,
application_enabled=application_enabled,
)
+ self.projection_policy = compose_projection_policy(
+ manual=manual_projection_policy,
+ portable_graph=portable_graph_policy,
+ live_viewer=live_viewer_policy,
+ manual_configured=project.descriptor.render is not None,
+ portable_graph_configured=project.descriptor.graph_render is not None,
+ application_enabled=application_enabled,
+ )
self.index = ProjectIndex(self.project, allow_logic=not self.policy.no_ast)
self.changesets = ChangesetStore(
self.project,
proposal_writer if selected_mode != "read" else None,
)
- self.rendering = RenderService(self.project, self.changesets)
+ self.rendering = RenderService(
+ self.project,
+ self.changesets,
+ manual_policy=self.projection_policy.manual,
+ )
+ self.graph_rendering = GraphRenderService(
+ self.project,
+ allow_logic=not self.policy.no_ast,
+ portable_graph_policy=self.projection_policy.portable_graph,
+ )
self.application = CanonicalApplicationService(
self.project,
applier_id=canonical_applier_id if application_enabled else None,
applier=canonical_applier if application_enabled else None,
index=self.index,
+ manual_policy=self.projection_policy.manual,
+ )
+ self.visualization = ViewerManagerClient(
+ self.index,
+ live_viewer_policy=self.projection_policy.live_viewer,
)
- self.visualization = ViewerManagerClient(self.index)
self.context_provider = context_provider
self.task_context_available = context_provider is compile_context
self.binding_metadata = dict(binding_metadata or {})
@@ -621,6 +649,7 @@ class DocForgeService:
}
capabilities = self.capabilities()
effective_policy = self.policy.as_dict()
+ projection_policy = self.projection_policy.as_dict()
session_contract: dict[str, object] = {
"schema_version": 1,
"binding": binding,
@@ -630,6 +659,8 @@ class DocForgeService:
"freshness": "current",
},
"effective_policy": effective_policy,
+ "projection_policy": projection_policy,
+ "projection_policy_hash": self.projection_policy.policy_hash,
"capabilities": capabilities,
"render_policies": {
"manual": effective_policy["manual_render"],
@@ -652,6 +683,8 @@ class DocForgeService:
"canonical_paths": [str(path) for path in descriptor.content_roots],
"adapter_policy": self.adapter_policy(),
"effective_policy": effective_policy,
+ "projection_policy": projection_policy,
+ "projection_policy_hash": self.projection_policy.policy_hash,
"capabilities": capabilities,
"session_contract": session_contract,
"proposal_access": proposal_access,
@@ -714,6 +747,8 @@ class DocForgeService:
),
"adapter_policy": self.adapter_policy(),
"effective_policy": self.policy.as_dict(),
+ "projection_policy": self.projection_policy.as_dict(),
+ "projection_policy_hash": self.projection_policy.policy_hash,
"capabilities": self.capabilities(),
"canonical_paths": [
*(relative(path) for path in snapshot.descriptor.content_roots),
@@ -829,6 +864,29 @@ class DocForgeService:
operation_name="mcp.render_status",
)
+ def graph_plan(self, view_id: str) -> dict[str, object]:
+ """Plan one declared portable graph without publishing derived output."""
+
+ return self.invoke(
+ lambda: self.graph_rendering.plan(view_id),
+ synchronize=False,
+ load_error_identity=False,
+ operation_name="mcp.graph_plan",
+ )
+
+ def graph_render_status(
+ self,
+ view_id: str | None = None,
+ ) -> dict[str, object]:
+ """Report portable-graph publication state without planning or rendering."""
+
+ return self.invoke(
+ lambda: self.graph_rendering.status(view_id),
+ synchronize=False,
+ load_error_identity=False,
+ operation_name="mcp.graph_render_status",
+ )
+
def context(
self,
profile: str,
@@ -1575,6 +1633,18 @@ def _create_bound_server(service: DocForgeService, *, read_only: bool) -> FastMC
return service.render_status(view_id, deep=deep)
+ @server.tool(name="docforge_graph_plan")
+ def graph_plan(view_id: str) -> dict[str, Any]:
+ """Plan one declared portable graph without publishing derived output."""
+
+ return service.graph_plan(view_id)
+
+ @server.tool(name="docforge_graph_render_status")
+ def graph_render_status(view_id: str | None = None) -> dict[str, Any]:
+ """Report portable-graph publication state without rendering."""
+
+ return service.graph_render_status(view_id)
+
@server.tool(name="docforge_visualize")
def visualize(
node_id: str | None = None,
@@ -1622,6 +1692,8 @@ def _create_bound_server(service: DocForgeService, *, read_only: bool) -> FastMC
get_task_context,
validate_project,
render_status,
+ graph_plan,
+ graph_render_status,
visualize,
stop_visualization,
visualization_status,
@@ -2004,6 +2076,9 @@ def create_server(
no_ast: bool = False,
diagnostics: bool = False,
capability_mode: str | None = None,
+ manual_projection_policy: str | None = None,
+ portable_graph_policy: str | None = None,
+ live_viewer_policy: str | None = None,
) -> FastMCP:
project = Project.open(project_root)
return create_project_server(
@@ -2020,6 +2095,9 @@ def create_server(
no_ast=no_ast,
diagnostics=diagnostics,
capability_mode=capability_mode,
+ manual_projection_policy=manual_projection_policy,
+ portable_graph_policy=portable_graph_policy,
+ live_viewer_policy=live_viewer_policy,
)
@@ -2034,6 +2112,9 @@ def create_project_server(
no_ast: bool = False,
diagnostics: bool = False,
capability_mode: str | None = None,
+ manual_projection_policy: str | None = None,
+ portable_graph_policy: str | None = None,
+ live_viewer_policy: str | None = None,
) -> FastMCP:
"""Create the full fixed MCP surface for one explicitly configured project service."""
@@ -2047,6 +2128,9 @@ def create_project_server(
no_ast=no_ast,
diagnostics=diagnostics,
capability_mode_name=capability_mode,
+ manual_projection_policy=manual_projection_policy,
+ portable_graph_policy=portable_graph_policy,
+ live_viewer_policy=live_viewer_policy,
)
return _create_bound_server(
service,
@@ -2062,6 +2146,9 @@ def create_read_only_server(
no_ast: bool = False,
diagnostics: bool = False,
capability_mode: str | None = None,
+ manual_projection_policy: str | None = None,
+ portable_graph_policy: str | None = None,
+ live_viewer_policy: str | None = None,
) -> FastMCP:
"""Create an adapter-capable MCP server exposing only the fixed read tool surface."""
@@ -2073,6 +2160,9 @@ def create_read_only_server(
no_ast=no_ast,
diagnostics=diagnostics,
capability_mode_name="read" if capability_mode is None else capability_mode,
+ manual_projection_policy=manual_projection_policy,
+ portable_graph_policy=portable_graph_policy,
+ live_viewer_policy=live_viewer_policy,
)
if service.policy.capability_mode != "read":
raise DocForgeError(
@@ -2106,6 +2196,18 @@ def main() -> None:
choices=("read", "proposal", "application", "operator"),
help="Expose the versioned project-bound capability surface",
)
+ parser.add_argument(
+ "--manual-render-policy",
+ choices=("auto", "explicit", "disabled"),
+ )
+ parser.add_argument(
+ "--portable-graph-policy",
+ choices=("explicit", "disabled"),
+ )
+ parser.add_argument(
+ "--live-viewer-policy",
+ choices=("on-demand", "disabled"),
+ )
arguments = parser.parse_args()
create_server(
arguments.project_root,
@@ -2114,6 +2216,9 @@ def main() -> None:
no_ast=arguments.no_ast,
diagnostics=arguments.diagnostics,
capability_mode=arguments.capability_mode,
+ manual_projection_policy=arguments.manual_render_policy,
+ portable_graph_policy=arguments.portable_graph_policy,
+ live_viewer_policy=arguments.live_viewer_policy,
).run(transport="stdio")
diff --git a/src/docforge/models.py b/src/docforge/models.py
index 47d5339..efcd71f 100644
--- a/src/docforge/models.py
+++ b/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, runtime_checkable
+from typing import Literal, Protocol, runtime_checkable
@dataclass(frozen=True)
@@ -49,6 +49,33 @@ class RenderConfig:
views: tuple[RenderView, ...]
+@dataclass(frozen=True)
+class GraphRenderView:
+ view_id: str
+ renderer: str
+ output_path: Path
+ title: str
+ root_node_id: str | None
+ query: str | None
+ initial_mode: Literal["nodes", "flow", "web", "logic"]
+ depth: int
+ max_nodes: int
+ max_edges: int
+ max_work: int
+ families: tuple[str, ...]
+ relations: tuple[str, ...]
+ authorities: tuple[str, ...]
+ statuses: tuple[str, ...]
+ tags: tuple[str, ...]
+ include_logic: bool
+
+
+@dataclass(frozen=True)
+class GraphRenderConfig:
+ output_root: Path
+ views: tuple[GraphRenderView, ...]
+
+
@dataclass(frozen=True)
class ContextProfile:
profile_id: str
@@ -78,6 +105,7 @@ class ProjectDescriptor:
allowed_relations: tuple[str, ...]
profiles: tuple[ContextProfile, ...]
limits: Limits
+ graph_render: GraphRenderConfig | None = None
@dataclass(frozen=True)
diff --git a/src/docforge/project.py b/src/docforge/project.py
index 3d689bd..17052b3 100644
--- a/src/docforge/project.py
+++ b/src/docforge/project.py
@@ -25,6 +25,7 @@ from .config_validation import (
string_list,
)
from .errors import DocForgeError
+from .graph_render_config import load_graph_render_config
from .models import (
ContextProfile,
Edge,
@@ -66,6 +67,7 @@ _DESCRIPTOR_KEYS = frozenset(
"derived",
"changesets",
"render",
+ "graph_render",
"graph",
"limits",
"profiles",
@@ -548,7 +550,6 @@ def _load_descriptor(root: Path) -> ProjectDescriptor:
for field in defaults.__dataclass_fields__
}
)
-
render = load_render_config(
root,
document.get("render"),
@@ -560,6 +561,18 @@ def _load_descriptor(root: Path) -> ProjectDescriptor:
changeset_root=changeset_root,
limits=limits,
)
+ graph_render = load_graph_render_config(
+ root,
+ document.get("graph_render"),
+ descriptor_path=descriptor_path,
+ content_roots=content_roots,
+ authority_files=authority_files,
+ cache_root=cache_root,
+ index_path=index_path,
+ changeset_root=changeset_root,
+ manual_render=render,
+ limits=limits,
+ )
profile_documents = document.get("profiles", [])
if not isinstance(profile_documents, list):
@@ -623,6 +636,7 @@ def _load_descriptor(root: Path) -> ProjectDescriptor:
changeset_root=changeset_root,
proposal_writers=tuple(sorted(proposal_writers, key=lambda writer: writer.writer_id)),
render=render,
+ graph_render=graph_render,
allowed_relations=allowed_relations,
profiles=tuple(profiles),
limits=limits,
diff --git a/src/docforge/projection_contract.py b/src/docforge/projection_contract.py
new file mode 100644
index 0000000..937d84d
--- /dev/null
+++ b/src/docforge/projection_contract.py
@@ -0,0 +1,536 @@
+"""Versioned, canonical contracts shared by independent projection renderers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from .errors import DocForgeError
+
+MANUAL_RENDER_PLAN_CONTRACT = "docforge.manual-render-plan"
+GRAPH_VIEW_PLAN_CONTRACT = "docforge.graph-view-plan"
+PROJECTION_PACKAGE_CONTRACT = "docforge.projection-package"
+PROJECTION_RECEIPT_CONTRACT = "docforge.projection-receipt"
+
+PROJECTION_SCHEMA_VERSION = 1
+MAX_PLAN_BYTES = 16_000_000
+MAX_PACKAGE_BYTES = 24_000_000
+MAX_RECEIPT_BYTES = 128_000
+MAX_PROJECTION_ARTIFACTS = 32
+MAX_GRAPH_VIEW_DEPTH = 32
+MAX_GRAPH_VIEW_NODES = 1_000
+MAX_GRAPH_VIEW_EDGES = 4_000
+MAX_GRAPH_VIEW_WORK = 1_000_000
+MAX_GRAPH_VIEW_FILTERS = 64
+MAX_GRAPH_VIEW_STRING_CHARS = 1_024
+MAX_GRAPH_VIEW_QUERY_CHARS = 10_000
+
+ProjectionKind = Literal["manual", "graph"]
+
+
+def canonical_projection_bytes(value: object) -> bytes:
+ """Return the one canonical UTF-8 representation used for projection identities."""
+
+ return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+ "utf-8"
+ )
+
+
+def projection_hash(value: object) -> str:
+ return hashlib.sha256(canonical_projection_bytes(value)).hexdigest()
+
+
+def _is_hash(value: object) -> bool:
+ return (
+ isinstance(value, str)
+ and len(value) == 64
+ and all(character in "0123456789abcdef" for character in value)
+ )
+
+
+def _bounded(document: dict[str, object], maximum: int, *, kind: str) -> None:
+ size = len(canonical_projection_bytes(document))
+ if size > maximum:
+ raise DocForgeError(
+ "projection_too_large",
+ f"{kind} exceeds its fixed serialized-size limit",
+ maximum_bytes=maximum,
+ actual_bytes=size,
+ )
+
+
+def _validated_identity(
+ document: dict[str, object],
+ *,
+ identity_field: str,
+ maximum: int,
+ kind: str,
+) -> dict[str, object]:
+ _bounded(document, maximum, kind=kind)
+ identity = document.get(identity_field)
+ if not _is_hash(identity):
+ raise DocForgeError("invalid_projection", f"{kind} identity is invalid")
+ body = dict(document)
+ body.pop(identity_field)
+ if projection_hash(body) != identity:
+ raise DocForgeError("invalid_projection", f"{kind} identity does not match its content")
+ return document
+
+
+def _reject_runtime_authority(value: object) -> None:
+ """Reject structural capabilities while treating selected content as inert data."""
+
+ forbidden_keys = {
+ "command",
+ "database",
+ "database_path",
+ "index_path",
+ "project_root",
+ "project_path",
+ "sql",
+ }
+ if isinstance(value, dict):
+ payload = cast(dict[object, object], value)
+ for key, item in payload.items():
+ if isinstance(key, str) and key in forbidden_keys:
+ raise DocForgeError(
+ "invalid_projection",
+ "Projection package contains forbidden runtime authority",
+ field=key,
+ )
+ if (
+ isinstance(key, str)
+ and (key == "path" or key.endswith("_path"))
+ and isinstance(item, str)
+ and item.startswith("/")
+ ):
+ raise DocForgeError(
+ "invalid_projection",
+ "Projection package contains an absolute runtime path",
+ field=key,
+ )
+ _reject_runtime_authority(item)
+ elif isinstance(value, list):
+ for item in cast(list[object], value):
+ _reject_runtime_authority(item)
+
+
+@dataclass(frozen=True)
+class ManualRenderPlanV1:
+ """One immutable, bounded manual plan prepared from a validated graph generation."""
+
+ document: dict[str, object]
+
+ @property
+ def plan_id(self) -> str:
+ return cast(str, self.document["plan_id"])
+
+ def as_dict(self) -> dict[str, object]:
+ return dict(self.document)
+
+ @classmethod
+ def create(cls, payload: dict[str, object]) -> ManualRenderPlanV1:
+ body = {
+ "schema_version": PROJECTION_SCHEMA_VERSION,
+ "contract": MANUAL_RENDER_PLAN_CONTRACT,
+ **payload,
+ }
+ document = {**body, "plan_id": projection_hash(body)}
+ return cls(validate_manual_render_plan(document))
+
+ @classmethod
+ def from_dict(cls, document: dict[str, object]) -> ManualRenderPlanV1:
+ return cls(validate_manual_render_plan(dict(document)))
+
+
+@dataclass(frozen=True)
+class GraphViewPlanV1:
+ """One immutable, bounded portable-graph plan."""
+
+ document: dict[str, object]
+
+ @property
+ def plan_id(self) -> str:
+ return cast(str, self.document["plan_id"])
+
+ def as_dict(self) -> dict[str, object]:
+ return dict(self.document)
+
+ @classmethod
+ def create(cls, payload: dict[str, object]) -> GraphViewPlanV1:
+ body = {
+ "schema_version": PROJECTION_SCHEMA_VERSION,
+ "contract": GRAPH_VIEW_PLAN_CONTRACT,
+ **payload,
+ }
+ document = {**body, "plan_id": projection_hash(body)}
+ return cls(validate_graph_view_plan(document))
+
+ @classmethod
+ def from_dict(cls, document: dict[str, object]) -> GraphViewPlanV1:
+ return cls(validate_graph_view_plan(dict(document)))
+
+
+@dataclass(frozen=True)
+class ProjectionPackageV1:
+ """Path-free package supplied to one capability-isolated renderer."""
+
+ document: dict[str, object]
+
+ @property
+ def package_id(self) -> str:
+ return cast(str, self.document["package_id"])
+
+ @property
+ def kind(self) -> ProjectionKind:
+ return cast(ProjectionKind, self.document["kind"])
+
+ def as_dict(self) -> dict[str, object]:
+ return dict(self.document)
+
+ @classmethod
+ def create(
+ cls,
+ *,
+ kind: ProjectionKind,
+ plan: ManualRenderPlanV1 | GraphViewPlanV1,
+ renderer: dict[str, object],
+ components: list[dict[str, object]],
+ assets: list[dict[str, object]],
+ output_policy: dict[str, object],
+ ) -> ProjectionPackageV1:
+ body: dict[str, object] = {
+ "schema_version": PROJECTION_SCHEMA_VERSION,
+ "contract": PROJECTION_PACKAGE_CONTRACT,
+ "kind": kind,
+ "plan_id": plan.plan_id,
+ "plan": plan.as_dict(),
+ "renderer": renderer,
+ "components": components,
+ "assets": assets,
+ "output_policy": output_policy,
+ }
+ document = {**body, "package_id": projection_hash(body)}
+ return cls(validate_projection_package(document))
+
+ @classmethod
+ def from_dict(cls, document: dict[str, object]) -> ProjectionPackageV1:
+ return cls(validate_projection_package(dict(document)))
+
+
+@dataclass(frozen=True)
+class ProjectionReceiptV1:
+ """Renderer evidence that contains identities and sizes, never artifact bytes."""
+
+ document: dict[str, object]
+
+ @property
+ def receipt_id(self) -> str:
+ return cast(str, self.document["receipt_id"])
+
+ def as_dict(self) -> dict[str, object]:
+ return dict(self.document)
+
+ @classmethod
+ def create(
+ cls,
+ *,
+ kind: ProjectionKind,
+ package_id: str,
+ plan_id: str,
+ renderer: dict[str, object],
+ artifacts: list[dict[str, object]],
+ diagnostics: dict[str, object],
+ timing: dict[str, object],
+ peak_memory_bytes: int | None,
+ ) -> ProjectionReceiptV1:
+ body: dict[str, object] = {
+ "schema_version": PROJECTION_SCHEMA_VERSION,
+ "contract": PROJECTION_RECEIPT_CONTRACT,
+ "kind": kind,
+ "package_id": package_id,
+ "plan_id": plan_id,
+ "renderer": renderer,
+ "artifacts": artifacts,
+ "diagnostics": diagnostics,
+ "timing": timing,
+ "peak_memory_bytes": peak_memory_bytes,
+ }
+ document = {**body, "receipt_id": projection_hash(body)}
+ return cls(validate_projection_receipt(document))
+
+ @classmethod
+ def from_dict(cls, document: dict[str, object]) -> ProjectionReceiptV1:
+ return cls(validate_projection_receipt(dict(document)))
+
+
+@dataclass(frozen=True)
+class ProjectionArtifact:
+ """One renderer-produced artifact addressed by a logical identifier."""
+
+ artifact_id: str
+ media_type: str
+ content: bytes
+
+ def evidence(self) -> dict[str, object]:
+ return {
+ "artifact_id": self.artifact_id,
+ "media_type": self.media_type,
+ "sha256": hashlib.sha256(self.content).hexdigest(),
+ "bytes": len(self.content),
+ }
+
+
+@dataclass(frozen=True)
+class ProjectionRenderResult:
+ """Artifact bytes plus the bounded renderer receipt that attests them."""
+
+ artifacts: tuple[ProjectionArtifact, ...]
+ receipt: ProjectionReceiptV1
+
+
+def _validate_project_identity(value: object) -> None:
+ if not isinstance(value, dict):
+ raise DocForgeError("invalid_projection", "Projection project identity is invalid")
+ project = cast(dict[str, object], value)
+ if set(project) != {
+ "project_id",
+ "project_root_fingerprint",
+ "adapter",
+ "revision",
+ "source_hash",
+ }:
+ raise DocForgeError("invalid_projection", "Projection project identity is invalid")
+ if not all(
+ isinstance(project.get(key), str) and bool(project[key])
+ for key in ("project_id", "project_root_fingerprint", "adapter", "revision")
+ ) or not _is_hash(project.get("source_hash")):
+ raise DocForgeError("invalid_projection", "Projection project identity is invalid")
+
+
+def validate_manual_render_plan(document: dict[str, object]) -> dict[str, object]:
+ required = {
+ "schema_version",
+ "contract",
+ "plan_id",
+ "project",
+ "view",
+ "changeset_hash",
+ "pages",
+ "navigation",
+ "search_documents",
+ "diagnostics",
+ }
+ if set(document) != required:
+ raise DocForgeError("invalid_projection", "Manual render plan fields are invalid")
+ if (
+ document.get("schema_version") != PROJECTION_SCHEMA_VERSION
+ or document.get("contract") != MANUAL_RENDER_PLAN_CONTRACT
+ ):
+ raise DocForgeError("invalid_projection", "Manual render plan version is unsupported")
+ _validate_project_identity(document.get("project"))
+ if not all(
+ isinstance(document.get(key), expected)
+ for key, expected in (
+ ("view", dict),
+ ("pages", list),
+ ("navigation", list),
+ ("search_documents", list),
+ ("diagnostics", dict),
+ )
+ ):
+ raise DocForgeError("invalid_projection", "Manual render plan structure is invalid")
+ changeset_hash = document.get("changeset_hash")
+ if changeset_hash is not None and not _is_hash(changeset_hash):
+ raise DocForgeError("invalid_projection", "Manual render plan changeset hash is invalid")
+ return _validated_identity(
+ document,
+ identity_field="plan_id",
+ maximum=MAX_PLAN_BYTES,
+ kind="Manual render plan",
+ )
+
+
+def validate_graph_view_plan(document: dict[str, object]) -> dict[str, object]:
+ required = {
+ "schema_version",
+ "contract",
+ "plan_id",
+ "project",
+ "view",
+ "bounds",
+ "policy",
+ "graph",
+ "omissions",
+ "diagnostics",
+ }
+ if set(document) != required:
+ raise DocForgeError("invalid_projection", "Graph view plan fields are invalid")
+ if (
+ document.get("schema_version") != PROJECTION_SCHEMA_VERSION
+ or document.get("contract") != GRAPH_VIEW_PLAN_CONTRACT
+ ):
+ raise DocForgeError("invalid_projection", "Graph view plan version is unsupported")
+ _validate_project_identity(document.get("project"))
+ if not all(
+ isinstance(document.get(key), expected)
+ for key, expected in (
+ ("view", dict),
+ ("bounds", dict),
+ ("policy", dict),
+ ("graph", dict),
+ ("omissions", list),
+ ("diagnostics", dict),
+ )
+ ):
+ raise DocForgeError("invalid_projection", "Graph view plan structure is invalid")
+ return _validated_identity(
+ document,
+ identity_field="plan_id",
+ maximum=MAX_PLAN_BYTES,
+ kind="Graph view plan",
+ )
+
+
+def validate_projection_package(document: dict[str, object]) -> dict[str, object]:
+ required = {
+ "schema_version",
+ "contract",
+ "package_id",
+ "kind",
+ "plan_id",
+ "plan",
+ "renderer",
+ "components",
+ "assets",
+ "output_policy",
+ }
+ if set(document) != required:
+ raise DocForgeError("invalid_projection", "Projection package fields are invalid")
+ kind = document.get("kind")
+ if (
+ document.get("schema_version") != PROJECTION_SCHEMA_VERSION
+ or document.get("contract") != PROJECTION_PACKAGE_CONTRACT
+ or kind not in {"manual", "graph"}
+ ):
+ raise DocForgeError("invalid_projection", "Projection package version or kind is invalid")
+ plan = document.get("plan")
+ if not isinstance(plan, dict):
+ raise DocForgeError("invalid_projection", "Projection package plan is invalid")
+ validated_plan = (
+ validate_manual_render_plan(cast(dict[str, object], plan))
+ if kind == "manual"
+ else validate_graph_view_plan(cast(dict[str, object], plan))
+ )
+ if document.get("plan_id") != validated_plan.get("plan_id"):
+ raise DocForgeError("invalid_projection", "Projection package plan identity is invalid")
+ if not all(
+ isinstance(document.get(key), expected)
+ for key, expected in (
+ ("renderer", dict),
+ ("components", list),
+ ("assets", list),
+ ("output_policy", dict),
+ )
+ ):
+ raise DocForgeError("invalid_projection", "Projection package structure is invalid")
+ if len(cast(list[object], document["assets"])) > MAX_PROJECTION_ARTIFACTS:
+ raise DocForgeError("projection_too_large", "Projection package has too many assets")
+ _reject_runtime_authority(document)
+ return _validated_identity(
+ document,
+ identity_field="package_id",
+ maximum=MAX_PACKAGE_BYTES,
+ kind="Projection package",
+ )
+
+
+def validate_projection_receipt(document: dict[str, object]) -> dict[str, object]:
+ required = {
+ "schema_version",
+ "contract",
+ "receipt_id",
+ "kind",
+ "package_id",
+ "plan_id",
+ "renderer",
+ "artifacts",
+ "diagnostics",
+ "timing",
+ "peak_memory_bytes",
+ }
+ if set(document) != required:
+ raise DocForgeError("invalid_projection", "Projection receipt fields are invalid")
+ if (
+ document.get("schema_version") != PROJECTION_SCHEMA_VERSION
+ or document.get("contract") != PROJECTION_RECEIPT_CONTRACT
+ or document.get("kind") not in {"manual", "graph"}
+ or not _is_hash(document.get("package_id"))
+ or not _is_hash(document.get("plan_id"))
+ ):
+ raise DocForgeError("invalid_projection", "Projection receipt identity is invalid")
+ artifacts_value = document.get("artifacts")
+ if not isinstance(artifacts_value, list):
+ raise DocForgeError("invalid_projection", "Projection receipt structure is invalid")
+ artifacts = cast(list[object], artifacts_value)
+ renderer = document.get("renderer")
+ diagnostics = document.get("diagnostics")
+ timing = document.get("timing")
+ if (
+ not isinstance(renderer, dict)
+ or not isinstance(diagnostics, dict)
+ or not isinstance(timing, dict)
+ ):
+ raise DocForgeError("invalid_projection", "Projection receipt structure is invalid")
+ renderer_document = cast(dict[str, object], renderer)
+ diagnostics_document = cast(dict[str, object], diagnostics)
+ timing_document = cast(dict[str, object], timing)
+ warnings = diagnostics_document.get("warnings")
+ if (
+ len(artifacts) > MAX_PROJECTION_ARTIFACTS
+ or set(renderer_document) != {"renderer_id", "renderer_version"}
+ or not all(
+ isinstance(renderer_document.get(field), str) and renderer_document[field]
+ for field in ("renderer_id", "renderer_version")
+ )
+ or set(diagnostics_document) != {"warnings"}
+ or not isinstance(warnings, list)
+ or len(cast(list[object], warnings)) > 10_000
+ or not all(isinstance(item, str) for item in cast(list[object], warnings))
+ or set(timing_document) != {"elapsed_ns"}
+ or type(timing_document.get("elapsed_ns")) is not int
+ or cast(int, timing_document["elapsed_ns"]) < 0
+ ):
+ raise DocForgeError("invalid_projection", "Projection receipt structure is invalid")
+ peak = document.get("peak_memory_bytes")
+ if peak is not None and (type(peak) is not int or peak < 0):
+ raise DocForgeError("invalid_projection", "Projection receipt memory value is invalid")
+ artifact_ids: set[str] = set()
+ for artifact in artifacts:
+ if not isinstance(artifact, dict):
+ raise DocForgeError("invalid_projection", "Projection receipt artifact is invalid")
+ item = cast(dict[str, object], artifact)
+ if (
+ set(item) != {"artifact_id", "media_type", "sha256", "bytes"}
+ or not isinstance(item.get("artifact_id"), str)
+ or not item["artifact_id"]
+ or "/" in cast(str, item["artifact_id"])
+ or not isinstance(item.get("media_type"), str)
+ or not item["media_type"]
+ or not _is_hash(item.get("sha256"))
+ or type(item.get("bytes")) is not int
+ or cast(int, item["bytes"]) < 0
+ ):
+ raise DocForgeError("invalid_projection", "Projection receipt artifact is invalid")
+ artifact_id = cast(str, item["artifact_id"])
+ if artifact_id in artifact_ids:
+ raise DocForgeError("invalid_projection", "Projection receipt artifacts are duplicated")
+ artifact_ids.add(artifact_id)
+ return _validated_identity(
+ document,
+ identity_field="receipt_id",
+ maximum=MAX_RECEIPT_BYTES,
+ kind="Projection receipt",
+ )
diff --git a/src/docforge/projection_fragments.py b/src/docforge/projection_fragments.py
new file mode 100644
index 0000000..b2fe3d2
--- /dev/null
+++ b/src/docforge/projection_fragments.py
@@ -0,0 +1,489 @@
+"""Bounded, path-free, disposable projection fragment caching."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, cast
+
+from ._fs_safety import (
+ atomic_replace_bytes_at,
+ open_confined_directory,
+ read_bounded_file_at,
+ require_bound_directory,
+)
+from .errors import DocForgeError
+from .projection_contract import canonical_projection_bytes, projection_hash
+
+FRAGMENT_SCHEMA_VERSION = 1
+FRAGMENT_KEY_CONTRACT = "docforge.projection-fragment-key"
+FRAGMENT_RECORD_CONTRACT = "docforge.projection-fragment-record"
+FRAGMENT_CACHE_DIRECTORY = "projection-fragments-v1"
+MAX_FRAGMENT_CONTENT_BYTES = 4_000_000
+MAX_FRAGMENT_ID_CHARS = 256
+MAX_FRAGMENT_CACHE_ENTRIES = 10_000
+MAX_FRAGMENT_CACHE_BYTES = 64_000_000
+_MAX_RECORD_OVERHEAD_BYTES = 8_192
+
+ProjectionKind = Literal["manual", "graph"]
+
+
+def _is_hash(value: object) -> bool:
+ return (
+ isinstance(value, str)
+ and len(value) == 64
+ and all(character in "0123456789abcdef" for character in value)
+ )
+
+
+def _version_string(value: object, *, field: str) -> str:
+ if (
+ not isinstance(value, str)
+ or not value
+ or value != value.strip()
+ or len(value) > MAX_FRAGMENT_ID_CHARS
+ or any(ord(character) < 32 for character in value)
+ ):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment identity is invalid",
+ field=field,
+ )
+ return value
+
+
+def fragment_semantic_hash(value: object) -> str:
+ """Hash one complete semantic input using the projection canonical JSON form."""
+
+ try:
+ return hashlib.sha256(canonical_projection_bytes(value)).hexdigest()
+ except (TypeError, ValueError) as error:
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment semantic input is not canonical JSON",
+ ) from error
+
+
+@dataclass(frozen=True)
+class FragmentKey:
+ """Versioned identity for one renderer component's complete semantics."""
+
+ projection_kind: ProjectionKind
+ renderer_id: str
+ renderer_version: str
+ component_version: str
+ semantic_input_hash: str
+ key_id: str
+
+ @classmethod
+ def create(
+ cls,
+ *,
+ projection_kind: ProjectionKind,
+ renderer_id: str,
+ renderer_version: str,
+ component_version: str,
+ semantic_input_hash: str,
+ ) -> FragmentKey:
+ body = cls._body(
+ projection_kind=projection_kind,
+ renderer_id=renderer_id,
+ renderer_version=renderer_version,
+ component_version=component_version,
+ semantic_input_hash=semantic_input_hash,
+ )
+ return cls._from_validated({**body, "key_id": projection_hash(body)})
+
+ @classmethod
+ def from_dict(cls, value: object) -> FragmentKey:
+ if not isinstance(value, dict):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment key is invalid",
+ )
+ return cls._from_validated(dict(cast(dict[str, object], value)))
+
+ @staticmethod
+ def _body(
+ *,
+ projection_kind: object,
+ renderer_id: object,
+ renderer_version: object,
+ component_version: object,
+ semantic_input_hash: object,
+ ) -> dict[str, object]:
+ if projection_kind not in {"manual", "graph"}:
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment kind is invalid",
+ )
+ if not _is_hash(semantic_input_hash):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment semantic input hash is invalid",
+ )
+ return {
+ "schema_version": FRAGMENT_SCHEMA_VERSION,
+ "contract": FRAGMENT_KEY_CONTRACT,
+ "projection_kind": projection_kind,
+ "renderer_id": _version_string(renderer_id, field="renderer_id"),
+ "renderer_version": _version_string(
+ renderer_version,
+ field="renderer_version",
+ ),
+ "component_version": _version_string(
+ component_version,
+ field="component_version",
+ ),
+ "semantic_input_hash": semantic_input_hash,
+ }
+
+ @classmethod
+ def _from_validated(cls, value: dict[str, object]) -> FragmentKey:
+ required = {
+ "schema_version",
+ "contract",
+ "projection_kind",
+ "renderer_id",
+ "renderer_version",
+ "component_version",
+ "semantic_input_hash",
+ "key_id",
+ }
+ if (
+ set(value) != required
+ or value.get("schema_version") != FRAGMENT_SCHEMA_VERSION
+ or value.get("contract") != FRAGMENT_KEY_CONTRACT
+ ):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment key contract is incompatible",
+ )
+ body = cls._body(
+ projection_kind=value.get("projection_kind"),
+ renderer_id=value.get("renderer_id"),
+ renderer_version=value.get("renderer_version"),
+ component_version=value.get("component_version"),
+ semantic_input_hash=value.get("semantic_input_hash"),
+ )
+ key_id = value.get("key_id")
+ if not _is_hash(key_id) or key_id != projection_hash(body):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment key does not match its semantics",
+ )
+ return cls(
+ projection_kind=cast(ProjectionKind, body["projection_kind"]),
+ renderer_id=cast(str, body["renderer_id"]),
+ renderer_version=cast(str, body["renderer_version"]),
+ component_version=cast(str, body["component_version"]),
+ semantic_input_hash=cast(str, body["semantic_input_hash"]),
+ key_id=cast(str, key_id),
+ )
+
+ def as_dict(self) -> dict[str, object]:
+ return {
+ "schema_version": FRAGMENT_SCHEMA_VERSION,
+ "contract": FRAGMENT_KEY_CONTRACT,
+ "projection_kind": self.projection_kind,
+ "renderer_id": self.renderer_id,
+ "renderer_version": self.renderer_version,
+ "component_version": self.component_version,
+ "semantic_input_hash": self.semantic_input_hash,
+ "key_id": self.key_id,
+ }
+
+
+@dataclass(frozen=True)
+class FragmentRecord:
+ """One path-free fragment payload with complete byte evidence."""
+
+ key: FragmentKey
+ content: bytes
+ byte_count: int
+ content_sha256: str
+ record_id: str
+
+ @classmethod
+ def create(cls, key: FragmentKey, content: bytes) -> FragmentRecord:
+ if len(content) > MAX_FRAGMENT_CONTENT_BYTES:
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment content is invalid or oversized",
+ maximum_bytes=MAX_FRAGMENT_CONTENT_BYTES,
+ )
+ body = cls._body(key, content)
+ return cls(
+ key=key,
+ content=content,
+ byte_count=len(content),
+ content_sha256=hashlib.sha256(content).hexdigest(),
+ record_id=projection_hash(body),
+ )
+
+ @classmethod
+ def from_dict(cls, value: object) -> FragmentRecord:
+ if not isinstance(value, dict):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment record is invalid",
+ )
+ document = dict(cast(dict[str, object], value))
+ required = {
+ "schema_version",
+ "contract",
+ "record_id",
+ "key",
+ "content_encoding",
+ "content",
+ "byte_count",
+ "content_sha256",
+ }
+ if (
+ set(document) != required
+ or document.get("schema_version") != FRAGMENT_SCHEMA_VERSION
+ or document.get("contract") != FRAGMENT_RECORD_CONTRACT
+ or document.get("content_encoding") != "base64"
+ ):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment record contract is incompatible",
+ )
+ encoded = document.get("content")
+ if not isinstance(encoded, str):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment content encoding is invalid",
+ )
+ try:
+ content = base64.b64decode(encoded.encode("ascii"), validate=True)
+ except (UnicodeEncodeError, ValueError) as error:
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment content encoding is invalid",
+ ) from error
+ if len(content) > MAX_FRAGMENT_CONTENT_BYTES:
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment content is oversized",
+ maximum_bytes=MAX_FRAGMENT_CONTENT_BYTES,
+ )
+ key = FragmentKey.from_dict(document.get("key"))
+ body = cls._body(key, content)
+ record_id = document.get("record_id")
+ if (
+ type(document.get("byte_count")) is not int
+ or document.get("byte_count") != len(content)
+ or document.get("content_sha256") != hashlib.sha256(content).hexdigest()
+ or not _is_hash(record_id)
+ or record_id != projection_hash(body)
+ ):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment byte evidence is invalid",
+ )
+ return cls(
+ key=key,
+ content=content,
+ byte_count=len(content),
+ content_sha256=hashlib.sha256(content).hexdigest(),
+ record_id=cast(str, record_id),
+ )
+
+ @classmethod
+ def from_bytes(cls, raw: bytes) -> FragmentRecord:
+ try:
+ value: object = json.loads(raw)
+ except (UnicodeDecodeError, json.JSONDecodeError) as error:
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment record is not valid JSON",
+ ) from error
+ record = cls.from_dict(value)
+ if record.to_bytes() != raw:
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment record is not canonically serialized",
+ )
+ return record
+
+ @staticmethod
+ def _body(key: FragmentKey, content: bytes) -> dict[str, object]:
+ return {
+ "schema_version": FRAGMENT_SCHEMA_VERSION,
+ "contract": FRAGMENT_RECORD_CONTRACT,
+ "key": key.as_dict(),
+ "content_encoding": "base64",
+ "content": base64.b64encode(content).decode("ascii"),
+ "byte_count": len(content),
+ "content_sha256": hashlib.sha256(content).hexdigest(),
+ }
+
+ def as_dict(self) -> dict[str, object]:
+ return {
+ **self._body(self.key, self.content),
+ "record_id": self.record_id,
+ }
+
+ def to_bytes(self) -> bytes:
+ return canonical_projection_bytes(self.as_dict())
+
+
+class ProjectionFragmentCache:
+ """Confined best-effort storage for immutable projection fragments."""
+
+ def __init__(
+ self,
+ project_root: Path,
+ cache_root: Path,
+ *,
+ maximum_content_bytes: int = MAX_FRAGMENT_CONTENT_BYTES,
+ ) -> None:
+ if (
+ type(maximum_content_bytes) is not int
+ or not 1 <= maximum_content_bytes <= MAX_FRAGMENT_CONTENT_BYTES
+ ):
+ raise DocForgeError(
+ "invalid_projection_fragment",
+ "Projection fragment cache byte limit is invalid",
+ maximum_bytes=MAX_FRAGMENT_CONTENT_BYTES,
+ )
+ self.project_root = project_root
+ self.cache_root = cache_root
+ self.fragment_root = cache_root / FRAGMENT_CACHE_DIRECTORY
+ self.maximum_content_bytes = maximum_content_bytes
+
+ @property
+ def maximum_record_bytes(self) -> int:
+ encoded = ((self.maximum_content_bytes + 2) // 3) * 4
+ return encoded + _MAX_RECORD_OVERHEAD_BYTES
+
+ def get(self, key: FragmentKey) -> FragmentRecord | None:
+ """Return one exact compatible fragment, treating every cache defect as a miss."""
+
+ descriptor: int | None = None
+ try:
+ descriptor = self._open(create=False)
+ raw = read_bounded_file_at(
+ descriptor,
+ f"{key.key_id}.json",
+ self.maximum_record_bytes,
+ )
+ if raw is None:
+ return None
+ record = FragmentRecord.from_bytes(raw)
+ if record.key != key or record.byte_count > self.maximum_content_bytes:
+ return None
+ require_bound_directory(self.fragment_root, descriptor)
+ return record
+ except (DocForgeError, OSError):
+ return None
+ finally:
+ if descriptor is not None:
+ os.close(descriptor)
+
+ def put(self, key: FragmentKey, content: bytes) -> FragmentRecord | None:
+ """Durably publish one fragment, returning ``None`` on disposable cache failure."""
+
+ if len(content) > self.maximum_content_bytes:
+ return None
+ try:
+ record = FragmentRecord.create(key, content)
+ except DocForgeError:
+ return None
+ raw = record.to_bytes()
+ if len(raw) > self.maximum_record_bytes:
+ return None
+ descriptor: int | None = None
+ try:
+ descriptor = self._open(create=True)
+ name = f"{key.key_id}.json"
+ try:
+ existing = read_bounded_file_at(
+ descriptor,
+ name,
+ self.maximum_record_bytes,
+ )
+ except DocForgeError as error:
+ if error.code == "path_escape":
+ return None
+ existing = None
+ if existing == raw:
+ require_bound_directory(self.fragment_root, descriptor)
+ return record
+ atomic_replace_bytes_at(
+ self.fragment_root,
+ descriptor,
+ name,
+ raw,
+ verify=lambda: require_bound_directory(self.fragment_root, descriptor),
+ )
+ return record
+ except (DocForgeError, OSError):
+ return None
+ finally:
+ if descriptor is not None:
+ os.close(descriptor)
+
+ def prune(self, keep: tuple[FragmentKey, ...]) -> bool:
+ """Remove every stale entry and prove the retained inventory is bounded."""
+
+ keep_ids = {key.key_id for key in keep}
+ if len(keep_ids) > MAX_FRAGMENT_CACHE_ENTRIES:
+ return False
+ descriptor: int | None = None
+ try:
+ descriptor = self._open(create=False)
+ retained_entries = 0
+ retained_bytes = 0
+ with os.scandir(descriptor) as entries:
+ for entry in entries:
+ name = entry.name
+ retained = (
+ len(name) == 69
+ and name.endswith(".json")
+ and name[:-5] in keep_ids
+ and all(character in "0123456789abcdef" for character in name[:-5])
+ )
+ if retained:
+ identity = entry.stat(follow_symlinks=False)
+ if not entry.is_file(follow_symlinks=False):
+ return False
+ retained_entries += 1
+ retained_bytes += identity.st_size
+ continue
+ try:
+ os.unlink(name, dir_fd=descriptor)
+ except OSError:
+ return False
+ if (
+ retained_entries > MAX_FRAGMENT_CACHE_ENTRIES
+ or retained_bytes > MAX_FRAGMENT_CACHE_BYTES
+ ):
+ return False
+ require_bound_directory(self.fragment_root, descriptor)
+ os.fsync(descriptor)
+ return True
+ except (DocForgeError, OSError):
+ return False
+ finally:
+ if descriptor is not None:
+ os.close(descriptor)
+
+ def _open(self, *, create: bool) -> int:
+ if self.cache_root == self.project_root or not self.cache_root.is_relative_to(
+ self.project_root
+ ):
+ raise DocForgeError(
+ "path_escape",
+ "Projection fragment cache is not confined to a derived project root",
+ )
+ return open_confined_directory(
+ self.project_root,
+ self.fragment_root,
+ create=create,
+ )
diff --git a/src/docforge/projection_policy.py b/src/docforge/projection_policy.py
new file mode 100644
index 0000000..5c7321d
--- /dev/null
+++ b/src/docforge/projection_policy.py
@@ -0,0 +1,234 @@
+"""Independent version-2 policy for manual, portable graph, and live projections."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from .errors import DocForgeError
+
+ManualProjectionMode = Literal["auto", "explicit", "disabled"]
+PortableGraphProjectionMode = Literal["explicit", "disabled"]
+LiveViewerProjectionMode = Literal["on-demand", "disabled"]
+
+MANUAL_PROJECTION_MODES: tuple[ManualProjectionMode, ...] = (
+ "auto",
+ "explicit",
+ "disabled",
+)
+PORTABLE_GRAPH_PROJECTION_MODES: tuple[PortableGraphProjectionMode, ...] = (
+ "explicit",
+ "disabled",
+)
+LIVE_VIEWER_PROJECTION_MODES: tuple[LiveViewerProjectionMode, ...] = (
+ "on-demand",
+ "disabled",
+)
+
+
+def _invalid_mode(field: str, value: object, allowed: tuple[str, ...]) -> DocForgeError:
+ return DocForgeError(
+ "invalid_projection_policy",
+ "Projection policy mode is unsupported",
+ projection=field,
+ mode=value,
+ allowed=list(allowed),
+ )
+
+
+def _select_mode(
+ value: object | None,
+ *,
+ field: str,
+ default: str,
+ allowed: tuple[str, ...],
+) -> str:
+ selected: object = default if value is None else value
+ if not isinstance(selected, str) or selected not in allowed:
+ raise _invalid_mode(field, selected, allowed)
+ return selected
+
+
+def _require_boolean(field: str, value: object) -> bool:
+ if type(value) is not bool:
+ raise DocForgeError(
+ "invalid_projection_policy",
+ "Projection policy availability must be Boolean",
+ field=field,
+ )
+ return value
+
+
+def _unavailable(field: str, mode: str, required: str) -> DocForgeError:
+ return DocForgeError(
+ "projection_policy_unavailable",
+ "Projection policy mode is unavailable",
+ projection=field,
+ mode=mode,
+ required=required,
+ )
+
+
+def validate_manual_projection_mode(value: object) -> ManualProjectionMode:
+ """Validate one direct manual-service policy selection."""
+
+ return cast(
+ ManualProjectionMode,
+ _select_mode(
+ value,
+ field="manual",
+ default="explicit",
+ allowed=MANUAL_PROJECTION_MODES,
+ ),
+ )
+
+
+def validate_portable_graph_projection_mode(
+ value: object,
+) -> PortableGraphProjectionMode:
+ """Validate one direct portable-graph service policy selection."""
+
+ return cast(
+ PortableGraphProjectionMode,
+ _select_mode(
+ value,
+ field="portable_graph",
+ default="explicit",
+ allowed=PORTABLE_GRAPH_PROJECTION_MODES,
+ ),
+ )
+
+
+def validate_live_viewer_projection_mode(value: object) -> LiveViewerProjectionMode:
+ """Validate one direct live-viewer service policy selection."""
+
+ return cast(
+ LiveViewerProjectionMode,
+ _select_mode(
+ value,
+ field="live_viewer",
+ default="on-demand",
+ allowed=LIVE_VIEWER_PROJECTION_MODES,
+ ),
+ )
+
+
+@dataclass(frozen=True)
+class ProjectionPolicyV2:
+ """One immutable policy for three independent projection consumers."""
+
+ manual: ManualProjectionMode
+ portable_graph: PortableGraphProjectionMode
+ live_viewer: LiveViewerProjectionMode
+
+ def __post_init__(self) -> None:
+ if self.manual not in MANUAL_PROJECTION_MODES:
+ raise _invalid_mode("manual", self.manual, MANUAL_PROJECTION_MODES)
+ if self.portable_graph not in PORTABLE_GRAPH_PROJECTION_MODES:
+ raise _invalid_mode(
+ "portable_graph",
+ self.portable_graph,
+ PORTABLE_GRAPH_PROJECTION_MODES,
+ )
+ if self.live_viewer not in LIVE_VIEWER_PROJECTION_MODES:
+ raise _invalid_mode(
+ "live_viewer",
+ self.live_viewer,
+ LIVE_VIEWER_PROJECTION_MODES,
+ )
+
+ def as_dict(self) -> dict[str, object]:
+ return {
+ "schema_version": 2,
+ "manual": self.manual,
+ "portable_graph": self.portable_graph,
+ "live_viewer": self.live_viewer,
+ }
+
+ @property
+ def policy_hash(self) -> str:
+ raw = json.dumps(
+ self.as_dict(),
+ sort_keys=True,
+ separators=(",", ":"),
+ ensure_ascii=False,
+ ).encode("utf-8")
+ return hashlib.sha256(raw).hexdigest()
+
+
+def compose_projection_policy(
+ *,
+ manual: str | None = None,
+ portable_graph: str | None = None,
+ live_viewer: str | None = None,
+ manual_configured: bool,
+ portable_graph_configured: bool,
+ application_enabled: bool,
+ live_viewer_available: bool = True,
+) -> ProjectionPolicyV2:
+ """Compose compatible defaults with explicit availability-checked selections."""
+
+ manual_available = _require_boolean("manual_configured", manual_configured)
+ graph_available = _require_boolean(
+ "portable_graph_configured",
+ portable_graph_configured,
+ )
+ application_available = _require_boolean("application_enabled", application_enabled)
+ viewer_available = _require_boolean("live_viewer_available", live_viewer_available)
+
+ default_manual = (
+ "auto"
+ if manual_available and application_available
+ else ("explicit" if manual_available else "disabled")
+ )
+ default_graph = "explicit" if graph_available else "disabled"
+ default_viewer = "on-demand" if viewer_available else "disabled"
+
+ manual_mode = cast(
+ ManualProjectionMode,
+ _select_mode(
+ manual,
+ field="manual",
+ default=default_manual,
+ allowed=MANUAL_PROJECTION_MODES,
+ ),
+ )
+ graph_mode = cast(
+ PortableGraphProjectionMode,
+ _select_mode(
+ portable_graph,
+ field="portable_graph",
+ default=default_graph,
+ allowed=PORTABLE_GRAPH_PROJECTION_MODES,
+ ),
+ )
+ viewer_mode = cast(
+ LiveViewerProjectionMode,
+ _select_mode(
+ live_viewer,
+ field="live_viewer",
+ default=default_viewer,
+ allowed=LIVE_VIEWER_PROJECTION_MODES,
+ ),
+ )
+
+ if manual_mode != "disabled" and not manual_available:
+ raise _unavailable("manual", manual_mode, "manual_render_config")
+ if manual_mode == "auto" and not application_available:
+ raise _unavailable("manual", manual_mode, "canonical_application")
+ if graph_mode == "explicit" and not graph_available:
+ raise _unavailable(
+ "portable_graph",
+ graph_mode,
+ "portable_graph_render_config",
+ )
+ if viewer_mode == "on-demand" and not viewer_available:
+ raise _unavailable("live_viewer", viewer_mode, "live_viewer_runtime")
+
+ return ProjectionPolicyV2(
+ manual=manual_mode,
+ portable_graph=graph_mode,
+ live_viewer=viewer_mode,
+ )
diff --git a/src/docforge/projection_worker.py b/src/docforge/projection_worker.py
new file mode 100644
index 0000000..dc6d48a
--- /dev/null
+++ b/src/docforge/projection_worker.py
@@ -0,0 +1,436 @@
+"""One-shot detached execution for the fixed built-in projection renderers."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import os
+import resource
+import subprocess
+import sys
+import tempfile
+from importlib.metadata import version
+from typing import cast
+
+from .errors import DocForgeError
+from .projection_contract import (
+ MAX_PACKAGE_BYTES,
+ MAX_PROJECTION_ARTIFACTS,
+ MAX_RECEIPT_BYTES,
+ ProjectionArtifact,
+ ProjectionPackageV1,
+ ProjectionReceiptV1,
+ ProjectionRenderResult,
+ canonical_projection_bytes,
+)
+
+WORKER_PROTOCOL_VERSION = 1
+MAX_WORKER_ARTIFACT_BYTES = 20_000_000
+MAX_WORKER_REQUEST_BYTES = MAX_PACKAGE_BYTES + 1
+MAX_WORKER_RESPONSE_BYTES = 4 * ((MAX_WORKER_ARTIFACT_BYTES + 2) // 3) + MAX_RECEIPT_BYTES + 256_000
+WORKER_TIMEOUT_SECONDS = 30
+
+_GENERIC_HTML_RENDERER_ID = "generic_html"
+_PORTABLE_GRAPH_RENDERER_ID = "portable_graph_html"
+_PORTABLE_GRAPH_RENDERER_VERSION = "1"
+
+
+def _generic_html_renderer_version() -> str:
+ return f"1+markdown-it-py-{version('markdown-it-py')}"
+
+
+def _worker_failure(message: str, **details: object) -> DocForgeError:
+ return DocForgeError("projection_worker_failure", message, **details)
+
+
+def _renderer_identity(package: ProjectionPackageV1) -> dict[str, object]:
+ renderer_value = package.document.get("renderer")
+ if not isinstance(renderer_value, dict):
+ raise DocForgeError("unsupported_renderer", "Projection renderer identity is invalid")
+ renderer = cast(dict[str, object], renderer_value)
+ if set(renderer) != {"renderer_id", "renderer_version"}:
+ raise DocForgeError("unsupported_renderer", "Projection renderer identity is invalid")
+ renderer_id = renderer.get("renderer_id")
+ renderer_version = renderer.get("renderer_version")
+ if not isinstance(renderer_id, str) or not isinstance(renderer_version, str):
+ raise DocForgeError("unsupported_renderer", "Projection renderer identity is invalid")
+ supported = (
+ package.kind == "manual"
+ and renderer_id == _GENERIC_HTML_RENDERER_ID
+ and renderer_version == _generic_html_renderer_version()
+ ) or (
+ package.kind == "graph"
+ and renderer_id == _PORTABLE_GRAPH_RENDERER_ID
+ and renderer_version == _PORTABLE_GRAPH_RENDERER_VERSION
+ )
+ if not supported:
+ raise DocForgeError(
+ "unsupported_renderer",
+ "Projection worker supports only the fixed built-in renderer versions",
+ )
+ return dict(renderer)
+
+
+def _output_policy(package: ProjectionPackageV1) -> tuple[tuple[str, ...], int]:
+ policy_value = package.document.get("output_policy")
+ if not isinstance(policy_value, dict):
+ raise DocForgeError("invalid_projection", "Projection output policy is invalid")
+ policy = cast(dict[str, object], policy_value)
+ if set(policy) != {"artifact_ids", "max_total_bytes"}:
+ raise DocForgeError("invalid_projection", "Projection output policy is invalid")
+ artifact_ids_value = policy.get("artifact_ids")
+ maximum = policy.get("max_total_bytes")
+ if not isinstance(artifact_ids_value, list):
+ raise DocForgeError("invalid_projection", "Projection artifact inventory is invalid")
+ artifact_ids_objects = cast(list[object], artifact_ids_value)
+ if (
+ not artifact_ids_objects
+ or len(artifact_ids_objects) > MAX_PROJECTION_ARTIFACTS
+ or not all(
+ isinstance(artifact_id, str)
+ and bool(artifact_id)
+ and "/" not in artifact_id
+ and artifact_id not in {".", ".."}
+ for artifact_id in artifact_ids_objects
+ )
+ ):
+ raise DocForgeError("invalid_projection", "Projection artifact inventory is invalid")
+ artifact_ids = tuple(cast(list[str], artifact_ids_objects))
+ if len(set(artifact_ids)) != len(artifact_ids):
+ raise DocForgeError("invalid_projection", "Projection artifact inventory is duplicated")
+ if type(maximum) is not int or maximum < 1:
+ raise DocForgeError(
+ "invalid_projection",
+ "Projection output byte allowance is invalid",
+ )
+ return artifact_ids, maximum
+
+
+def _validated_package(package: object) -> ProjectionPackageV1:
+ if not isinstance(package, ProjectionPackageV1):
+ raise TypeError("Projection worker requires ProjectionPackageV1")
+ validated = ProjectionPackageV1.from_dict(package.as_dict())
+ _renderer_identity(validated)
+ _output_policy(validated)
+ return validated
+
+
+def _validate_result(
+ package: ProjectionPackageV1,
+ result: ProjectionRenderResult,
+ *,
+ require_peak_memory: bool,
+) -> ProjectionRenderResult:
+ artifact_ids, maximum = _output_policy(package)
+ if (
+ len(result.artifacts) != len(artifact_ids)
+ or tuple(artifact.artifact_id for artifact in result.artifacts) != artifact_ids
+ ):
+ raise _worker_failure("Projection worker returned an invalid artifact inventory")
+ total_bytes = 0
+ evidence: list[dict[str, object]] = []
+ for artifact in result.artifacts:
+ if not artifact.media_type or type(artifact.content) is not bytes:
+ raise _worker_failure("Projection worker returned an invalid artifact")
+ total_bytes += len(artifact.content)
+ if total_bytes > maximum or total_bytes > MAX_WORKER_ARTIFACT_BYTES:
+ raise _worker_failure("Projection worker artifact transfer exceeded its fixed boundary")
+ evidence.append(artifact.evidence())
+
+ try:
+ receipt = ProjectionReceiptV1.from_dict(result.receipt.as_dict())
+ except DocForgeError as error:
+ raise _worker_failure("Projection worker receipt is invalid") from error
+ receipt_document = receipt.document
+ renderer = _renderer_identity(package)
+ timing_value = receipt_document.get("timing")
+ if not isinstance(timing_value, dict):
+ raise _worker_failure("Projection worker receipt timing is invalid")
+ timing = cast(dict[str, object], timing_value)
+ elapsed = timing.get("elapsed_ns")
+ peak_memory = receipt_document.get("peak_memory_bytes")
+ if (
+ receipt_document.get("kind") != package.kind
+ or receipt_document.get("package_id") != package.package_id
+ or receipt_document.get("plan_id") != package.document.get("plan_id")
+ or receipt_document.get("renderer") != renderer
+ or receipt_document.get("artifacts") != evidence
+ or type(elapsed) is not int
+ or elapsed < 0
+ or (require_peak_memory and (type(peak_memory) is not int or peak_memory <= 0))
+ ):
+ raise _worker_failure("Projection worker receipt does not attest the requested package")
+ return ProjectionRenderResult(tuple(result.artifacts), receipt)
+
+
+def _decode_canonical_line(raw: bytes, *, maximum: int, label: str) -> dict[str, object]:
+ if type(raw) is not bytes or len(raw) > maximum:
+ raise _worker_failure(f"{label} exceeded its fixed boundary", maximum_bytes=maximum)
+ if not raw or not raw.endswith(b"\n") or raw.count(b"\n") != 1:
+ raise _worker_failure(f"{label} framing is invalid")
+ payload = raw[:-1]
+ try:
+ value: object = json.loads(payload)
+ except (UnicodeDecodeError, json.JSONDecodeError) as error:
+ raise _worker_failure(f"{label} is not valid JSON") from error
+ if not isinstance(value, dict):
+ raise _worker_failure(f"{label} must be one JSON object")
+ document = cast(dict[str, object], value)
+ if canonical_projection_bytes(document) != payload:
+ raise _worker_failure(f"{label} is not canonical JSON")
+ return document
+
+
+def _encode_request(package: ProjectionPackageV1) -> bytes:
+ encoded = canonical_projection_bytes(package.as_dict()) + b"\n"
+ if len(encoded) > MAX_WORKER_REQUEST_BYTES:
+ raise DocForgeError(
+ "projection_too_large",
+ "Projection worker request exceeds its fixed boundary",
+ maximum_bytes=MAX_WORKER_REQUEST_BYTES,
+ )
+ return encoded
+
+
+def _invoke_worker(request: bytes) -> subprocess.CompletedProcess[bytes]:
+ environment = {key: os.environ[key] for key in ("SYSTEMROOT", "WINDIR") if key in os.environ}
+ environment.update(
+ {
+ "PYTHONIOENCODING": "utf-8",
+ "PYTHONUTF8": "1",
+ }
+ )
+ command = [sys.executable, "-I", "-m", "docforge._projection_worker_main"]
+ with tempfile.TemporaryFile() as output:
+ completed = subprocess.run(
+ command,
+ input=request,
+ stdout=output,
+ stderr=subprocess.DEVNULL,
+ check=False,
+ timeout=WORKER_TIMEOUT_SECONDS,
+ shell=False,
+ cwd=sys.prefix,
+ env=environment,
+ )
+ output.seek(0)
+ stdout = output.read(MAX_WORKER_RESPONSE_BYTES + 1)
+ return subprocess.CompletedProcess(
+ command,
+ completed.returncode,
+ stdout=stdout,
+ )
+
+
+def _decode_response(package: ProjectionPackageV1, raw: bytes) -> ProjectionRenderResult:
+ document = _decode_canonical_line(
+ raw,
+ maximum=MAX_WORKER_RESPONSE_BYTES,
+ label="Projection worker response",
+ )
+ if (
+ set(document) != {"schema_version", "artifacts", "receipt"}
+ or document.get("schema_version") != WORKER_PROTOCOL_VERSION
+ ):
+ raise _worker_failure("Projection worker response contract is invalid")
+ artifact_values = document.get("artifacts")
+ receipt_value = document.get("receipt")
+ if not isinstance(artifact_values, list) or not isinstance(receipt_value, dict):
+ raise _worker_failure("Projection worker response structure is invalid")
+ artifacts: list[ProjectionArtifact] = []
+ total_bytes = 0
+ for value in cast(list[object], artifact_values):
+ if not isinstance(value, dict):
+ raise _worker_failure("Projection worker artifact envelope is invalid")
+ artifact = cast(dict[str, object], value)
+ if set(artifact) != {"artifact_id", "media_type", "content_base64"}:
+ raise _worker_failure("Projection worker artifact envelope is invalid")
+ artifact_id = artifact.get("artifact_id")
+ media_type = artifact.get("media_type")
+ encoded = artifact.get("content_base64")
+ if (
+ not isinstance(artifact_id, str)
+ or not isinstance(media_type, str)
+ or not isinstance(encoded, str)
+ ):
+ raise _worker_failure("Projection worker artifact envelope is invalid")
+ try:
+ content = base64.b64decode(encoded.encode("ascii"), validate=True)
+ except (UnicodeEncodeError, binascii.Error, ValueError) as error:
+ raise _worker_failure("Projection worker artifact encoding is invalid") from error
+ total_bytes += len(content)
+ if total_bytes > MAX_WORKER_ARTIFACT_BYTES:
+ raise _worker_failure("Projection worker artifact transfer exceeded its fixed boundary")
+ artifacts.append(ProjectionArtifact(artifact_id, media_type, content))
+ try:
+ receipt = ProjectionReceiptV1.from_dict(cast(dict[str, object], receipt_value))
+ except DocForgeError as error:
+ raise _worker_failure("Projection worker receipt is invalid") from error
+ return _validate_result(
+ package,
+ ProjectionRenderResult(tuple(artifacts), receipt),
+ require_peak_memory=True,
+ )
+
+
+def render_projection_in_worker(package: ProjectionPackageV1) -> ProjectionRenderResult:
+ """Render one validated path-free package in a fixed one-shot child process."""
+
+ validated = _validated_package(package)
+ request = _encode_request(validated)
+ try:
+ completed = _invoke_worker(request)
+ except subprocess.TimeoutExpired as error:
+ raise DocForgeError(
+ "projection_worker_timeout",
+ "Detached projection worker exceeded its fixed timeout",
+ timeout_seconds=WORKER_TIMEOUT_SECONDS,
+ ) from error
+ except OSError as error:
+ raise _worker_failure("Detached projection worker could not be launched") from error
+ if completed.returncode != 0:
+ if completed.returncode == 3 and completed.stdout:
+ try:
+ failure = _decode_canonical_line(
+ completed.stdout,
+ maximum=MAX_RECEIPT_BYTES,
+ label="Projection worker error response",
+ )
+ error = failure.get("error")
+ error_document = cast(dict[str, object], error) if isinstance(error, dict) else None
+ if (
+ set(failure) == {"schema_version", "error"}
+ and failure.get("schema_version") == WORKER_PROTOCOL_VERSION
+ and error_document is not None
+ and set(error_document) == {"code", "message", "details"}
+ and isinstance(error_document.get("code"), str)
+ and bool(error_document["code"])
+ and isinstance(error_document.get("message"), str)
+ and bool(error_document["message"])
+ and isinstance(error_document.get("details"), dict)
+ ):
+ raise DocForgeError(
+ cast(str, error_document["code"]),
+ cast(str, error_document["message"]),
+ **cast(dict[str, object], error_document["details"]),
+ )
+ except DocForgeError as error:
+ if error.code != "projection_worker_failure":
+ raise
+ if completed.returncode < 0:
+ raise _worker_failure(
+ "Detached projection worker terminated by signal",
+ signal=-completed.returncode,
+ )
+ raise _worker_failure(
+ "Detached projection worker exited unsuccessfully",
+ exit_code=completed.returncode,
+ )
+ if type(completed.stdout) is not bytes:
+ raise _worker_failure("Detached projection worker returned invalid output")
+ return _decode_response(validated, completed.stdout)
+
+
+def _render_package(package: ProjectionPackageV1) -> ProjectionRenderResult:
+ renderer = _renderer_identity(package)
+ if renderer["renderer_id"] == _GENERIC_HTML_RENDERER_ID:
+ from docforge_renderers.manual import ManualHtmlRenderer
+
+ result = ManualHtmlRenderer(cast(str, renderer["renderer_version"])).render(package)
+ else:
+ from docforge_renderers.graph import PortableGraphHtmlRenderer
+
+ result = PortableGraphHtmlRenderer().render(package)
+ return _validate_result(package, result, require_peak_memory=False)
+
+
+def _peak_memory_bytes() -> int:
+ peak = int(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss)
+ return max(1, peak if sys.platform == "darwin" else peak * 1024)
+
+
+def _child_response(package: ProjectionPackageV1) -> bytes:
+ result = _render_package(package)
+ original = result.receipt.document
+ receipt = ProjectionReceiptV1.create(
+ kind=package.kind,
+ package_id=package.package_id,
+ plan_id=cast(str, package.document["plan_id"]),
+ renderer=cast(dict[str, object], original["renderer"]),
+ artifacts=[artifact.evidence() for artifact in result.artifacts],
+ diagnostics=cast(dict[str, object], original["diagnostics"]),
+ timing=cast(dict[str, object], original["timing"]),
+ peak_memory_bytes=_peak_memory_bytes(),
+ )
+ validated = _validate_result(
+ package,
+ ProjectionRenderResult(result.artifacts, receipt),
+ require_peak_memory=True,
+ )
+ document: dict[str, object] = {
+ "schema_version": WORKER_PROTOCOL_VERSION,
+ "artifacts": [
+ {
+ "artifact_id": artifact.artifact_id,
+ "media_type": artifact.media_type,
+ "content_base64": base64.b64encode(artifact.content).decode("ascii"),
+ }
+ for artifact in validated.artifacts
+ ],
+ "receipt": validated.receipt.as_dict(),
+ }
+ encoded = canonical_projection_bytes(document) + b"\n"
+ if len(encoded) > MAX_WORKER_RESPONSE_BYTES:
+ raise _worker_failure(
+ "Projection worker response exceeded its fixed boundary",
+ maximum_bytes=MAX_WORKER_RESPONSE_BYTES,
+ )
+ return encoded
+
+
+def _read_child_request() -> ProjectionPackageV1:
+ raw = sys.stdin.buffer.read(MAX_WORKER_REQUEST_BYTES + 1)
+ document = _decode_canonical_line(
+ raw,
+ maximum=MAX_WORKER_REQUEST_BYTES,
+ label="Projection worker request",
+ )
+ return _validated_package(ProjectionPackageV1.from_dict(document))
+
+
+def main(argv: list[str] | None = None) -> int:
+ """Run the closed one-request child protocol."""
+
+ arguments = sys.argv[1:] if argv is None else argv
+ if arguments:
+ return 2
+ try:
+ package = _read_child_request()
+ except Exception:
+ return 2
+ try:
+ response = _child_response(package)
+ sys.stdout.buffer.write(response)
+ sys.stdout.buffer.flush()
+ except DocForgeError as error:
+ response = (
+ canonical_projection_bytes(
+ {
+ "schema_version": WORKER_PROTOCOL_VERSION,
+ "error": error.as_dict(),
+ }
+ )
+ + b"\n"
+ )
+ if len(response) <= MAX_RECEIPT_BYTES:
+ sys.stdout.buffer.write(response)
+ sys.stdout.buffer.flush()
+ return 3
+ except Exception:
+ return 2
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/src/docforge/py.typed b/src/docforge/py.typed
new file mode 100644
index 0000000..e4798ff
--- /dev/null
+++ b/src/docforge/py.typed
@@ -0,0 +1 @@
+# PEP 561 marker for the typed DocForge public package.
diff --git a/src/docforge/render_contract.py b/src/docforge/render_contract.py
index f24ee9b..430dc26 100644
--- a/src/docforge/render_contract.py
+++ b/src/docforge/render_contract.py
@@ -1,31 +1,30 @@
-"""Deterministic built-in renderer contract and safe template primitives."""
+"""Compatibility shim over the versioned manual projection boundary."""
from __future__ import annotations
import hashlib
import html
import json
-import re
from dataclasses import dataclass
from importlib.metadata import version
from pathlib import Path
-from typing import Protocol
-
-from markdown_it import MarkdownIt
+from typing import Protocol, cast
from .errors import DocForgeError
-from .models import Edge, Node, ProjectSnapshot, RenderView
-
-_TEMPLATE_TOKEN = re.compile(r"{{\s*([a-z_][a-z0-9_]*)\s*}}")
-_ALLOWED_TOKENS = frozenset(
- {
- "docforge_content",
- "docforge_project_id",
- "docforge_render_identity",
- "docforge_title",
- "docforge_view_id",
- }
+from .manual_projection import build_manual_projection_package, build_manual_render_plan
+from .models import ProjectSnapshot, RenderView
+from .projection_contract import (
+ ManualRenderPlanV1,
+ ProjectionPackageV1,
+ ProjectionRenderResult,
)
+from .projection_fragments import (
+ FragmentKey,
+ FragmentRecord,
+ ProjectionFragmentCache,
+ fragment_semantic_hash,
+)
+from .projection_worker import render_projection_in_worker
@dataclass(frozen=True)
@@ -36,6 +35,7 @@ class PreparedRender:
renderer: str
renderer_version: str
template_hash: str
+ projection_receipt: dict[str, object] | None = None
class Renderer(Protocol):
@@ -55,16 +55,18 @@ class Renderer(Protocol):
class GenericHtmlRenderer:
- """Render validated nodes through escaped CommonMark and a strict token template."""
+ """Preserve the public v1 renderer API over the plan-only manual renderer."""
renderer_id = "generic_html"
contract_version = "1"
- def __init__(self) -> None:
- self.markdown = MarkdownIt("commonmark", {"html": False, "typographer": False})
+ page_component_version = "manual.page@1"
+
+ def __init__(self, *, incremental: bool = True) -> None:
self.renderer_version = (
f"{self.contract_version}+markdown-it-py-{version('markdown-it-py')}"
)
+ self.incremental = incremental
def prepare(
self,
@@ -74,22 +76,6 @@ class GenericHtmlRenderer:
*,
changeset_hash: str | None,
) -> PreparedRender:
- try:
- template = template_bytes.decode("utf-8")
- except UnicodeDecodeError as error:
- raise DocForgeError("invalid_template", "Render template is not valid UTF-8") from error
- tokens = _TEMPLATE_TOKEN.findall(template)
- unknown = sorted(set(tokens) - _ALLOWED_TOKENS)
- remainder = _TEMPLATE_TOKEN.sub("", template)
- if unknown or "{{" in remainder or "}}" in remainder:
- raise DocForgeError(
- "invalid_template", "Render template contains unsupported tokens", tokens=unknown
- )
- if tokens.count("docforge_content") != 1:
- raise DocForgeError(
- "invalid_template", "Render template must contain docforge_content exactly once"
- )
-
selected = tuple(
node for node in snapshot.nodes if not view.families or node.family in view.families
)
@@ -128,16 +114,31 @@ class GenericHtmlRenderer:
render_identity = hashlib.sha256(
json.dumps(identity_payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
).hexdigest()
- content = self._content(selected, selected_edges)
- replacements = {
- "docforge_content": content,
- "docforge_project_id": html.escape(snapshot.descriptor.project_id, quote=True),
- "docforge_render_identity": render_identity,
- "docforge_title": html.escape(view.title, quote=True),
- "docforge_view_id": html.escape(view.view_id, quote=True),
- }
- rendered = _TEMPLATE_TOKEN.sub(lambda match: replacements[match.group(1)], template)
- output = rendered.rstrip().encode("utf-8") + b"\n"
+ plan = build_manual_render_plan(snapshot, view, changeset_hash=changeset_hash)
+ full_package = build_manual_projection_package(
+ plan,
+ template_bytes,
+ renderer_id=self.renderer_id,
+ renderer_version=self.renderer_version,
+ max_output_bytes=snapshot.descriptor.limits.max_render_bytes,
+ render_identity=render_identity,
+ )
+ if self.incremental:
+ result = self._incremental_result(
+ snapshot,
+ plan,
+ template_bytes,
+ full_package=full_package,
+ render_identity=render_identity,
+ )
+ else:
+ result = render_projection_in_worker(full_package)
+ if len(result.artifacts) != 1:
+ raise DocForgeError(
+ "invalid_projection",
+ "Manual renderer returned an unsupported artifact set",
+ )
+ output = result.artifacts[0].content
return PreparedRender(
render_identity=render_identity,
output_hash=hashlib.sha256(output).hexdigest(),
@@ -145,45 +146,114 @@ class GenericHtmlRenderer:
renderer=self.renderer_id,
renderer_version=self.renderer_version,
template_hash=template_hash,
+ projection_receipt=result.receipt.as_dict(),
)
- def _content(self, nodes: tuple[Node, ...], edges: tuple[Edge, ...]) -> str:
- navigation = ['
")
- sections = [*navigation]
- edge_map: dict[str, list[Edge]] = {}
- for edge in edges:
- edge_map.setdefault(edge.source_id, []).append(edge)
- for node in nodes:
- sections.extend(
- [
- f'
',
- f"{html.escape(node.title)}
",
- '',
- f"- ID
- {html.escape(node.node_id)}
",
- f"- Family
- {html.escape(node.family)}
",
- f"- Status
- {html.escape(node.status)}
",
- f"- Authority
- {html.escape(node.authority)}
",
- "
",
- f'{html.escape(node.summary)}
',
- self.markdown.render(node.content).rstrip(),
- ]
+ record = cache.get(key)
+ if record is None:
+ missing.append((len(records), key))
+ records.append(record)
+ if not records:
+ return render_projection_in_worker(full_package)
+ full_result: ProjectionRenderResult | None = None
+ new_records: list[FragmentRecord] = []
+ if missing:
+ full_result = render_projection_in_worker(full_package)
+ fragments = self._extract_page_fragments(
+ pages,
+ full_result.artifacts[0].content,
)
- relationships = edge_map.get(node.node_id, [])
- if relationships:
- sections.append('')
- for edge in relationships:
- sections.append(
- f"- {html.escape(edge.relation)}: {html.escape(edge.target_id)}
"
- )
- sections.append("
")
- sections.append("")
- return "\n".join(sections)
+ try:
+ for position, key in missing:
+ record = FragmentRecord.create(key, fragments[position])
+ records[position] = record
+ new_records.append(record)
+ except DocForgeError:
+ return full_result
+ complete_records = [record for record in records if record is not None]
+ if len(complete_records) != len(records):
+ return full_result or render_projection_in_worker(full_package)
+ try:
+ incremental_package = build_manual_projection_package(
+ plan,
+ template_bytes,
+ fragment_records=[record.as_dict() for record in complete_records],
+ renderer_id=self.renderer_id,
+ renderer_version=self.renderer_version,
+ max_output_bytes=snapshot.descriptor.limits.max_render_bytes,
+ render_identity=render_identity,
+ )
+ incremental_result = render_projection_in_worker(incremental_package)
+ except DocForgeError:
+ cache.prune(())
+ return full_result or render_projection_in_worker(full_package)
+ if full_result is None:
+ cache.prune(tuple(record.key for record in complete_records))
+ return incremental_result
+ if tuple(
+ (artifact.artifact_id, artifact.media_type, artifact.content)
+ for artifact in incremental_result.artifacts
+ ) != tuple(
+ (artifact.artifact_id, artifact.media_type, artifact.content)
+ for artifact in full_result.artifacts
+ ):
+ cache.prune(())
+ return full_result
+ for record in new_records:
+ cache.put(record.key, record.content)
+ cache.prune(tuple(record.key for record in complete_records))
+ return incremental_result
+
+ @staticmethod
+ def _extract_page_fragments(
+ pages: list[object],
+ output: bytes,
+ ) -> list[bytes]:
+ """Extract exact deterministic page sections from one trusted full artifact."""
+
+ fragments: list[bytes] = []
+ cursor = 0
+ closing = b""
+ for value in pages:
+ page = cast(dict[str, object], value)
+ node_id = cast(str, page["node_id"])
+ marker = f'
'.encode()
+ start = output.find(marker, cursor)
+ end = output.find(closing, start + len(marker)) if start >= 0 else -1
+ if start < 0 or end < 0:
+ raise DocForgeError(
+ "invalid_projection",
+ "Full manual artifact does not contain its planned page fragments",
+ )
+ end += len(closing)
+ fragments.append(output[start:end])
+ cursor = end
+ return fragments
_RENDERERS: dict[str, type[GenericHtmlRenderer]] = {
@@ -191,13 +261,13 @@ _RENDERERS: dict[str, type[GenericHtmlRenderer]] = {
}
-def renderer_for(view: RenderView) -> Renderer:
+def renderer_for(view: RenderView, *, incremental: bool = True) -> Renderer:
factory = _RENDERERS.get(view.renderer)
if factory is None:
raise DocForgeError(
"unsupported_renderer", "View does not name a supported built-in renderer"
)
- return factory()
+ return factory(incremental=incremental)
def relative_output(snapshot: ProjectSnapshot, path: Path) -> str:
diff --git a/src/docforge/rendering.py b/src/docforge/rendering.py
index 79e4116..86738d3 100644
--- a/src/docforge/rendering.py
+++ b/src/docforge/rendering.py
@@ -26,6 +26,8 @@ from .models import (
RenderView,
)
from .project import project_root_fingerprint
+from .projection_contract import ProjectionReceiptV1
+from .projection_policy import ManualProjectionMode, validate_manual_projection_mode
from .render_contract import PreparedRender, relative_output, renderer_for
from .telemetry import increment, stage
@@ -36,9 +38,26 @@ MAX_RENDER_RECEIPT_BYTES = 64_000
class RenderService:
"""Render only declared views through fixed built-in renderer implementations."""
- def __init__(self, project: ProjectService, changesets: ChangesetStore | None = None) -> None:
+ def __init__(
+ self,
+ project: ProjectService,
+ changesets: ChangesetStore | None = None,
+ *,
+ manual_policy: ManualProjectionMode = "explicit",
+ ) -> None:
self.project = project
self.changesets = changesets or ChangesetStore(project)
+ self.manual_policy = validate_manual_projection_mode(manual_policy)
+
+ def _require_rendering(self, operation: str) -> None:
+ if self.manual_policy == "disabled":
+ raise DocForgeError(
+ "projection_policy_forbids_operation",
+ "Manual projection policy disables rendering work",
+ projection="manual",
+ mode=self.manual_policy,
+ operation=operation,
+ )
def status(self, view_id: str | None = None) -> dict[str, object]:
"""Report publication state from bounded receipts without rendering canonical content."""
@@ -86,6 +105,7 @@ class RenderService:
def deep_status(self, view_id: str | None = None) -> dict[str, object]:
"""Recompute render output as the explicit side-effect-free equivalence oracle."""
+ self._require_rendering("deep_status")
snapshot = self.project.load()
config = snapshot.descriptor.render
if config is None:
@@ -107,7 +127,12 @@ class RenderService:
snapshot.descriptor.root,
view.output_path,
)
- prepared, _ = self._prepare(snapshot, view, changeset_hash=None)
+ prepared, _ = self._prepare(
+ snapshot,
+ view,
+ changeset_hash=None,
+ incremental=False,
+ )
state = "missing"
actual_hash: str | None = None
output = view.output_path
@@ -151,6 +176,7 @@ class RenderService:
)
def render(self, view_id: str) -> dict[str, object]:
+ self._require_rendering("render")
with self._lock():
snapshot = self.project.load()
config = self._config(snapshot)
@@ -373,6 +399,8 @@ class RenderService:
"template_file": final_template_file,
"output_file": final_output_file,
}
+ if prepared.projection_receipt is not None:
+ payload["projection_receipt"] = prepared.projection_receipt
raw = json.dumps(payload, sort_keys=True, indent=2).encode("utf-8") + b"\n"
if len(raw) > MAX_RENDER_RECEIPT_BYTES:
raise DocForgeError(
@@ -572,8 +600,10 @@ class RenderService:
renderer = renderer_for(view)
template_file = receipt.get("template_file")
output_file = receipt.get("output_file")
+ fields = set(receipt)
+ projection_receipt = receipt.get("projection_receipt")
return (
- set(receipt) == required
+ fields in (required, required | {"projection_receipt"})
and receipt.get("schema_version") == RENDER_RECEIPT_SCHEMA_VERSION
and receipt.get("project_id") == descriptor.project_id
and receipt.get("project_root_fingerprint") == project_root_fingerprint(descriptor.root)
@@ -602,6 +632,50 @@ class RenderService:
descriptor.limits.max_render_bytes,
)
and cast(dict[str, object], output_file)["size"] == receipt.get("output_bytes")
+ and (
+ projection_receipt is None
+ or self._valid_projection_receipt(
+ projection_receipt,
+ renderer_id=renderer.renderer_id,
+ renderer_version=renderer.renderer_version,
+ output_hash=cast(str, receipt["output_hash"]),
+ output_bytes=cast(int, receipt["output_bytes"]),
+ )
+ )
+ )
+
+ @staticmethod
+ def _valid_projection_receipt(
+ value: object,
+ *,
+ renderer_id: str,
+ renderer_version: str,
+ output_hash: str,
+ output_bytes: int,
+ ) -> bool:
+ if not isinstance(value, dict):
+ return False
+ try:
+ receipt = ProjectionReceiptV1.from_dict(cast(dict[str, object], value))
+ except DocForgeError:
+ return False
+ document = receipt.document
+ return (
+ document.get("kind") == "manual"
+ and document.get("renderer")
+ == {
+ "renderer_id": renderer_id,
+ "renderer_version": renderer_version,
+ }
+ and document.get("artifacts")
+ == [
+ {
+ "artifact_id": "manual.html",
+ "media_type": "text/html; charset=utf-8",
+ "sha256": output_hash,
+ "bytes": output_bytes,
+ }
+ ]
)
@staticmethod
@@ -663,6 +737,7 @@ class RenderService:
"reason": reason,
"verification": "receipt",
"receipt_schema_version": payload.get("schema_version"),
+ "projection_receipt": payload.get("projection_receipt"),
}
def _current_state(self) -> ProjectState | None:
@@ -687,6 +762,7 @@ class RenderService:
}
def preview(self, changeset_id: str, view_id: str) -> dict[str, object]:
+ self._require_rendering("preview")
with self._lock():
snapshot, changeset_hash = self.changesets.projected_snapshot(changeset_id)
config = self._config(snapshot)
@@ -731,11 +807,12 @@ class RenderService:
view: RenderView,
*,
changeset_hash: str | None,
+ incremental: bool = True,
) -> tuple[PreparedRender, bytes]:
increment("render_prepare_calls")
template = self._template_bytes(snapshot, view)
with stage("render.prepare"):
- prepared = renderer_for(view).prepare(
+ prepared = renderer_for(view, incremental=incremental).prepare(
snapshot,
view,
template,
@@ -850,6 +927,7 @@ class RenderService:
"expected_output_hash": prepared.output_hash,
"actual_output_hash": actual_hash,
"template_hash": prepared.template_hash,
+ "projection_receipt": prepared.projection_receipt,
"path": relative_output(snapshot, view.output_path),
"state": state,
}
diff --git a/src/docforge/telemetry.py b/src/docforge/telemetry.py
index 4c9c6d8..1571c24 100644
--- a/src/docforge/telemetry.py
+++ b/src/docforge/telemetry.py
@@ -79,6 +79,7 @@ OPERATION_NAMES = frozenset(
"test",
"benchmark.m1",
"benchmark.m2",
+ "benchmark.m3",
"mcp.invoke",
"mcp.bootstrap",
"mcp.sync",
@@ -96,6 +97,8 @@ OPERATION_NAMES = frozenset(
"mcp.generation_diff",
"mcp.validate_project",
"mcp.render_status",
+ "mcp.graph_plan",
+ "mcp.graph_render_status",
"mcp.visualize",
"mcp.visualization_status",
"mcp.stop_visualization",
@@ -117,6 +120,9 @@ OPERATION_NAMES = frozenset(
"cli.impact",
"cli.context",
"cli.generation-diff",
+ "cli.graph-plan",
+ "cli.graph-render",
+ "cli.graph-render-status",
"cli.configure",
"cli.doctor",
"cli.render",
diff --git a/src/docforge/viewer_manager.py b/src/docforge/viewer_manager.py
index cd8ca88..44f0d63 100644
--- a/src/docforge/viewer_manager.py
+++ b/src/docforge/viewer_manager.py
@@ -28,6 +28,10 @@ from .errors import DocForgeError
from .index import ProjectIndex
from .models import IncrementalStateProject
from .project import project_root_fingerprint
+from .projection_policy import (
+ LiveViewerProjectionMode,
+ validate_live_viewer_projection_mode,
+)
from .telemetry import increment, stage
from .visualization import VISUALIZATION_TEMPLATE, VisualizationIndexSnapshot
@@ -623,9 +627,16 @@ class ViewerManager:
class ViewerManagerClient:
"""Project-bound MCP-side client for the separately supervised manager service."""
- def __init__(self, index: ProjectIndex, *, state_path: Path | None = None) -> None:
+ def __init__(
+ self,
+ index: ProjectIndex,
+ *,
+ state_path: Path | None = None,
+ live_viewer_policy: LiveViewerProjectionMode = "on-demand",
+ ) -> None:
self.index = index
self.state_path = state_path or default_state_path()
+ self.live_viewer_policy = validate_live_viewer_projection_mode(live_viewer_policy)
def start(
self,
@@ -634,6 +645,14 @@ class ViewerManagerClient:
query: str | None = None,
depth: int = 1,
) -> dict[str, object]:
+ if self.live_viewer_policy == "disabled":
+ raise DocForgeError(
+ "projection_policy_forbids_operation",
+ "Live viewer projection policy disables viewer startup",
+ projection="live_viewer",
+ mode=self.live_viewer_policy,
+ operation="start",
+ )
if node_id is not None and query is not None:
raise DocForgeError(
"invalid_visualization_target",
diff --git a/src/docforge/visualization.py b/src/docforge/visualization.py
index 621cb83..9dfcb7e 100644
--- a/src/docforge/visualization.py
+++ b/src/docforge/visualization.py
@@ -506,11 +506,11 @@ class VisualizationIndexSnapshot:
)
def source(self, node_id: str) -> dict[str, object]:
- """Return one node's bounded, project-confined UTF-8 source file."""
+ """Return bounded source evidence stored in the pinned index generation."""
with self._connection() as connection:
row = connection.execute(
- "SELECT node_id, source_path, source_anchor FROM nodes WHERE node_id = ?",
+ "SELECT node_id, source_path, source_anchor, content FROM nodes WHERE node_id = ?",
(node_id,),
).fetchone()
if row is None:
@@ -518,7 +518,8 @@ class VisualizationIndexSnapshot:
"""
SELECT logic.logic_id AS node_id,
owner.source_path AS source_path,
- logic.source_anchor AS source_anchor
+ logic.source_anchor AS source_anchor,
+ owner.content AS content
FROM logic_nodes AS logic
JOIN nodes AS owner ON owner.node_id = logic.owner_node_id
WHERE logic.logic_id = ?
@@ -533,51 +534,26 @@ class VisualizationIndexSnapshot:
"No node has the requested stable ID",
node_id=node_id,
)
- relative = Path(row["source_path"])
- if relative.is_absolute() or ".." in relative.parts or not relative.parts:
- raise DocForgeError("path_escape", "Node source path is unsafe", node_id=node_id)
- source = self.project_root / relative
- try:
- resolved = source.resolve(strict=True)
- except OSError as error:
+ content = row["content"]
+ if not isinstance(content, str):
raise DocForgeError(
- "missing_source",
- "Node source file is unavailable",
- node_id=node_id,
- ) from error
- if (
- source.is_symlink()
- or resolved != source
- or not source.is_relative_to(self.project_root)
- or not source.is_file()
- ):
- raise DocForgeError("path_escape", "Node source file is unsafe", node_id=node_id)
- if source.stat().st_size > self.max_source_bytes:
- raise DocForgeError(
- "source_too_large",
- "Node source exceeds the configured source limit",
+ "invalid_index",
+ "Pinned source evidence is invalid",
node_id=node_id,
)
- raw = source.read_bytes()
+ raw = content.encode("utf-8")
if len(raw) > self.max_source_bytes:
raise DocForgeError(
"source_too_large",
- "Node source exceeds the configured source limit",
+ "Pinned source evidence exceeds the configured source limit",
node_id=node_id,
)
- try:
- content = raw.decode("utf-8")
- except UnicodeDecodeError as error:
- raise DocForgeError(
- "invalid_source",
- "Node source is not UTF-8",
- node_id=node_id,
- ) from error
return self._result(
node_id=node_id,
source_path=row["source_path"],
source_anchor=row["source_anchor"],
content=content,
+ source_provenance="index_snapshot",
snapshot=True,
)
diff --git a/src/docforge_renderers/__init__.py b/src/docforge_renderers/__init__.py
new file mode 100644
index 0000000..94c4706
--- /dev/null
+++ b/src/docforge_renderers/__init__.py
@@ -0,0 +1 @@
+"""Capability-isolated renderer implementations for DocForge projection packages."""
diff --git a/src/docforge_renderers/graph.py b/src/docforge_renderers/graph.py
new file mode 100644
index 0000000..a36528b
--- /dev/null
+++ b/src/docforge_renderers/graph.py
@@ -0,0 +1,321 @@
+"""Deterministic self-contained renderer for one portable graph package."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import html
+import json
+from time import perf_counter_ns
+from typing import cast
+
+from docforge.errors import DocForgeError
+from docforge.projection_contract import (
+ ProjectionArtifact,
+ ProjectionPackageV1,
+ ProjectionReceiptV1,
+ ProjectionRenderResult,
+)
+
+PORTABLE_GRAPH_CSS = """
+:root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+* { box-sizing: border-box; }
+body { margin: 0; background: Canvas; color: CanvasText; }
+.skip { position: absolute; left: -10000px; top: auto; }
+.skip:focus { left: 1rem; top: 1rem; z-index: 2; padding: .5rem; background: Canvas; }
+header, main { width: min(96%, 1100px); margin: 0 auto; }
+header { padding: 1rem 0; }
+.controls { display: flex; flex-wrap: wrap; gap: .75rem; align-items: end; }
+label { display: grid; gap: .25rem; font-weight: 600; }
+input, select, button { font: inherit; min-height: 2.75rem; padding: .45rem .65rem; }
+button { cursor: pointer; }
+button:focus-visible, input:focus-visible, select:focus-visible { outline: .2rem solid Highlight; }
+.summary { margin: 1rem 0; }
+.layout { display: grid; grid-template-columns: minmax(16rem, 1fr) minmax(20rem, 2fr); gap: 1rem; }
+.panel { border: 1px solid GrayText; border-radius: .5rem; padding: 1rem; overflow: auto; }
+html[data-enhanced="true"] main[data-mode="nodes"] .layout,
+html[data-enhanced="true"] main[data-mode="flow"] .layout { grid-template-columns: 1fr; }
+html[data-enhanced="true"] main[data-mode="nodes"] [data-panel="relationships"] { display: none; }
+html[data-enhanced="true"] main[data-mode="flow"] [data-panel="nodes"] { display: none; }
+.node-list { list-style: none; padding: 0; margin: 0; display: grid; gap: .5rem; }
+.node-list button {
+ width: 100%; text-align: left; border: 1px solid GrayText; border-radius: .35rem;
+}
+.node-list button[aria-current="true"] { border-width: .2rem; }
+table { border-collapse: collapse; width: 100%; }
+th, td { text-align: left; border-bottom: 1px solid GrayText; padding: .5rem; vertical-align: top; }
+caption { text-align: left; font-weight: 700; margin-bottom: .5rem; }
+.muted { color: CanvasText; }
+dialog {
+ max-width: min(42rem, calc(100% - 2rem));
+ border: 1px solid GrayText; border-radius: .5rem;
+}
+dialog::backdrop { background: rgb(0 0 0 / 55%); }
+@media (max-width: 48rem) { .layout { grid-template-columns: 1fr; } }
+@media (prefers-reduced-motion: reduce) {
+ *, *::before, *::after { scroll-behavior: auto !important; }
+}
+@media (forced-colors: active) {
+ .panel, .node-list button, dialog { border: 2px solid CanvasText; }
+}
+""".strip()
+
+PORTABLE_GRAPH_JAVASCRIPT = r"""
+(() => {
+ "use strict";
+ const plan = JSON.parse(document.getElementById("docforge-graph-plan").textContent);
+ const nodes = plan.graph.nodes;
+ const edges = plan.graph.edges;
+ const list = document.getElementById("node-list");
+ const rows = document.getElementById("edge-rows");
+ const filter = document.getElementById("filter");
+ const mode = document.getElementById("mode");
+ const main = document.getElementById("main");
+ const status = document.getElementById("status");
+ const dialog = document.getElementById("node-dialog");
+ const detail = document.getElementById("node-detail");
+ const close = document.getElementById("close-dialog");
+ let opener = null;
+ document.documentElement.dataset.enhanced = "true";
+
+ const matches = (node) => {
+ const query = filter.value.trim().toLocaleLowerCase();
+ const fields = [
+ node.node_id, node.title, node.summary, node.family, node.status, ...node.tags
+ ];
+ return !query || fields
+ .join(" ").toLocaleLowerCase().includes(query);
+ };
+ const selectedIds = () => new Set(nodes.filter(matches).map((node) => node.node_id));
+ const render = () => {
+ main.dataset.mode = mode.value;
+ const visible = nodes.filter(matches);
+ const ids = selectedIds();
+ list.replaceChildren(...visible.map((node) => {
+ const item = document.createElement("li");
+ const button = document.createElement("button");
+ button.type = "button";
+ button.textContent = `${node.title} (${node.node_id})`;
+ button.dataset.nodeId = node.node_id;
+ button.addEventListener("click", () => inspect(node, button));
+ item.append(button);
+ return item;
+ }));
+ const visibleEdges = edges.filter((edge) => ids.has(edge.source_id) && ids.has(edge.target_id));
+ rows.replaceChildren(...visibleEdges.map((edge) => {
+ const row = document.createElement("tr");
+ [edge.source_id, edge.relation, edge.target_id].forEach((value) => {
+ const cell = document.createElement("td");
+ cell.textContent = value;
+ row.append(cell);
+ });
+ return row;
+ }));
+ status.textContent = `${visible.length} nodes and ${visibleEdges.length} relationships `
+ + `shown in ${mode.value} mode.`;
+ };
+ const inspect = (node, button) => {
+ opener = button;
+ detail.replaceChildren();
+ const heading = document.createElement("h2");
+ heading.id = "node-dialog-title";
+ heading.textContent = node.title;
+ const identity = document.createElement("p");
+ identity.textContent = `${node.node_id} · ${node.family} · ${node.status}`;
+ const summary = document.createElement("p");
+ summary.textContent = node.summary;
+ detail.append(heading, identity, summary);
+ dialog.showModal();
+ close.focus();
+ };
+ close.addEventListener("click", () => dialog.close());
+ dialog.addEventListener("close", () => opener?.focus());
+ filter.addEventListener("input", render);
+ mode.addEventListener("change", render);
+ render();
+})();
+""".strip()
+
+
+def _csp_hash(content: str) -> str:
+ digest = hashlib.sha256(content.encode("utf-8")).digest()
+ return base64.b64encode(digest).decode("ascii")
+
+
+def _embedded_json(value: object) -> str:
+ return (
+ json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+ .replace("&", "\\u0026")
+ .replace("<", "\\u003c")
+ .replace(">", "\\u003e")
+ )
+
+
+def _static_node_markup(plan: dict[str, object]) -> str:
+ graph = cast(dict[str, object], plan["graph"])
+ nodes = cast(list[dict[str, object]], graph["nodes"])
+ parts: list[str] = []
+ for node in nodes:
+ node_id = html.escape(cast(str, node["node_id"]))
+ attribute_node_id = html.escape(cast(str, node["node_id"]), quote=True)
+ title = html.escape(cast(str, node["title"]))
+ family = html.escape(cast(str, node["family"]))
+ status = html.escape(cast(str, node["status"]))
+ summary = html.escape(cast(str, node["summary"]))
+ parts.append(
+ ""
+ f'"
+ f'{family} · {status}
'
+ f"{summary}
"
+ ""
+ )
+ return "".join(parts)
+
+
+def _static_edge_markup(plan: dict[str, object]) -> str:
+ graph = cast(dict[str, object], plan["graph"])
+ edges = cast(list[dict[str, object]], graph["edges"])
+ return "".join(
+ ""
+ f"| {html.escape(cast(str, edge['source_id']))} | "
+ f"{html.escape(cast(str, edge['relation']))} | "
+ f"{html.escape(cast(str, edge['target_id']))} | "
+ "
"
+ for edge in edges
+ )
+
+
+class PortableGraphHtmlRenderer:
+ """Render a validated graph package without querying or publishing project state."""
+
+ renderer_id = "portable_graph_html"
+ renderer_version = "1"
+
+ def render(self, package: ProjectionPackageV1) -> ProjectionRenderResult:
+ started = perf_counter_ns()
+ package = ProjectionPackageV1.from_dict(package.as_dict())
+ document = package.document
+ if package.kind != "graph":
+ raise DocForgeError("invalid_projection", "Graph renderer requires a graph package")
+ renderer = cast(dict[str, object], document["renderer"])
+ if renderer != {
+ "renderer_id": self.renderer_id,
+ "renderer_version": self.renderer_version,
+ }:
+ raise DocForgeError("unsupported_renderer", "Graph renderer identity is incompatible")
+ if document["components"] != [
+ {"component_id": "graph.portable-document@1"},
+ {"component_id": "graph.accessible-list@1"},
+ {"component_id": "graph.relationship-table@1"},
+ ]:
+ raise DocForgeError(
+ "invalid_projection",
+ "Portable graph renderer component declarations are incompatible",
+ )
+ if document["assets"] != []:
+ raise DocForgeError(
+ "invalid_projection",
+ "Portable graph renderer does not accept project-provided assets",
+ )
+ plan = cast(dict[str, object], document["plan"])
+ view = cast(dict[str, object], plan["view"])
+ initial_mode = view.get("initial_mode")
+ policy = cast(dict[str, object], plan["policy"])
+ if (
+ initial_mode not in {"nodes", "flow", "web"}
+ or policy.get("logic_requested") is not False
+ ):
+ raise DocForgeError(
+ "unsupported_renderer",
+ "Portable graph renderer version 1 does not render Logic projections",
+ )
+ title = html.escape(cast(str, view["title"]))
+ project = cast(dict[str, object], plan["project"])
+ embedded = _embedded_json(plan)
+ static_nodes = _static_node_markup(plan)
+ static_edges = _static_edge_markup(plan)
+ csp = (
+ "default-src 'none'; "
+ f"style-src 'sha256-{_csp_hash(PORTABLE_GRAPH_CSS)}'; "
+ f"script-src 'sha256-{_csp_hash(PORTABLE_GRAPH_JAVASCRIPT)}'; "
+ "img-src 'none'; connect-src 'none'; object-src 'none'; base-uri 'none'; "
+ "form-action 'none'; frame-ancestors 'none'"
+ )
+ output = (
+ "\n"
+ '\n'
+ "\n"
+ '\n'
+ '\n'
+ '\n'
+ f"{title} · DocForge graph\n"
+ f"\n"
+ "\n"
+ "\n"
+ 'Skip to graph content\n'
+ "\n"
+ f"{title}
\n"
+ f'Generation {html.escape(cast(str, project["source_hash"]))}
\n'
+ '\n'
+ '\n'
+ '\n"
+ "
\n"
+ '\n'
+ "\n"
+ f'\n'
+ '\n'
+ '
\n'
+ '
'
+ 'Relationships
'
+ "Selected graph facts"
+ '| Source | Relation | '
+ f'Target |
{static_edges}'
+ "
"
+ "\n"
+ "
{html.escape(cast(str, page['title']))}
",
+ '',
+ f"- ID
- {html.escape(node_id)}
",
+ f"- Family
- {html.escape(cast(str, page['family']))}
",
+ f"- Status
- {html.escape(cast(str, page['status']))}
",
+ f"- Authority
- {html.escape(cast(str, page['authority']))}
",
+ "
",
+ f'{html.escape(cast(str, page["summary"]))}
',
+ self.markdown.render(cast(str, page["content"])).rstrip(),
+ ]
+ relationships = cast(list[object], page["cross_references"])
+ if relationships:
+ sections.append('')
+ for relationship_value in relationships:
+ relationship = cast(dict[str, object], relationship_value)
+ sections.append(
+ f"- {html.escape(cast(str, relationship['relation']))}: "
+ f"{html.escape(cast(str, relationship['target_id']))}
"
+ )
+ sections.append("
")
+ sections.append("")
+ return "\n".join(sections)
+
+ def _content(
+ self,
+ plan: dict[str, object],
+ fragments: dict[str, str],
+ ) -> str:
+ navigation = ['")
+ sections = [*navigation]
+ for value in cast(list[object], plan["pages"]):
+ page = cast(dict[str, object], value)
+ node_id = cast(str, page["node_id"])
+ sections.append(fragments.get(node_id, self.render_page_fragment(page)))
+ return "\n".join(sections)
diff --git a/src/docforge_renderers/py.typed b/src/docforge_renderers/py.typed
new file mode 100644
index 0000000..e75b43f
--- /dev/null
+++ b/src/docforge_renderers/py.typed
@@ -0,0 +1 @@
+# PEP 561 marker for the typed DocForge renderer package.
diff --git a/tests/accessibility.spec.mjs b/tests/accessibility.spec.mjs
new file mode 100644
index 0000000..82f92c3
--- /dev/null
+++ b/tests/accessibility.spec.mjs
@@ -0,0 +1,187 @@
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+const AXE_TAGS = [
+ "wcag2a",
+ "wcag2aa",
+ "wcag21a",
+ "wcag21aa",
+ "wcag22a",
+ "wcag22aa",
+];
+const MANUAL_AXE_TAGS = AXE_TAGS.filter((tag) => !tag.startsWith("wcag22"));
+
+let fixtureProcess;
+let surfaces;
+
+function startFixture() {
+ const python = process.env.DOCFORGE_PYTHON || ".venv/bin/python";
+ const child = spawn(python, ["tools/accessibility_fixture.py"], {
+ cwd: process.cwd(),
+ stdio: ["pipe", "pipe", "pipe"],
+ });
+ let stderr = "";
+ child.stderr.setEncoding("utf8");
+ child.stderr.on("data", (chunk) => {
+ stderr += chunk;
+ });
+ const lines = createInterface({ input: child.stdout });
+ const ready = new Promise((resolve, reject) => {
+ let settled = false;
+ lines.once("line", (line) => {
+ settled = true;
+ try {
+ const payload = JSON.parse(line);
+ if (
+ payload.schema_version !== 1
+ || typeof payload.manual_html !== "string"
+ || typeof payload.portable_html !== "string"
+ || typeof payload.live_url !== "string"
+ ) {
+ throw new Error("Accessibility fixture returned an invalid payload");
+ }
+ resolve(payload);
+ } catch (error) {
+ reject(error);
+ } finally {
+ lines.close();
+ }
+ });
+ child.once("exit", (code, signal) => {
+ if (!settled) {
+ reject(
+ new Error(
+ `Accessibility fixture exited before readiness `
+ + `(code=${code}, signal=${signal}):\n${stderr}`,
+ ),
+ );
+ }
+ });
+ });
+ return { child, ready };
+}
+
+async function stopFixture(child) {
+ if (child.exitCode !== null || child.signalCode !== null) {
+ return;
+ }
+ const exited = new Promise((resolve) => child.once("exit", resolve));
+ child.stdin.end();
+ await Promise.race([
+ exited,
+ new Promise((_, reject) => {
+ setTimeout(() => reject(new Error("Accessibility fixture did not stop")), 5_000);
+ }),
+ ]);
+}
+
+function violationReport(violations) {
+ return violations.map((violation) => {
+ const targets = violation.nodes
+ .flatMap((node) => node.target)
+ .join(", ");
+ return `${violation.id} (${violation.impact}): ${violation.help}\n ${targets}`;
+ }).join("\n");
+}
+
+async function expectNoAxeViolations(page, tags = AXE_TAGS) {
+ const results = await new AxeBuilder({ page }).withTags(tags).analyze();
+ expect(results.violations, violationReport(results.violations)).toEqual([]);
+}
+
+async function tabTo(page, selector, maximumTabs = 40) {
+ for (let count = 0; count < maximumTabs; count += 1) {
+ await page.keyboard.press("Tab");
+ if (await page.evaluate((target) => document.activeElement?.matches(target), selector)) {
+ return page.locator(selector).filter({ visible: true }).first();
+ }
+ }
+ throw new Error(`Keyboard focus did not reach ${selector}`);
+}
+
+test.beforeAll(async () => {
+ const fixture = startFixture();
+ fixtureProcess = fixture.child;
+ surfaces = await fixture.ready;
+});
+
+test.afterAll(async () => {
+ await stopFixture(fixtureProcess);
+});
+
+test("generated manual has no axe violations and its navigation works by keyboard", async ({
+ page,
+}) => {
+ await page.setContent(surfaces.manual_html, { waitUntil: "load" });
+ await expect(page.locator("main section")).not.toHaveCount(0);
+ // The generic renderer owns structure, while this frozen project template owns target sizing.
+ await expectNoAxeViolations(page, MANUAL_AXE_TAGS);
+
+ await page.keyboard.press("Tab");
+ const firstNavigationLink = page.locator("nav[aria-label='Documentation'] a").first();
+ await expect(firstNavigationLink).toBeFocused();
+ const target = await firstNavigationLink.getAttribute("href");
+ expect(target).toMatch(/^#[A-Za-z0-9_.-]+$/);
+ await page.keyboard.press("Enter");
+ await expect.poll(() => page.evaluate(() => window.location.hash)).toBe(target);
+});
+
+test("portable graph supports skip, filter, view, and dialog keyboard flows", async ({ page }) => {
+ await page.goto("about:blank");
+ await page.setContent(surfaces.portable_html, { waitUntil: "load" });
+ await expect(page.locator("#status")).toContainText("nodes and");
+ await expectNoAxeViolations(page);
+
+ await page.keyboard.press("Tab");
+ await expect(page.locator("a.skip")).toBeFocused();
+ await page.keyboard.press("Enter");
+ await expect(page.locator("main#main")).toBeFocused();
+
+ await page.goto("about:blank");
+ await page.setContent(surfaces.portable_html, { waitUntil: "load" });
+ await page.keyboard.press("Tab");
+ await page.keyboard.press("Tab");
+ await expect(page.locator("#filter")).toBeFocused();
+ await page.keyboard.type("guide.workflow");
+ await expect(page.locator("#status")).toContainText("1 nodes and");
+
+ await page.keyboard.press("Tab");
+ await expect(page.locator("#mode")).toBeFocused();
+ await page.keyboard.press("ArrowDown");
+ await expect(page.locator("main#main")).toHaveAttribute("data-mode", "flow");
+ await page.keyboard.press("ArrowUp");
+ await expect(page.locator("main#main")).toHaveAttribute("data-mode", "nodes");
+
+ await page.keyboard.press("Tab");
+ const nodeButton = page.locator("#node-list button").first();
+ await expect(nodeButton).toBeFocused();
+ await page.keyboard.press("Enter");
+ await expect(page.locator("#node-dialog")).toHaveAttribute("open", "");
+ await expect(page.locator("#close-dialog")).toBeFocused();
+ await expectNoAxeViolations(page);
+ await page.keyboard.press("Escape");
+ await expect(page.locator("#node-dialog")).not.toHaveAttribute("open", "");
+ await expect(nodeButton).toBeFocused();
+});
+
+test("live viewer passes axe and exposes keyboard graph and resize controls", async ({ page }) => {
+ await page.goto(surfaces.live_url);
+ await expect(page.locator("#status")).toContainText("nodes ·");
+ await expect(page.locator("#graph g.node[role='button']").first()).toBeVisible();
+ await expectNoAxeViolations(page);
+
+ const resizer = await tabTo(page, "#left-resizer");
+ const originalWidth = Number(await resizer.getAttribute("aria-valuenow"));
+ await page.keyboard.press("ArrowRight");
+ await expect(resizer).toHaveAttribute("aria-valuenow", String(originalWidth + 16));
+
+ await tabTo(page, "#graph g.node[role='button']");
+ await page.keyboard.press("Shift+Enter");
+ await expect(page.locator("#node-dialog")).toHaveAttribute("open", "");
+ await expect(page.locator("#close-node-dialog")).toBeFocused();
+ await expectNoAxeViolations(page);
+ await page.keyboard.press("Escape");
+ await expect(page.locator("#node-dialog")).not.toHaveAttribute("open", "");
+});
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 92e3cda..bd5a039 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -17,6 +17,25 @@ from docforge.viewer_manager import ViewerManager
ROOT = Path(__file__).resolve().parents[1]
FIXTURES = ROOT / "tests" / "fixtures"
+GRAPH_CONFIG = """
+
+[graph_render]
+output_root = ".docforge/portable-graph"
+
+[[graph_render.views]]
+id = "architecture"
+renderer = "portable_graph_html"
+output = "architecture.html"
+title = "Alpha architecture"
+root = "guide.workflow"
+initial_mode = "nodes"
+depth = 2
+max_nodes = 20
+max_edges = 40
+max_work = 1000
+include_logic = false
+"""
+
class DocForgeCliTests(unittest.TestCase):
def copy_fixture(self, destination: Path) -> Path:
@@ -134,6 +153,30 @@ class DocForgeCliTests(unittest.TestCase):
else:
os.environ["DOCFORGE_VIEWER_MANAGER_STATE"] = previous
+ def test_portable_graph_plan_render_and_status_are_self_service(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = self.copy_fixture(Path(directory))
+ descriptor = root / ".docforge/project.toml"
+ descriptor.write_text(
+ descriptor.read_text(encoding="utf-8") + GRAPH_CONFIG,
+ encoding="utf-8",
+ )
+ parser = _parser()
+ planned = _run(
+ parser.parse_args(["--project-root", str(root), "graph-plan", "architecture"])
+ )
+ self.assertEqual("architecture", planned["view_id"])
+ rendered = _run(
+ parser.parse_args(["--project-root", str(root), "graph-render", "architecture"])
+ )
+ self.assertEqual("current", rendered["state"])
+ status = _run(
+ parser.parse_args(
+ ["--project-root", str(root), "graph-render-status", "architecture"]
+ )
+ )
+ self.assertEqual("current", status["state"])
+
if __name__ == "__main__":
unittest.main()
diff --git a/tests/test_client_integration.py b/tests/test_client_integration.py
index 778b96a..539f089 100644
--- a/tests/test_client_integration.py
+++ b/tests/test_client_integration.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import contextlib
+import hashlib
import io
import json
import os
@@ -18,6 +19,7 @@ from jsonschema import Draft202012Validator
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
+from docforge.changeset_contract import document_hash
from docforge.cli import _parser, _run, main
from docforge.client_config import (
_read_existing,
@@ -39,6 +41,19 @@ CONFIGURATION_SCHEMA = json.loads(
DOCTOR_SCHEMA = json.loads((SCHEMAS / "doctor-result.schema.json").read_text(encoding="utf-8"))
POLICY_SCHEMA = json.loads((SCHEMAS / "policy.schema.json").read_text(encoding="utf-8"))
+GRAPH_RENDER_CONFIG = """
+
+[graph_render]
+output_root = ".docforge/portable-graph"
+
+[[graph_render.views]]
+id = "architecture"
+renderer = "portable_graph_html"
+output = "architecture.html"
+title = "Alpha architecture"
+root = "guide.workflow"
+"""
+
class ClientIntegrationTests(unittest.TestCase):
def copy_fixture(self, destination: Path) -> Path:
@@ -156,6 +171,256 @@ class ClientIntegrationTests(unittest.TestCase):
)
self.assertEqual("invalid_capability_binding", escalated.exception.code)
+ def test_nondefault_projection_policy_selectors_serialize_and_validate(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = self.copy_fixture(Path(directory))
+ descriptor = root / ".docforge" / "project.toml"
+ descriptor.write_text(
+ descriptor.read_text(encoding="utf-8") + GRAPH_RENDER_CONFIG,
+ encoding="utf-8",
+ )
+ project = Project.open(root)
+ expected_arguments = [
+ "-I",
+ "-m",
+ "docforge.mcp_server",
+ "--project-root",
+ str(root),
+ "--capability-mode",
+ "read",
+ "--manual-render-policy",
+ "disabled",
+ "--portable-graph-policy",
+ "disabled",
+ "--live-viewer-policy",
+ "disabled",
+ ]
+ for client in ("codex", "claude", "openclaw"):
+ with self.subTest(client=client):
+ result = generate_client_configuration(
+ project,
+ client,
+ manual_render_policy="disabled",
+ portable_graph_policy="disabled",
+ live_viewer_policy="disabled",
+ )
+ Draft202012Validator(CONFIGURATION_SCHEMA).validate(result)
+ _validate_configuration_result(result)
+ self.assertEqual(
+ {
+ "schema_version": 2,
+ "manual": "disabled",
+ "portable_graph": "disabled",
+ "live_viewer": "disabled",
+ },
+ result["projection_policy"],
+ )
+ self.assertEqual(expected_arguments, result["binding"]["args"])
+ content = result["artifact"]["content"]
+ if client == "codex":
+ document = tomllib.loads(content)
+ serialized = document["mcp_servers"][result["server_name"]]["args"]
+ elif client == "claude":
+ document = json.loads(content)
+ serialized = document["mcpServers"][result["server_name"]]["args"]
+ else:
+ document = json.loads(content)
+ serialized = document["mcp"]["servers"][result["server_name"]]["args"]
+ self.assertEqual(expected_arguments, serialized)
+ canonical = json.dumps(
+ result["projection_policy"],
+ sort_keys=True,
+ separators=(",", ":"),
+ ensure_ascii=False,
+ ).encode("utf-8")
+ self.assertEqual(
+ hashlib.sha256(canonical).hexdigest(),
+ result["projection_policy_hash"],
+ )
+
+ def test_projection_policy_schema_and_configuration_validation_reject_drift(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ project = Project.open(self.copy_fixture(Path(directory)))
+ result = generate_client_configuration(
+ project,
+ "codex",
+ manual_render_policy="disabled",
+ live_viewer_policy="disabled",
+ )
+ validator = Draft202012Validator(CONFIGURATION_SCHEMA)
+ validator.validate(result)
+ _validate_configuration_result(result)
+
+ for field, value in (
+ ("schema_version", 1),
+ ("manual", "on-demand"),
+ ("portable_graph", "auto"),
+ ("live_viewer", "explicit"),
+ ):
+ with self.subTest(field=field):
+ drifted = json.loads(json.dumps(result))
+ drifted["projection_policy"][field] = value
+ self.assertTrue(list(validator.iter_errors(drifted)))
+
+ missing = json.loads(json.dumps(result))
+ missing.pop("projection_policy")
+ self.assertTrue(list(validator.iter_errors(missing)))
+ extra = json.loads(json.dumps(result))
+ extra["projection_policy"]["project_path"] = "/private/project"
+ self.assertTrue(list(validator.iter_errors(extra)))
+
+ mismatched = json.loads(json.dumps(result))
+ mismatched["projection_policy"]["manual"] = "explicit"
+ canonical = json.dumps(
+ mismatched["projection_policy"],
+ sort_keys=True,
+ separators=(",", ":"),
+ ensure_ascii=False,
+ ).encode("utf-8")
+ mismatched["projection_policy_hash"] = hashlib.sha256(canonical).hexdigest()
+ with self.assertRaises(AssertionError):
+ _validate_configuration_result(mismatched)
+
+ bad_hash = json.loads(json.dumps(result))
+ bad_hash["projection_policy_hash"] = "0" * 64
+ with self.assertRaises(AssertionError):
+ _validate_configuration_result(bad_hash)
+
+ defaulted = generate_client_configuration(project, "codex")
+ self.assertNotIn(
+ "--manual-render-policy",
+ defaulted["binding"]["args"],
+ )
+ defaulted["projection_policy"]["manual"] = "disabled"
+ canonical = json.dumps(
+ defaulted["projection_policy"],
+ sort_keys=True,
+ separators=(",", ":"),
+ ensure_ascii=False,
+ ).encode("utf-8")
+ defaulted["projection_policy_hash"] = hashlib.sha256(canonical).hexdigest()
+ with self.assertRaises(AssertionError):
+ _validate_configuration_result(defaulted)
+
+ unavailable = json.loads(json.dumps(result))
+ unavailable["projection_availability"]["manual_configured"] = False
+ with self.assertRaises(AssertionError):
+ _validate_configuration_result(unavailable)
+
+ descriptor = project.descriptor.descriptor_path
+ descriptor.write_text(
+ descriptor.read_text(encoding="utf-8") + GRAPH_RENDER_CONFIG,
+ encoding="utf-8",
+ )
+ graph_project = Project.open(project.descriptor.root)
+ graph_defaulted = generate_client_configuration(graph_project, "codex")
+ self.assertNotIn(
+ "--portable-graph-policy",
+ graph_defaulted["binding"]["args"],
+ )
+ coordinated_graph_drift = json.loads(json.dumps(graph_defaulted))
+ coordinated_graph_drift["projection_policy"]["portable_graph"] = "disabled"
+ coordinated_graph_drift["projection_availability"]["portable_graph_configured"] = False
+ canonical = json.dumps(
+ coordinated_graph_drift["projection_policy"],
+ sort_keys=True,
+ separators=(",", ":"),
+ ensure_ascii=False,
+ ).encode("utf-8")
+ coordinated_graph_drift["projection_policy_hash"] = hashlib.sha256(
+ canonical
+ ).hexdigest()
+ coordinated_graph_drift["configuration_hash"] = document_hash(
+ {
+ "schema_version": 1,
+ "client": coordinated_graph_drift["client"],
+ "server_name": coordinated_graph_drift["server_name"],
+ "project": coordinated_graph_drift["project"],
+ "binding": coordinated_graph_drift["binding"],
+ "effective_policy": coordinated_graph_drift["effective_policy"],
+ "projection_policy": coordinated_graph_drift["projection_policy"],
+ "projection_policy_hash": coordinated_graph_drift["projection_policy_hash"],
+ "projection_availability": coordinated_graph_drift["projection_availability"],
+ "artifact_format": coordinated_graph_drift["artifact"]["format"],
+ "artifact_content_sha256": coordinated_graph_drift["artifact"][
+ "content_sha256"
+ ],
+ }
+ )
+ with self.assertRaises(AssertionError):
+ _validate_configuration_result(coordinated_graph_drift)
+
+ invalid_selections = (
+ {"manual_render_policy": "sometimes"},
+ {"portable_graph_policy": "auto"},
+ {"live_viewer_policy": "always"},
+ )
+ for selection in invalid_selections:
+ with self.subTest(selection=selection):
+ with self.assertRaises(DocForgeError) as raised:
+ generate_client_configuration(graph_project, "codex", **selection)
+ self.assertEqual("invalid_projection_policy", raised.exception.code)
+
+ def test_doctor_round_trips_projection_selectors_and_rejects_invalid_modes(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ parent = Path(directory)
+ project = Project.open(self.copy_fixture(parent))
+ ProjectIndex(project).build()
+ config = parent / "openclaw.json"
+ generated = generate_client_configuration(
+ project,
+ "openclaw",
+ manual_render_policy="disabled",
+ live_viewer_policy="disabled",
+ output=config,
+ )
+ healthy = run_doctor(
+ project,
+ "openclaw",
+ config_path=config,
+ server_name=generated["server_name"],
+ )
+ Draft202012Validator(DOCTOR_SCHEMA).validate(healthy)
+ self.assertEqual("healthy", healthy["doctor_state"])
+ self.assertIn(
+ "effective_policy_valid",
+ [check["code"] for check in healthy["checks"]],
+ )
+
+ document = json.loads(config.read_text(encoding="utf-8"))
+ entry = document["mcp"]["servers"][generated["server_name"]]
+ arguments = entry["args"]
+ manual_position = arguments.index("--manual-render-policy") + 1
+ arguments[manual_position] = "sometimes"
+ config.write_text(json.dumps(document, sort_keys=True), encoding="utf-8")
+ invalid = run_doctor(
+ project,
+ "openclaw",
+ config_path=config,
+ server_name=generated["server_name"],
+ )
+ Draft202012Validator(DOCTOR_SCHEMA).validate(invalid)
+ self.assertEqual("unhealthy", invalid["doctor_state"])
+ policy_check = next(
+ check for check in invalid["checks"] if check["check_id"] == "policy.effective"
+ )
+ self.assertEqual("invalid_projection_policy", policy_check["code"])
+
+ arguments[manual_position] = "auto"
+ config.write_text(json.dumps(document, sort_keys=True), encoding="utf-8")
+ unavailable = run_doctor(
+ project,
+ "openclaw",
+ config_path=config,
+ server_name=generated["server_name"],
+ )
+ Draft202012Validator(DOCTOR_SCHEMA).validate(unavailable)
+ self.assertEqual("unhealthy", unavailable["doctor_state"])
+ policy_check = next(
+ check for check in unavailable["checks"] if check["check_id"] == "policy.effective"
+ )
+ self.assertEqual("projection_policy_unavailable", policy_check["code"])
+
def test_explicit_fragment_write_is_atomic_conflict_aware_and_private(self) -> None:
with tempfile.TemporaryDirectory() as directory:
parent = Path(directory)
diff --git a/tests/test_graph_projection.py b/tests/test_graph_projection.py
new file mode 100644
index 0000000..d0b516a
--- /dev/null
+++ b/tests/test_graph_projection.py
@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, cast
+
+from docforge.errors import DocForgeError
+from docforge.graph_projection import (
+ GraphViewRequestV1,
+ build_graph_view_plan,
+)
+from docforge.models import Edge, Limits, Node, ProjectDescriptor, ProjectSnapshot
+from docforge.projection_contract import GraphViewPlanV1
+
+
+def _document(plan: GraphViewPlanV1) -> dict[str, Any]:
+ return cast(dict[str, Any], plan.as_dict())
+
+
+def _node(
+ node_id: str,
+ *,
+ title: str | None = None,
+ family: str = "code",
+ authority: str = "derived",
+ status: str = "active",
+ tags: tuple[str, ...] = (),
+) -> Node:
+ return Node(
+ node_id=node_id,
+ title=title or node_id,
+ family=family,
+ authority=authority,
+ status=status,
+ tags=tags,
+ summary=f"Summary for {node_id}",
+ content=f"SECRET SOURCE BODY {node_id}",
+ source_path=f"/private/source/{node_id}.py",
+ source_anchor=f"line-{len(node_id)}",
+ content_hash=(node_id.encode("utf-8").hex() + "0" * 64)[:64],
+ )
+
+
+def _snapshot(
+ root: Path,
+ nodes: tuple[Node, ...],
+ edges: tuple[Edge, ...],
+) -> ProjectSnapshot:
+ descriptor = ProjectDescriptor(
+ schema_version=1,
+ project_id="graph-project",
+ title="Graph project",
+ adapter="generic",
+ root=root,
+ descriptor_path=root / ".docforge" / "project.toml",
+ descriptor_hash="d" * 64,
+ content_roots=(root / "docs",),
+ authority_files=(),
+ cache_root=root / ".docforge" / "cache",
+ index_path=root / ".docforge" / "cache" / "index.sqlite3",
+ changeset_root=root / ".docforge" / "changesets",
+ proposal_writers=(),
+ render=None,
+ allowed_relations=tuple(sorted({edge.relation for edge in edges})),
+ profiles=(),
+ limits=Limits(),
+ )
+ return ProjectSnapshot(
+ descriptor=descriptor,
+ nodes=nodes,
+ edges=edges,
+ revision="revision-1",
+ source_hash="a" * 64,
+ )
+
+
+class GraphProjectionTests(unittest.TestCase):
+ def test_exact_root_plan_is_deterministic_sorted_and_path_free(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ nodes = (
+ _node("c", family="docs", tags=("python",)),
+ _node("a", tags=("python", "callable")),
+ _node("b", tags=("python",)),
+ _node("unrelated"),
+ )
+ edges = (
+ Edge("b", "calls", "c"),
+ Edge("a", "calls", "b"),
+ Edge("unrelated", "calls", "c"),
+ )
+ request = GraphViewRequestV1(
+ view_id="architecture",
+ title="Architecture",
+ root_node_id="a",
+ depth=2,
+ max_nodes=10,
+ max_edges=10,
+ max_work=100,
+ )
+ first = build_graph_view_plan(_snapshot(root, nodes, edges), request, True)
+ second = build_graph_view_plan(
+ _snapshot(root, tuple(reversed(nodes)), tuple(reversed(edges))),
+ request,
+ True,
+ )
+ self.assertEqual(first.as_dict(), second.as_dict())
+ GraphViewPlanV1.from_dict(first.as_dict())
+ document = _document(first)
+ self.assertEqual(
+ ["a", "b", "c"], [node["node_id"] for node in document["graph"]["nodes"]]
+ )
+ self.assertEqual(
+ [
+ {"source_id": "a", "relation": "calls", "target_id": "b"},
+ {"source_id": "b", "relation": "calls", "target_id": "c"},
+ ],
+ document["graph"]["edges"],
+ )
+ encoded = json.dumps(document, sort_keys=True)
+ self.assertNotIn(str(root), encoded)
+ self.assertNotIn("SECRET SOURCE BODY", encoded)
+ self.assertNotIn("/private/source/", encoded)
+ self.assertNotIn("line-1", encoded)
+ self.assertEqual("excluded", document["policy"]["source_paths"])
+ self.assertEqual("excluded", document["policy"]["source_bodies"])
+ self.assertEqual("allowed", document["policy"]["logic"])
+ self.assertEqual("exact_root", document["view"]["scope"]["kind"])
+
+ def test_lexical_scope_uses_metadata_only_and_closed_filters(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ nodes = (
+ _node(
+ "api.handler",
+ title="Request handler",
+ family="code",
+ authority="derived",
+ tags=("python", "route"),
+ ),
+ _node(
+ "api.test",
+ title="Handler proof",
+ family="test",
+ authority="approved_plan",
+ tags=("python", "test"),
+ ),
+ replace(
+ _node("hidden.body", family="code", tags=("python",)),
+ content="request handler appears only in the forbidden source body",
+ ),
+ )
+ edges = (
+ Edge("api.handler", "tested_by", "api.test"),
+ Edge("hidden.body", "relates_to", "api.handler"),
+ )
+ request = GraphViewRequestV1(
+ view_id="routes",
+ title="Routes",
+ query="request handler",
+ families=("code",),
+ authorities=("derived",),
+ tags=("python", "route"),
+ relations=("tested_by",),
+ max_nodes=10,
+ max_edges=10,
+ max_work=100,
+ )
+ plan = build_graph_view_plan(_snapshot(root, nodes, edges), request, False)
+ document = _document(plan)
+ self.assertEqual(
+ ["api.handler"],
+ [node["node_id"] for node in document["graph"]["nodes"]],
+ )
+ self.assertEqual([], document["graph"]["edges"])
+ self.assertEqual(
+ {
+ "families": ["code"],
+ "relations": ["tested_by"],
+ "authorities": ["derived"],
+ "statuses": [],
+ "tags": ["python", "route"],
+ },
+ document["view"]["filters"],
+ )
+ self.assertEqual("lexical", document["view"]["scope"]["kind"])
+
+ def test_result_and_work_limits_emit_explicit_omissions(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ nodes = tuple(_node(value) for value in ("a", "b", "c", "d"))
+ edges = (
+ Edge("a", "calls", "b"),
+ Edge("a", "calls", "c"),
+ Edge("a", "calls", "d"),
+ Edge("b", "calls", "c"),
+ )
+ result_limited = build_graph_view_plan(
+ _snapshot(root, nodes, edges),
+ GraphViewRequestV1(
+ view_id="limited",
+ title="Limited",
+ root_node_id="a",
+ max_nodes=2,
+ max_edges=0,
+ max_work=100,
+ ),
+ False,
+ )
+ result_limited = _document(result_limited)
+ self.assertEqual(
+ ["a", "b"], [node["node_id"] for node in result_limited["graph"]["nodes"]]
+ )
+ self.assertEqual([], result_limited["graph"]["edges"])
+ self.assertEqual(
+ ["edge_result_limit", "node_result_limit"],
+ [item["code"] for item in result_limited["omissions"]],
+ )
+
+ work_limited = build_graph_view_plan(
+ _snapshot(root, nodes, edges),
+ GraphViewRequestV1(
+ view_id="work",
+ title="Work",
+ root_node_id="a",
+ max_nodes=10,
+ max_edges=10,
+ max_work=1,
+ ),
+ False,
+ )
+ work_limited = _document(work_limited)
+ self.assertIn(
+ "work_limit",
+ [item["code"] for item in work_limited["omissions"]],
+ )
+ self.assertEqual(
+ 1,
+ work_limited["diagnostics"]["examined_work_units"],
+ )
+ self.assertTrue(work_limited["diagnostics"]["truncated"])
+
+ def test_no_ast_policy_excludes_requested_logic(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ snapshot = _snapshot(root, (_node("a"),), ())
+ request = GraphViewRequestV1(
+ view_id="logic",
+ title="Logic",
+ root_node_id="a",
+ initial_mode="logic",
+ include_logic=True,
+ )
+ blocked = _document(build_graph_view_plan(snapshot, request, False))
+ self.assertEqual("forbidden", blocked["policy"]["logic"])
+ self.assertEqual([], blocked["graph"]["logic_projections"])
+ self.assertIn(
+ "logic_forbidden",
+ [item["code"] for item in blocked["omissions"]],
+ )
+ allowed = _document(build_graph_view_plan(snapshot, request, True))
+ self.assertEqual("allowed", allowed["policy"]["logic"])
+ self.assertNotIn(
+ "logic_forbidden",
+ [item["code"] for item in allowed["omissions"]],
+ )
+
+ def test_edge_and_node_filters_constrain_exact_root_bfs(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ nodes = (
+ _node("root", family="code", status="active"),
+ _node("code-child", family="code", status="active"),
+ _node("doc-child", family="docs", status="active"),
+ _node("old-child", family="code", status="historical"),
+ )
+ edges = (
+ Edge("root", "calls", "code-child"),
+ Edge("root", "documents", "doc-child"),
+ Edge("root", "calls", "old-child"),
+ )
+ plan = build_graph_view_plan(
+ _snapshot(root, nodes, edges),
+ GraphViewRequestV1(
+ view_id="filtered",
+ title="Filtered",
+ root_node_id="root",
+ families=("code",),
+ statuses=("active",),
+ relations=("calls",),
+ max_work=100,
+ ),
+ False,
+ )
+ plan = _document(plan)
+ self.assertEqual(
+ ["code-child", "root"], [node["node_id"] for node in plan["graph"]["nodes"]]
+ )
+ self.assertEqual(
+ [{"source_id": "root", "relation": "calls", "target_id": "code-child"}],
+ plan["graph"]["edges"],
+ )
+
+ def test_invalid_requests_and_graphs_fail_closed(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ snapshot = _snapshot(root, (_node("a"),), ())
+ invalid_requests = (
+ GraphViewRequestV1(view_id="v", title="V"),
+ GraphViewRequestV1(
+ view_id="v",
+ title="V",
+ root_node_id="a",
+ query="a",
+ ),
+ GraphViewRequestV1(
+ view_id="v",
+ title="V",
+ root_node_id="a",
+ max_nodes=0,
+ ),
+ GraphViewRequestV1(
+ view_id="v",
+ title="V",
+ query="***",
+ ),
+ GraphViewRequestV1(
+ view_id="v",
+ title="V",
+ root_node_id="a",
+ families=("code", "code"),
+ ),
+ )
+ for request in invalid_requests:
+ with self.subTest(request=request), self.assertRaises(DocForgeError) as error:
+ build_graph_view_plan(snapshot, request, False)
+ self.assertEqual("invalid_graph_view_request", error.exception.code)
+
+ with self.assertRaises(DocForgeError) as missing:
+ build_graph_view_plan(
+ snapshot,
+ GraphViewRequestV1(
+ view_id="v",
+ title="V",
+ root_node_id="missing",
+ ),
+ False,
+ )
+ self.assertEqual("missing_node", missing.exception.code)
+
+ duplicate = _snapshot(root, (_node("a"), _node("a")), ())
+ with self.assertRaises(DocForgeError) as invalid:
+ build_graph_view_plan(
+ duplicate,
+ GraphViewRequestV1(
+ view_id="v",
+ title="V",
+ root_node_id="a",
+ ),
+ False,
+ )
+ self.assertEqual("invalid_projection", invalid.exception.code)
+
+ def test_plan_identity_changes_with_generation_request_and_policy(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ snapshot = _snapshot(root, (_node("a"),), ())
+ request = GraphViewRequestV1(
+ view_id="v",
+ title="V",
+ root_node_id="a",
+ )
+ base = build_graph_view_plan(snapshot, request, False)
+ self.assertEqual(
+ base.plan_id,
+ build_graph_view_plan(snapshot, request, False).plan_id,
+ )
+ self.assertNotEqual(
+ base.plan_id,
+ build_graph_view_plan(
+ replace(snapshot, source_hash="b" * 64),
+ request,
+ False,
+ ).plan_id,
+ )
+ self.assertNotEqual(
+ base.plan_id,
+ build_graph_view_plan(
+ snapshot,
+ replace(request, title="Other"),
+ False,
+ ).plan_id,
+ )
+ self.assertNotEqual(
+ base.plan_id,
+ build_graph_view_plan(snapshot, request, True).plan_id,
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_graph_publication.py b/tests/test_graph_publication.py
new file mode 100644
index 0000000..1d6d110
--- /dev/null
+++ b/tests/test_graph_publication.py
@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+import tomllib
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from jsonschema import Draft202012Validator
+
+from docforge.errors import DocForgeError
+from docforge.graph_rendering import GraphRenderService
+from docforge.models import ProjectState
+from docforge.project import Project
+from docforge.projection_contract import projection_hash
+
+ROOT = Path(__file__).resolve().parents[1]
+FIXTURES = ROOT / "tests" / "fixtures"
+PROJECT_SCHEMA = json.loads((ROOT / "schemas/project.schema.json").read_text(encoding="utf-8"))
+
+GRAPH_CONFIG = """
+
+[graph_render]
+output_root = ".docforge/portable-graph"
+
+[[graph_render.views]]
+id = "architecture"
+renderer = "portable_graph_html"
+output = "architecture.html"
+title = "Alpha architecture"
+root = "guide.workflow"
+initial_mode = "nodes"
+depth = 2
+max_nodes = 20
+max_edges = 40
+max_work = 1000
+families = ["guide", "proof"]
+relations = ["depends_on", "proves"]
+authorities = []
+statuses = []
+tags = []
+include_logic = false
+"""
+
+
+class GraphPublicationTests(unittest.TestCase):
+ def setUp(self) -> None:
+ self.temporary = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temporary.cleanup)
+ self.root = Path(self.temporary.name) / "alpha"
+ shutil.copytree(FIXTURES / "alpha", self.root)
+ descriptor = self.root / ".docforge/project.toml"
+ descriptor.write_text(
+ descriptor.read_text(encoding="utf-8") + GRAPH_CONFIG,
+ encoding="utf-8",
+ )
+ self.project = Project.open(self.root)
+ self.service = GraphRenderService(self.project)
+
+ def test_descriptor_schema_and_runtime_accept_the_separate_graph_view(self) -> None:
+ document = tomllib.loads((self.root / ".docforge/project.toml").read_text(encoding="utf-8"))
+ Draft202012Validator(PROJECT_SCHEMA).validate(document)
+ config = self.project.descriptor.graph_render
+ assert config is not None
+ self.assertEqual(self.root / ".docforge/portable-graph", config.output_root)
+ self.assertEqual("architecture", config.views[0].view_id)
+ self.assertEqual("guide.workflow", config.views[0].root_node_id)
+ self.assertIsNone(config.views[0].query)
+
+ def test_render_publication_is_deterministic_durable_and_unchanged_on_reuse(self) -> None:
+ missing = self.service.status("architecture")
+ self.assertEqual("stale", missing["state"])
+ self.assertEqual("missing", missing["outputs"][0]["state"])
+
+ first = self.service.render("architecture")
+ output = self.root / ".docforge/portable-graph/architecture.html"
+ manifest = self.root / ".docforge/cache/projection-publications/graph/architecture.json"
+ artifact_root = self.root / ".docforge/cache/projection-artifacts"
+ self.assertEqual("current", first["state"])
+ self.assertEqual("published", first["publication"])
+ self.assertTrue(output.is_file())
+ self.assertTrue(manifest.is_file())
+ self.assertEqual(1, len(tuple(artifact_root.glob("*.html"))))
+ before = output.stat()
+ before_bytes = output.read_bytes()
+
+ current = self.service.status("architecture")
+ self.assertEqual("current", current["state"])
+ self.assertEqual("manifest", current["outputs"][0]["verification"])
+ second = self.service.render("architecture")
+ after = output.stat()
+ self.assertEqual("unchanged", second["publication"])
+ self.assertEqual(before_bytes, output.read_bytes())
+ self.assertEqual((before.st_dev, before.st_ino), (after.st_dev, after.st_ino))
+
+ def test_status_is_manifest_only_and_detects_source_output_and_manifest_changes(self) -> None:
+ self.service.render("architecture")
+ output = self.root / ".docforge/portable-graph/architecture.html"
+ manifest = self.root / ".docforge/cache/projection-publications/graph/architecture.json"
+ with mock.patch.object(
+ self.project,
+ "load",
+ side_effect=AssertionError("status must not load or plan"),
+ ):
+ self.assertEqual("current", self.service.status("architecture")["state"])
+
+ output.write_bytes(output.read_bytes() + b"\n")
+ changed_output = self.service.status("architecture")
+ self.assertEqual("stale", changed_output["state"])
+ self.assertEqual("output_changed", changed_output["outputs"][0]["reason"])
+
+ self.service.render("architecture")
+ source = self.root / "docs/content/workflow.md"
+ source.write_text(
+ source.read_text(encoding="utf-8") + "\nChanged after publication.\n",
+ encoding="utf-8",
+ )
+ changed_source = self.service.status("architecture")
+ self.assertEqual("stale", changed_source["state"])
+ self.assertEqual("stale", changed_source["outputs"][0]["state"])
+ self.assertEqual(
+ "source_generation_changed",
+ changed_source["outputs"][0]["reason"],
+ )
+
+ self.service.render("architecture")
+ manifest.write_text("{bad-json", encoding="utf-8")
+ corrupt = self.service.status("architecture")
+ self.assertEqual("missing", corrupt["outputs"][0]["state"])
+
+ def test_status_validates_nested_manifest_and_artifact_store_evidence(self) -> None:
+ self.service.render("architecture")
+ manifest_path = (
+ self.root / ".docforge/cache/projection-publications/graph/architecture.json"
+ )
+ original = json.loads(manifest_path.read_text(encoding="utf-8"))
+ mutations = {
+ "bad_project": lambda value: value.__setitem__("project", "bad"),
+ "forged_artifact": lambda value: value.__setitem__(
+ "artifact",
+ {
+ "artifact_id": "portable-graph.html",
+ "media_type": "text/html; charset=utf-8",
+ "sha256": "0" * 64,
+ "bytes": 1,
+ },
+ ),
+ "bad_store": lambda value: value["store"].__setitem__("size", -1),
+ }
+ for name, mutate in mutations.items():
+ with self.subTest(name=name):
+ value = json.loads(json.dumps(original))
+ mutate(value)
+ value.pop("publication_id")
+ value["publication_id"] = projection_hash(value)
+ manifest_path.write_text(
+ json.dumps(value, sort_keys=True, indent=2) + "\n",
+ encoding="utf-8",
+ )
+ status = self.service.status("architecture")
+ self.assertEqual("unverified", status["outputs"][0]["state"])
+ self.assertEqual("manifest_invalid", status["outputs"][0]["reason"])
+ manifest_path.write_text(
+ json.dumps(original, sort_keys=True, indent=2) + "\n",
+ encoding="utf-8",
+ )
+
+ artifact = next((self.root / ".docforge/cache/projection-artifacts").glob("*.html"))
+ artifact.unlink()
+ missing = self.service.status("architecture")
+ self.assertEqual("stale", missing["outputs"][0]["state"])
+ self.assertEqual("artifact_store_missing", missing["outputs"][0]["reason"])
+ repaired = self.service.render("architecture")
+ self.assertEqual("current", repaired["state"])
+ self.assertTrue(artifact.is_file())
+
+ def test_status_detects_source_and_publication_races(self) -> None:
+ self.service.render("architecture")
+ current = self.project.incremental_state()
+ assert current is not None
+ changed = ProjectState(source_hash="0" * 64, revision="changed")
+ with mock.patch.object(
+ self.project,
+ "incremental_state",
+ side_effect=(current, changed),
+ ):
+ raced_source = self.service.status("architecture")
+ self.assertEqual("stale", raced_source["state"])
+ self.assertEqual(
+ "source_changed_during_status",
+ raced_source["outputs"][0]["reason"],
+ )
+
+ baseline = self.service._manifest_status(
+ self.project.descriptor.graph_render.views[0], # type: ignore[union-attr]
+ current,
+ )
+ replaced = dict(baseline)
+ replaced["publication_id"] = "f" * 64
+ with mock.patch.object(
+ self.service,
+ "_manifest_status",
+ side_effect=(baseline, replaced),
+ ):
+ raced_publication = self.service.status("architecture")
+ self.assertEqual("stale", raced_publication["state"])
+ self.assertEqual(
+ "publication_changed_during_status",
+ raced_publication["outputs"][0]["reason"],
+ )
+
+ def test_manifest_failure_after_output_is_degraded_success(self) -> None:
+ with mock.patch.object(
+ self.service,
+ "_publish_manifest",
+ side_effect=DocForgeError(
+ "publication_failure",
+ "Synthetic manifest failure",
+ ),
+ ):
+ result = self.service.render("architecture")
+ self.assertEqual("degraded", result["state"])
+ self.assertEqual("published", result["publication"])
+ self.assertEqual("manifest", result["committed_stage"])
+ self.assertTrue((self.root / ".docforge/portable-graph/architecture.html").is_file())
+ self.assertEqual("failed", result["manifest"]["state"])
+
+ def test_post_commit_stage_failures_are_degraded_and_precommit_failures_raise(self) -> None:
+ committed = DocForgeError(
+ "publication_failure",
+ "Synthetic committed failure",
+ mutation_committed=True,
+ )
+ cases = (
+ ("_publish_artifact", "artifact_store", "partial", False),
+ ("_publish_output", "output", "published", None),
+ )
+ for method, stage, publication, output_exists in cases:
+ with self.subTest(method=method):
+ root = Path(self.temporary.name) / method
+ shutil.copytree(FIXTURES / "alpha", root)
+ descriptor = root / ".docforge/project.toml"
+ descriptor.write_text(
+ descriptor.read_text(encoding="utf-8") + GRAPH_CONFIG,
+ encoding="utf-8",
+ )
+ service = GraphRenderService(Project.open(root))
+ with mock.patch.object(service, method, side_effect=committed):
+ result = service.render("architecture")
+ self.assertEqual("degraded", result["state"])
+ self.assertEqual(stage, result["committed_stage"])
+ self.assertEqual(publication, result["publication"])
+ if output_exists is not None:
+ self.assertEqual(
+ output_exists,
+ (root / ".docforge/portable-graph/architecture.html").exists(),
+ )
+
+ uncommitted = DocForgeError(
+ "publication_failure",
+ "Synthetic precommit failure",
+ mutation_committed=False,
+ )
+ with (
+ mock.patch.object(
+ self.service,
+ "_publish_output",
+ side_effect=uncommitted,
+ ),
+ self.assertRaises(DocForgeError),
+ ):
+ self.service.render("architecture")
+
+ def test_configuration_rejects_unsafe_ambiguous_and_overlapping_views(self) -> None:
+ cases = {
+ "both_scope": GRAPH_CONFIG.replace(
+ 'root = "guide.workflow"',
+ 'root = "guide.workflow"\nquery = "workflow"',
+ ),
+ "output_overlap": GRAPH_CONFIG.replace(
+ 'output_root = ".docforge/portable-graph"',
+ 'output_root = "docs/content"',
+ ),
+ "active_renderer": GRAPH_CONFIG.replace(
+ 'renderer = "portable_graph_html"',
+ 'renderer = "shell"',
+ ),
+ "oversized": GRAPH_CONFIG.replace("max_nodes = 20", "max_nodes = 100000"),
+ "logic_mode": GRAPH_CONFIG.replace('initial_mode = "nodes"', 'initial_mode = "logic"'),
+ "logic_projection": GRAPH_CONFIG.replace(
+ "include_logic = false",
+ "include_logic = true",
+ ),
+ "long_title": GRAPH_CONFIG.replace(
+ 'title = "Alpha architecture"',
+ f'title = "{"x" * 1025}"',
+ ),
+ "long_query": GRAPH_CONFIG.replace(
+ 'root = "guide.workflow"',
+ f'query = "{"x" * 10001}"',
+ ),
+ "too_many_filters": GRAPH_CONFIG.replace(
+ 'families = ["guide", "proof"]',
+ "families = [" + ", ".join(f'"family-{index}"' for index in range(65)) + "]",
+ ),
+ }
+ for name, graph_config in cases.items():
+ with self.subTest(name=name):
+ root = Path(self.temporary.name) / name
+ shutil.copytree(FIXTURES / "alpha", root)
+ descriptor = root / ".docforge/project.toml"
+ descriptor.write_text(
+ descriptor.read_text(encoding="utf-8") + graph_config,
+ encoding="utf-8",
+ )
+ parsed = tomllib.loads(descriptor.read_text(encoding="utf-8"))
+ if name != "output_overlap":
+ self.assertFalse(Draft202012Validator(PROJECT_SCHEMA).is_valid(parsed))
+ with self.assertRaises(DocForgeError):
+ Project.open(root)
+
+ relocated = Path(self.temporary.name) / "descriptor-overlap"
+ shutil.copytree(FIXTURES / "alpha", relocated)
+ descriptor = relocated / ".docforge/project.toml"
+ base = descriptor.read_text(encoding="utf-8").replace(
+ 'cache_root = ".docforge/cache"\nindex = ".docforge/cache/index.sqlite3"',
+ 'cache_root = "var/cache"\nindex = "var/cache/index.sqlite3"',
+ )
+ descriptor.write_text(
+ base
+ + GRAPH_CONFIG.replace(
+ 'output_root = ".docforge/portable-graph"',
+ 'output_root = ".docforge"',
+ ),
+ encoding="utf-8",
+ )
+ with self.assertRaises(DocForgeError):
+ Project.open(relocated)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_graph_rendering.py b/tests/test_graph_rendering.py
new file mode 100644
index 0000000..bdb4831
--- /dev/null
+++ b/tests/test_graph_rendering.py
@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import os
+import shutil
+import sqlite3
+import tempfile
+import unittest
+from pathlib import Path
+from typing import cast
+from unittest import mock
+
+from docforge.errors import DocForgeError
+from docforge.graph_projection import (
+ GraphViewRequestV1,
+ build_graph_projection_package,
+ build_graph_view_plan,
+)
+from docforge.project import Project
+from docforge.projection_contract import ProjectionPackageV1
+from docforge_renderers.graph import PortableGraphHtmlRenderer
+
+ROOT = Path(__file__).resolve().parents[1]
+FIXTURES = ROOT / "tests" / "fixtures"
+
+
+class PortableGraphRenderingTests(unittest.TestCase):
+ def setUp(self) -> None:
+ self.temporary = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temporary.cleanup)
+ self.root = Path(self.temporary.name) / "alpha"
+ shutil.copytree(FIXTURES / "alpha", self.root)
+ self.project = Project.open(self.root)
+ self.snapshot = self.project.load()
+ self.request = GraphViewRequestV1(
+ view_id="architecture",
+ title="Alpha architecture",
+ root_node_id="guide.workflow",
+ depth=2,
+ max_nodes=20,
+ max_edges=40,
+ max_work=1_000,
+ )
+ self.plan = build_graph_view_plan(self.snapshot, self.request, False)
+ self.package = build_graph_projection_package(
+ self.plan,
+ renderer_id=PortableGraphHtmlRenderer.renderer_id,
+ renderer_version=PortableGraphHtmlRenderer.renderer_version,
+ max_output_bytes=1_000_000,
+ )
+
+ def test_portable_artifact_is_deterministic_self_contained_and_generation_bound(self) -> None:
+ renderer = PortableGraphHtmlRenderer()
+ first = renderer.render(self.package)
+ second = renderer.render(self.package)
+ self.assertEqual(first.artifacts, second.artifacts)
+ self.assertEqual(1, len(first.artifacts))
+ artifact = first.artifacts[0]
+ self.assertEqual("portable-graph.html", artifact.artifact_id)
+ self.assertEqual("text/html; charset=utf-8", artifact.media_type)
+ receipt = first.receipt.as_dict()
+ evidence = cast(list[dict[str, object]], receipt["artifacts"])
+ self.assertEqual(
+ hashlib.sha256(artifact.content).hexdigest(),
+ evidence[0]["sha256"],
+ )
+ rendered = artifact.content.decode("utf-8")
+ self.assertIn("Content-Security-Policy", rendered)
+ self.assertIn("default-src 'none'", rendered)
+ self.assertIn('type="application/json"', rendered)
+ self.assertNotIn(str(self.root), rendered)
+ self.assertNotIn("docs/content/", rendered)
+ self.assertNotIn("Editors change canonical nodes", rendered)
+ self.assertNotIn("fetch(", rendered)
+ self.assertNotIn("XMLHttpRequest", rendered)
+ self.assertNotIn("WebSocket", rendered)
+ self.assertIn(self.snapshot.source_hash, rendered)
+
+ def test_embedded_plan_is_exact_and_script_breakout_is_inert(self) -> None:
+ plan = copy.deepcopy(self.plan.as_dict())
+ view = plan["view"]
+ assert isinstance(view, dict)
+ view["title"] = ''
+ plan.pop("plan_id")
+ from docforge.projection_contract import GraphViewPlanV1
+
+ malicious = GraphViewPlanV1.create(plan)
+ package = build_graph_projection_package(
+ malicious,
+ renderer_id=PortableGraphHtmlRenderer.renderer_id,
+ renderer_version=PortableGraphHtmlRenderer.renderer_version,
+ max_output_bytes=1_000_000,
+ )
+ rendered = PortableGraphHtmlRenderer().render(package).artifacts[0].content.decode("utf-8")
+ self.assertNotIn('", 1)[0]
+ self.assertEqual(malicious.as_dict(), json.loads(embedded))
+
+ def test_renderer_has_no_project_database_or_filesystem_write_capability(self) -> None:
+ forbidden = AssertionError("portable graph renderer crossed its capability boundary")
+ with (
+ mock.patch.object(Project, "open", side_effect=forbidden),
+ mock.patch.object(Project, "load", side_effect=forbidden),
+ mock.patch.object(sqlite3, "connect", side_effect=forbidden),
+ mock.patch.object(Path, "write_bytes", side_effect=forbidden),
+ mock.patch.object(Path, "write_text", side_effect=forbidden),
+ mock.patch.object(Path, "mkdir", side_effect=forbidden),
+ mock.patch.object(os, "replace", side_effect=forbidden),
+ mock.patch.object(os, "rename", side_effect=forbidden),
+ mock.patch.object(os, "unlink", side_effect=forbidden),
+ ):
+ result = PortableGraphHtmlRenderer().render(self.package)
+ self.assertEqual(1, len(result.artifacts))
+
+ def test_renderer_rejects_wrong_kind_identity_assets_and_size(self) -> None:
+ wrong = ProjectionPackageV1.create(
+ kind="graph",
+ plan=self.plan,
+ renderer={
+ "renderer_id": PortableGraphHtmlRenderer.renderer_id,
+ "renderer_version": "other",
+ },
+ components=[],
+ assets=[],
+ output_policy={
+ "artifact_ids": ["portable-graph.html"],
+ "max_total_bytes": 1_000_000,
+ },
+ )
+ with self.assertRaises(DocForgeError) as unsupported:
+ PortableGraphHtmlRenderer().render(wrong)
+ self.assertEqual("unsupported_renderer", unsupported.exception.code)
+
+ with_asset = ProjectionPackageV1.create(
+ kind="graph",
+ plan=self.plan,
+ renderer={
+ "renderer_id": PortableGraphHtmlRenderer.renderer_id,
+ "renderer_version": PortableGraphHtmlRenderer.renderer_version,
+ },
+ components=[],
+ assets=[
+ {
+ "asset_id": "project-script",
+ "media_type": "text/javascript",
+ "sha256": "0" * 64,
+ "text": "alert(1)",
+ }
+ ],
+ output_policy={"artifact_ids": ["portable-graph.html"], "max_total_bytes": 1_000_000},
+ )
+ with self.assertRaises(DocForgeError) as assets:
+ PortableGraphHtmlRenderer().render(with_asset)
+ self.assertEqual("invalid_projection", assets.exception.code)
+
+ wrong_components = ProjectionPackageV1.create(
+ kind="graph",
+ plan=self.plan,
+ renderer={
+ "renderer_id": PortableGraphHtmlRenderer.renderer_id,
+ "renderer_version": PortableGraphHtmlRenderer.renderer_version,
+ },
+ components=[],
+ assets=[],
+ output_policy={
+ "artifact_ids": ["portable-graph.html"],
+ "max_total_bytes": 1_000_000,
+ },
+ )
+ with self.assertRaises(DocForgeError) as components:
+ PortableGraphHtmlRenderer().render(wrong_components)
+ self.assertEqual("invalid_projection", components.exception.code)
+
+ wrong_artifact = ProjectionPackageV1.create(
+ kind="graph",
+ plan=self.plan,
+ renderer={
+ "renderer_id": PortableGraphHtmlRenderer.renderer_id,
+ "renderer_version": PortableGraphHtmlRenderer.renderer_version,
+ },
+ components=self.package.document["components"], # type: ignore[arg-type]
+ assets=[],
+ output_policy={
+ "artifact_ids": ["unexpected.html"],
+ "max_total_bytes": 1_000_000,
+ },
+ )
+ with self.assertRaises(DocForgeError) as artifact:
+ PortableGraphHtmlRenderer().render(wrong_artifact)
+ self.assertEqual("invalid_projection", artifact.exception.code)
+
+ tiny = build_graph_projection_package(
+ self.plan,
+ renderer_id=PortableGraphHtmlRenderer.renderer_id,
+ renderer_version=PortableGraphHtmlRenderer.renderer_version,
+ max_output_bytes=1,
+ )
+ with self.assertRaises(DocForgeError) as too_large:
+ PortableGraphHtmlRenderer().render(tiny)
+ self.assertEqual("render_too_large", too_large.exception.code)
+
+ def test_initial_mode_is_honored_and_logic_is_rejected(self) -> None:
+ for mode in ("nodes", "flow", "web"):
+ with self.subTest(mode=mode):
+ plan = build_graph_view_plan(
+ self.snapshot,
+ GraphViewRequestV1(
+ view_id=f"{mode}-view",
+ title=f"{mode.title()} view",
+ root_node_id="guide.workflow",
+ initial_mode=mode, # type: ignore[arg-type]
+ depth=2,
+ max_nodes=20,
+ max_edges=40,
+ max_work=1_000,
+ ),
+ False,
+ )
+ package = build_graph_projection_package(
+ plan,
+ renderer_id=PortableGraphHtmlRenderer.renderer_id,
+ renderer_version=PortableGraphHtmlRenderer.renderer_version,
+ max_output_bytes=1_000_000,
+ )
+ rendered = (
+ PortableGraphHtmlRenderer().render(package).artifacts[0].content.decode("utf-8")
+ )
+ self.assertIn(f'data-mode="{mode}"', rendered)
+ self.assertIn(f'