Search for a node to inspect its neighborhood.
Visualization disconnected
diff --git a/src/docforge/cli.py b/src/docforge/cli.py
index 9e5f507..35b55d2 100644
--- a/src/docforge/cli.py
+++ b/src/docforge/cli.py
@@ -13,11 +13,9 @@ 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
@@ -31,18 +29,6 @@ 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)
@@ -56,21 +42,6 @@ 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)
@@ -124,12 +95,6 @@ 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")
@@ -159,9 +124,6 @@ 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,
@@ -190,39 +152,12 @@ 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 = (
- {
- "status": "ok",
- "state": "skipped",
- "reason": "projection_policy_disabled",
- }
- if projection_policy.manual == "disabled"
- else RenderService(
- project,
- manual_policy=projection_policy.manual,
- ).render("manual")
- )
+ render = RenderService(project).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 {
@@ -315,52 +250,24 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
cursor=arguments.cursor,
)
if arguments.command == "render":
- return RenderService(
- project,
- manual_policy=projection_policy.manual,
- ).render(arguments.view_id)
+ return RenderService(project).render(arguments.view_id)
if arguments.command == "render-status":
- rendering = RenderService(
- project,
- manual_policy=projection_policy.manual,
- )
+ rendering = RenderService(project)
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,
- manual_policy=projection_policy.manual,
- ).preview(arguments.changeset_id, arguments.view_id)
+ return RenderService(project).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,
- live_viewer_policy=projection_policy.live_viewer,
- ).start(
+ visualization = ViewerManagerClient(index).start(
node_id=arguments.node,
query=arguments.query,
depth=arguments.depth,
@@ -377,15 +284,9 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
"visualization": visualization,
}
if arguments.command == "visualization-status":
- return ViewerManagerClient(
- index,
- live_viewer_policy=projection_policy.live_viewer,
- ).status()
+ return ViewerManagerClient(index).status()
if arguments.command == "visualization-stop":
- return ViewerManagerClient(
- index,
- live_viewer_policy=projection_policy.live_viewer,
- ).stop()
+ return ViewerManagerClient(index).stop()
raise DocForgeError("invalid_command", "Unknown command")
diff --git a/src/docforge/client_config.py b/src/docforge/client_config.py
index 18c9de6..7b482d5 100644
--- a/src/docforge/client_config.py
+++ b/src/docforge/client_config.py
@@ -18,10 +18,9 @@ from typing import Literal, cast
from .changeset_contract import document_hash
from .errors import DocForgeError
-from .models import ProjectDescriptor, ProjectService
+from .models import ProjectService
from .policy import CapabilityMode, compose_effective_policy
-from .project import Project, project_root_fingerprint, validate_descriptor_binding
-from .projection_policy import compose_projection_policy
+from .project import project_root_fingerprint, validate_descriptor_binding
ClientName = Literal["codex", "claude", "openclaw"]
CLIENT_NAMES: tuple[ClientName, ...] = ("codex", "claude", "openclaw")
@@ -606,37 +605,11 @@ def _atomic_write(
os.close(directory_fd)
-def _validate_configuration_result(
- result: dict[str, object],
- *,
- trusted_descriptor: ProjectDescriptor | None = None,
-) -> None:
+def _validate_configuration_result(result: dict[str, object]) -> 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")
@@ -671,29 +644,6 @@ def _validate_configuration_result(
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)
@@ -713,34 +663,6 @@ def _validate_configuration_result(
)
):
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",
@@ -776,18 +698,6 @@ def _validate_configuration_result(
)
):
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,
@@ -796,9 +706,6 @@ def _validate_configuration_result(
"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"],
}
@@ -816,9 +723,6 @@ 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,
@@ -935,6 +839,9 @@ 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",
@@ -943,40 +850,6 @@ 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,
@@ -1029,7 +902,6 @@ 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(
@@ -1040,14 +912,6 @@ 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"],
}
@@ -1062,14 +926,6 @@ 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": [
@@ -1077,5 +933,5 @@ def generate_client_configuration(
*([] if publication_warning is None else [{"code": publication_warning}]),
],
}
- _validate_configuration_result(result, trusted_descriptor=descriptor)
+ _validate_configuration_result(result)
return result
diff --git a/src/docforge/doctor.py b/src/docforge/doctor.py
index 89fd345..e79ed61 100644
--- a/src/docforge/doctor.py
+++ b/src/docforge/doctor.py
@@ -20,7 +20,6 @@ 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
@@ -615,9 +614,6 @@ 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
@@ -666,9 +662,6 @@ 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"),
}
@@ -756,16 +749,6 @@ 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
index d716389..d4a05c3 100644
--- a/src/docforge/graph_projection.py
+++ b/src/docforge/graph_projection.py
@@ -9,20 +9,18 @@ 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,
-)
+from .projection_contract import GraphViewPlanV1
GraphViewMode = Literal["nodes", "flow", "web", "logic"]
+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
+
_QUERY_TOKEN = re.compile(r"\w+", re.UNICODE)
_DETAIL_FIELDS = (
"node_id",
@@ -497,29 +495,3 @@ def build_graph_view_plan(
},
}
)
-
-
-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
deleted file mode 100644
index dfd3ade..0000000
--- a/src/docforge/graph_render_config.py
+++ /dev/null
@@ -1,285 +0,0 @@
-"""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
deleted file mode 100644
index ee5c1a7..0000000
--- a/src/docforge/graph_rendering.py
+++ /dev/null
@@ -1,815 +0,0 @@
-"""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
index a249d38..3cee4d6 100644
--- a/src/docforge/manual_projection.py
+++ b/src/docforge/manual_projection.py
@@ -4,7 +4,6 @@ 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
@@ -24,51 +23,47 @@ 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()):
+ for targets in 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()
+ index = 0
+ indexes: dict[str, int] = {}
+ lowlinks: dict[str, int] = {}
+ stack: list[str] = []
+ on_stack: set[str] = set()
components: list[list[str]] = []
- for node_id in reversed(finished):
- if node_id in assigned:
- continue
- assigned.add(node_id)
+
+ def visit(node_id: str) -> None:
+ nonlocal index
+ indexes[node_id] = index
+ lowlinks[node_id] = index
+ index += 1
+ stack.append(node_id)
+ on_stack.add(node_id)
+ for target_id in adjacency[node_id]:
+ if target_id not in indexes:
+ visit(target_id)
+ lowlinks[node_id] = min(lowlinks[node_id], lowlinks[target_id])
+ elif target_id in on_stack:
+ lowlinks[node_id] = min(lowlinks[node_id], indexes[target_id])
+ if lowlinks[node_id] != indexes[node_id]:
+ return
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)
+ while stack:
+ member = stack.pop()
+ on_stack.remove(member)
+ component.append(member)
+ if member == node_id:
+ break
component.sort()
if len(component) > 1 or component[0] in adjacency[component[0]]:
components.append(component)
+
+ for node_id in node_ids:
+ if node_id not in indexes:
+ visit(node_id)
return sorted(components)
@@ -166,8 +161,6 @@ def build_manual_projection_package(
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."""
@@ -175,23 +168,6 @@ def build_manual_projection_package(
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,
@@ -200,7 +176,14 @@ def build_manual_projection_package(
{"component_id": "manual.document@1"},
{"component_id": "manual.commonmark@1"},
],
- assets=assets,
+ assets=[
+ {
+ "asset_id": "manual.template",
+ "media_type": "text/html; charset=utf-8",
+ "sha256": hashlib.sha256(template_bytes).hexdigest(),
+ "text": template,
+ }
+ ],
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 21e6544..d90e7b2 100644
--- a/src/docforge/mcp_server.py
+++ b/src/docforge/mcp_server.py
@@ -15,13 +15,11 @@ 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
@@ -49,8 +47,6 @@ 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",
@@ -138,9 +134,6 @@ 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 = (
@@ -160,40 +153,19 @@ 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,
- 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.rendering = RenderService(self.project, self.changesets)
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 {})
@@ -649,7 +621,6 @@ 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,
@@ -659,8 +630,6 @@ 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"],
@@ -683,8 +652,6 @@ 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,
@@ -747,8 +714,6 @@ 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),
@@ -864,29 +829,6 @@ 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,
@@ -1633,18 +1575,6 @@ 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,
@@ -1692,8 +1622,6 @@ 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,
@@ -2076,9 +2004,6 @@ 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(
@@ -2095,9 +2020,6 @@ 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,
)
@@ -2112,9 +2034,6 @@ 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."""
@@ -2128,9 +2047,6 @@ 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,
@@ -2146,9 +2062,6 @@ 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."""
@@ -2160,9 +2073,6 @@ 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(
@@ -2196,18 +2106,6 @@ 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,
@@ -2216,9 +2114,6 @@ 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 efcd71f..47d5339 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 Literal, Protocol, runtime_checkable
+from typing import Protocol, runtime_checkable
@dataclass(frozen=True)
@@ -49,33 +49,6 @@ 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
@@ -105,7 +78,6 @@ 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 17052b3..3d689bd 100644
--- a/src/docforge/project.py
+++ b/src/docforge/project.py
@@ -25,7 +25,6 @@ from .config_validation import (
string_list,
)
from .errors import DocForgeError
-from .graph_render_config import load_graph_render_config
from .models import (
ContextProfile,
Edge,
@@ -67,7 +66,6 @@ _DESCRIPTOR_KEYS = frozenset(
"derived",
"changesets",
"render",
- "graph_render",
"graph",
"limits",
"profiles",
@@ -550,6 +548,7 @@ def _load_descriptor(root: Path) -> ProjectDescriptor:
for field in defaults.__dataclass_fields__
}
)
+
render = load_render_config(
root,
document.get("render"),
@@ -561,18 +560,6 @@ 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):
@@ -636,7 +623,6 @@ 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
index 937d84d..6d06cb0 100644
--- a/src/docforge/projection_contract.py
+++ b/src/docforge/projection_contract.py
@@ -19,13 +19,6 @@ 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"]
@@ -475,39 +468,16 @@ def validate_projection_receipt(document: dict[str, object]) -> dict[str, object
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
+ or not isinstance(document.get("renderer"), dict)
+ or not isinstance(document.get("diagnostics"), dict)
+ or not isinstance(document.get("timing"), dict)
):
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")
@@ -524,10 +494,6 @@ def validate_projection_receipt(document: dict[str, object]) -> dict[str, object
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",
diff --git a/src/docforge/projection_fragments.py b/src/docforge/projection_fragments.py
deleted file mode 100644
index b2fe3d2..0000000
--- a/src/docforge/projection_fragments.py
+++ /dev/null
@@ -1,489 +0,0 @@
-"""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
deleted file mode 100644
index 5c7321d..0000000
--- a/src/docforge/projection_policy.py
+++ /dev/null
@@ -1,234 +0,0 @@
-"""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
deleted file mode 100644
index dc6d48a..0000000
--- a/src/docforge/projection_worker.py
+++ /dev/null
@@ -1,436 +0,0 @@
-"""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/render_contract.py b/src/docforge/render_contract.py
index 430dc26..aaecf9a 100644
--- a/src/docforge/render_contract.py
+++ b/src/docforge/render_contract.py
@@ -3,28 +3,15 @@
from __future__ import annotations
import hashlib
-import html
import json
from dataclasses import dataclass
from importlib.metadata import version
from pathlib import Path
-from typing import Protocol, cast
+from typing import Protocol
from .errors import DocForgeError
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)
@@ -35,7 +22,6 @@ class PreparedRender:
renderer: str
renderer_version: str
template_hash: str
- projection_receipt: dict[str, object] | None = None
class Renderer(Protocol):
@@ -60,13 +46,10 @@ class GenericHtmlRenderer:
renderer_id = "generic_html"
contract_version = "1"
- page_component_version = "manual.page@1"
-
- def __init__(self, *, incremental: bool = True) -> None:
+ def __init__(self) -> None:
self.renderer_version = (
f"{self.contract_version}+markdown-it-py-{version('markdown-it-py')}"
)
- self.incremental = incremental
def prepare(
self,
@@ -115,24 +98,19 @@ class GenericHtmlRenderer:
json.dumps(identity_payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
).hexdigest()
plan = build_manual_render_plan(snapshot, view, changeset_hash=changeset_hash)
- full_package = build_manual_projection_package(
+ 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,
+ )
+ from docforge_renderers.manual import ManualHtmlRenderer
+
+ result = ManualHtmlRenderer(self.renderer_version).render(
+ package,
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",
@@ -146,128 +124,21 @@ class GenericHtmlRenderer:
renderer=self.renderer_id,
renderer_version=self.renderer_version,
template_hash=template_hash,
- projection_receipt=result.receipt.as_dict(),
)
- def _incremental_result(
- self,
- snapshot: ProjectSnapshot,
- plan: ManualRenderPlanV1,
- template_bytes: bytes,
- *,
- full_package: ProjectionPackageV1,
- render_identity: str,
- ) -> ProjectionRenderResult:
- cache = ProjectionFragmentCache(
- snapshot.descriptor.root,
- snapshot.descriptor.cache_root,
- )
- pages = cast(list[object], plan.document["pages"])
- records: list[FragmentRecord | None] = []
- missing: list[tuple[int, FragmentKey]] = []
- for value in pages:
- page = cast(dict[str, object], value)
- key = FragmentKey.create(
- projection_kind="manual",
- renderer_id=self.renderer_id,
- renderer_version=self.renderer_version,
- component_version=self.page_component_version,
- semantic_input_hash=fragment_semantic_hash(page),
- )
- 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,
- )
- 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]] = {
GenericHtmlRenderer.renderer_id: GenericHtmlRenderer
}
-def renderer_for(view: RenderView, *, incremental: bool = True) -> Renderer:
+def renderer_for(view: RenderView) -> 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(incremental=incremental)
+ return factory()
def relative_output(snapshot: ProjectSnapshot, path: Path) -> str:
diff --git a/src/docforge/rendering.py b/src/docforge/rendering.py
index 86738d3..79e4116 100644
--- a/src/docforge/rendering.py
+++ b/src/docforge/rendering.py
@@ -26,8 +26,6 @@ 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
@@ -38,26 +36,9 @@ 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,
- *,
- manual_policy: ManualProjectionMode = "explicit",
- ) -> None:
+ def __init__(self, project: ProjectService, changesets: ChangesetStore | None = None) -> 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."""
@@ -105,7 +86,6 @@ 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:
@@ -127,12 +107,7 @@ class RenderService:
snapshot.descriptor.root,
view.output_path,
)
- prepared, _ = self._prepare(
- snapshot,
- view,
- changeset_hash=None,
- incremental=False,
- )
+ prepared, _ = self._prepare(snapshot, view, changeset_hash=None)
state = "missing"
actual_hash: str | None = None
output = view.output_path
@@ -176,7 +151,6 @@ 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)
@@ -399,8 +373,6 @@ 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(
@@ -600,10 +572,8 @@ 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 (
- fields in (required, required | {"projection_receipt"})
+ set(receipt) == required
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)
@@ -632,50 +602,6 @@ 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
@@ -737,7 +663,6 @@ 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:
@@ -762,7 +687,6 @@ 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)
@@ -807,12 +731,11 @@ 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, incremental=incremental).prepare(
+ prepared = renderer_for(view).prepare(
snapshot,
view,
template,
@@ -927,7 +850,6 @@ 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 1571c24..4c9c6d8 100644
--- a/src/docforge/telemetry.py
+++ b/src/docforge/telemetry.py
@@ -79,7 +79,6 @@ OPERATION_NAMES = frozenset(
"test",
"benchmark.m1",
"benchmark.m2",
- "benchmark.m3",
"mcp.invoke",
"mcp.bootstrap",
"mcp.sync",
@@ -97,8 +96,6 @@ 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",
@@ -120,9 +117,6 @@ 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 44f0d63..cd8ca88 100644
--- a/src/docforge/viewer_manager.py
+++ b/src/docforge/viewer_manager.py
@@ -28,10 +28,6 @@ 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
@@ -627,16 +623,9 @@ 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,
- live_viewer_policy: LiveViewerProjectionMode = "on-demand",
- ) -> None:
+ def __init__(self, index: ProjectIndex, *, state_path: Path | None = None) -> 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,
@@ -645,14 +634,6 @@ 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_renderers/graph.py b/src/docforge_renderers/graph.py
deleted file mode 100644
index a36528b..0000000
--- a/src/docforge_renderers/graph.py
+++ /dev/null
@@ -1,321 +0,0 @@
-"""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:
+ def _content(self, plan: dict[str, object]) -> str:
navigation = ['