"""Fail-closed canonical changeset application and derived-state refresh.""" from __future__ import annotations import json import os import secrets import stat import tempfile from collections import defaultdict from collections.abc import Mapping, Sequence from contextlib import suppress from dataclasses import dataclass, field from pathlib import Path from typing import Literal, Protocol, cast from ._fs_safety import ( open_bound_directory, rename_exchange_between_at, rename_noreplace_between_at, require_bound_directory, ) from .changesets import ChangesetStore from .errors import DocForgeError from .index import ProjectIndex from .models import Node, ProjectService, ProjectSnapshot from .projection_policy import ManualProjectionMode, validate_manual_projection_mode from .rendering import RenderService class CanonicalApplier(Protocol): """Project-owned serializer for one already validated proposal projection.""" def apply( self, base: ProjectSnapshot, projected: ProjectSnapshot, operations: tuple[Mapping[str, object], ...], ) -> dict[str, object]: ... @dataclass(frozen=True) class _CanonicalFile: device: int inode: int mode: int owner: int group: int size: int modified_ns: int changed_ns: int content: bytes def unchanged(self, other: _CanonicalFile | None) -> bool: return self == other def renamed_to(self, other: _CanonicalFile | None) -> bool: if other is None: return False return ( self.device, self.inode, self.mode, self.owner, self.group, self.size, self.modified_ns, self.content, ) == ( other.device, other.inode, other.mode, other.owner, other.group, other.size, other.modified_ns, other.content, ) @dataclass class _CanonicalPublication: relative: str target: Path action: Literal["create", "update", "delete"] expected: _CanonicalFile | None staged: Path staged_snapshot: _CanonicalFile backup_snapshot: _CanonicalFile | None = None published_snapshot: _CanonicalFile | None = None committed: bool = False cleanup_conflicts: list[dict[str, object]] = field( default_factory=lambda: list[dict[str, object]]() ) class GenericCanonicalApplier: """Apply generic Markdown/TOML projections inside declared content roots.""" def __init__(self, project: ProjectService) -> None: self.project = project def apply( self, base: ProjectSnapshot, projected: ProjectSnapshot, operations: tuple[Mapping[str, object], ...], ) -> dict[str, object]: del operations changed_sources = self._changed_sources(base, projected) if not changed_sources: raise DocForgeError("empty_changeset", "Changeset produces no canonical changes") base_by_source = self._nodes_by_source(base) projected_by_source = self._nodes_by_source(projected) publications: list[_CanonicalPublication] = [] created_directories: list[Path] = [] transaction_root: Path | None = None targets = {relative: self._target(relative) for relative in sorted(changed_sources)} try: transaction_root = self._prepare_transaction_root() for relative, target in targets.items(): self._prepare_parent(target.parent, created_directories) expected = self._capture(target, base.descriptor.limits.max_source_bytes) existed_in_base = relative in base_by_source if existed_in_base != (expected is not None): raise DocForgeError( "base_conflict", "Canonical target changed before application staging", source=relative, ) nodes = projected_by_source.get(relative, ()) raw = self._serialize_source(projected, relative, nodes) if nodes else b"" if nodes and len(raw) > base.descriptor.limits.max_source_bytes: raise DocForgeError( "source_too_large", "Applied canonical source exceeds the configured limit", source=relative, ) staged, staged_snapshot = self._stage( transaction_root, raw, mode=(stat.S_IMODE(expected.mode) if expected is not None else 0o600), owner=(expected.owner if expected is not None else None), group=(expected.group if expected is not None else None), source=relative, ) publications.append( _CanonicalPublication( relative=relative, target=target, action=( "delete" if not nodes else ("update" if expected is not None else "create") ), expected=expected, staged=staged, staged_snapshot=staged_snapshot, ) ) current = self.project.load() if current.source_hash != base.source_hash or current.revision != base.revision: raise DocForgeError( "base_conflict", "Canonical project changed while the changeset was being staged", expected_revision=base.revision, actual_revision=current.revision, expected_source_hash=base.source_hash, actual_source_hash=current.source_hash, ) for target in targets.values(): if target.is_symlink(): raise DocForgeError("path_escape", "Canonical target became a symbolic link") for publication in publications: self._publish(publication) applied = self.project.load() if self._semantic_snapshot(applied) != self._semantic_snapshot(projected): raise DocForgeError( "application_mismatch", "Applied canonical files do not reproduce the validated proposal", ) except Exception as error: recovery = self._rollback(publications) recovery.extend(self._discard_unowned_staging(publications)) if transaction_root is not None: recovery.extend(self._finish_transaction(transaction_root)) self._remove_empty_directories(created_directories) if recovery: cause = error.code if isinstance(error, DocForgeError) else type(error).__name__ raise DocForgeError( "application_recovery_required", ( "Canonical application raced external writes and could not be " "rolled back without overwriting foreign data" ), cause=cause, conflicts=recovery, remediation=( "Preserve the retained files, compare them with the named canonical " "targets, and resolve the project before retrying a new changeset." ), ) from error if isinstance(error, DocForgeError) and error.code == "application_recovery_required": raise DocForgeError( "base_conflict", "Canonical target raced publication but was restored without data loss", ) from error raise retained = [ conflict for publication in publications for conflict in publication.cleanup_conflicts ] retained.extend(self._discard_backups(publications)) assert transaction_root is not None retained.extend(self._finish_transaction(transaction_root)) recovery_status = "cleanup_required" if retained else "clean" return { "applied_sources": sorted(changed_sources), "removed_sources": sorted( source for source in changed_sources if source not in projected_by_source ), "retained_recovery_files": retained, "application_recovery": { "status": recovery_status, "retained": retained, "remediation": ( ( "Canonical content is committed. Preserve and inspect the retained " "transaction files, then remove only confirmed DocForge-owned artifacts." ) if retained else None ), }, } def _publish(self, publication: _CanonicalPublication) -> None: target = publication.target parent_fd = open_bound_directory(target.parent) staging_fd = open_bound_directory(publication.staged.parent) try: current = self._capture_at( target.parent, parent_fd, target.name, self.project.descriptor.limits.max_source_bytes, ) if publication.expected is None: if current is not None: raise DocForgeError( "base_conflict", "Canonical create target appeared during application", source=publication.relative, ) elif not publication.expected.unchanged(current): raise DocForgeError( "base_conflict", "Canonical target changed during application", source=publication.relative, ) staged = self._capture_at( publication.staged.parent, staging_fd, publication.staged.name, self.project.descriptor.limits.max_source_bytes, ) if staged is None or not publication.staged_snapshot.unchanged(staged): raise DocForgeError( "application_mismatch", "Canonical staging file changed before publication", source=publication.relative, ) if publication.action == "create": self._publish_create(publication, parent_fd, staging_fd) else: self._publish_exchange(publication, parent_fd, staging_fd) finally: os.close(staging_fd) os.close(parent_fd) def _publish_create( self, publication: _CanonicalPublication, parent_fd: int, staging_fd: int, ) -> None: try: os.link( publication.staged.name, publication.target.name, src_dir_fd=staging_fd, dst_dir_fd=parent_fd, follow_symlinks=False, ) except FileExistsError as error: raise DocForgeError( "base_conflict", "Canonical create target appeared during application", source=publication.relative, ) from error except OSError as error: raise DocForgeError( "application_failure", "Canonical create target could not be published", source=publication.relative, ) from error publication.committed = True published = self._capture_at( publication.target.parent, parent_fd, publication.target.name, self.project.descriptor.limits.max_source_bytes, ) if not publication.staged_snapshot.renamed_to(published): raise DocForgeError( "application_mismatch", "Published canonical create target does not match its staging file", source=publication.relative, ) assert published is not None publication.published_snapshot = published private_copy = self._capture_at( publication.staged.parent, staging_fd, publication.staged.name, self.project.descriptor.limits.max_source_bytes, ) if private_copy is None or not publication.staged_snapshot.renamed_to(private_copy): publication.cleanup_conflicts.append( self._recovery_conflict(publication, "private_create_link_changed") ) else: conflict = self._remove_private( publication, publication.staged, private_copy, "private_create_link_cleanup_failed", ) if conflict is not None: publication.cleanup_conflicts.append(conflict) refreshed = self._capture_at( publication.target.parent, parent_fd, publication.target.name, self.project.descriptor.limits.max_source_bytes, ) if not published.renamed_to(refreshed): raise DocForgeError( "application_mismatch", "Published canonical create target changed during private cleanup", source=publication.relative, ) publication.published_snapshot = refreshed os.fsync(parent_fd) require_bound_directory(publication.target.parent, parent_fd) def _publish_exchange( self, publication: _CanonicalPublication, parent_fd: int, staging_fd: int, ) -> None: rename_exchange_between_at( staging_fd, publication.staged.name, parent_fd, publication.target.name, ) publication.committed = True displaced = self._capture_at( publication.staged.parent, staging_fd, publication.staged.name, self.project.descriptor.limits.max_source_bytes, ) published = self._capture_at( publication.target.parent, parent_fd, publication.target.name, self.project.descriptor.limits.max_source_bytes, ) publication.backup_snapshot = displaced publication.published_snapshot = published if ( publication.expected is None or not publication.expected.renamed_to(displaced) or not publication.staged_snapshot.renamed_to(published) ): if not self._exchange_back(publication, parent_fd, staging_fd): raise DocForgeError( "application_recovery_required", "Canonical target raced atomic publication and displaced data was retained", source=publication.relative, retained=self._relative(publication.staged), ) raise DocForgeError( "base_conflict", "Canonical target changed at the atomic publication boundary", source=publication.relative, ) if publication.action == "delete": assert published is not None conflict = self._detach_canonical( publication, parent_fd, staging_fd, published, ) if conflict is not None: if publication.published_snapshot is None: publication.cleanup_conflicts.append(conflict) else: raise DocForgeError( "application_recovery_required", "Canonical delete target raced final detachment and was retained", source=publication.relative, conflict=conflict, ) os.fsync(parent_fd) os.fsync(staging_fd) require_bound_directory(publication.target.parent, parent_fd) require_bound_directory(publication.staged.parent, staging_fd) def _detach_canonical( self, publication: _CanonicalPublication, parent_fd: int, staging_fd: int, expected: _CanonicalFile, ) -> dict[str, object] | None: detached_name: str | None = None for _ in range(8): candidate = f".detached-{secrets.token_hex(12)}" if rename_noreplace_between_at( parent_fd, publication.target.name, staging_fd, candidate, ): detached_name = candidate break if detached_name is None: return self._recovery_conflict(publication, "private_name_collisions") detached = publication.staged.parent / detached_name moved: _CanonicalFile | None = None if self._same_inode_at(staging_fd, detached_name, expected): with suppress(DocForgeError, OSError): moved = self._capture_at( detached.parent, staging_fd, detached.name, self.project.descriptor.limits.max_source_bytes, ) if moved is None or not expected.renamed_to(moved): restored = rename_noreplace_between_at( staging_fd, detached_name, parent_fd, publication.target.name, ) os.fsync(staging_fd) os.fsync(parent_fd) conflict = self._recovery_conflict(publication, "canonical_detach_raced") conflict["raced_data"] = None if restored else self._relative(detached) conflict["foreign_target_restored"] = restored return conflict publication.published_snapshot = None conflict = self._remove_private( publication, detached, moved, "detached_cleanup_failed", ) os.fsync(parent_fd) return conflict def _exchange_back( self, publication: _CanonicalPublication, parent_fd: int, staging_fd: int, ) -> bool: backup = publication.backup_snapshot published = publication.published_snapshot if backup is None or published is None: return False try: rename_exchange_between_at( staging_fd, publication.staged.name, parent_fd, publication.target.name, ) restored = self._capture_at( publication.target.parent, parent_fd, publication.target.name, self.project.descriptor.limits.max_source_bytes, ) staged = self._capture_at( publication.staged.parent, staging_fd, publication.staged.name, self.project.descriptor.limits.max_source_bytes, ) if not backup.renamed_to(restored) or not published.renamed_to(staged): return False assert staged is not None publication.staged_snapshot = staged publication.backup_snapshot = None publication.published_snapshot = None publication.committed = False os.fsync(parent_fd) os.fsync(staging_fd) return True except (DocForgeError, OSError): return False @staticmethod def _same_inode_at( directory_fd: int, name: str, expected: _CanonicalFile, ) -> bool: try: current = os.stat(name, dir_fd=directory_fd, follow_symlinks=False) except OSError: return False return current.st_dev == expected.device and current.st_ino == expected.inode def _rollback( self, publications: Sequence[_CanonicalPublication], ) -> list[dict[str, object]]: conflicts: list[dict[str, object]] = [] for publication in reversed(publications): if not publication.committed: continue try: if publication.action == "create": conflict = self._rollback_create(publication) elif publication.action == "delete" and publication.published_snapshot is None: conflict = self._rollback_delete(publication) else: conflict = self._rollback_update(publication) except Exception as error: conflict = self._recovery_conflict(publication, "rollback_failed") conflict["error"] = ( error.code if isinstance(error, DocForgeError) else type(error).__name__ ) if conflict is not None: conflicts.append(conflict) return conflicts def _rollback_update( self, publication: _CanonicalPublication, ) -> dict[str, object] | None: parent_fd = open_bound_directory(publication.target.parent) staging_fd = open_bound_directory(publication.staged.parent) try: current = self._capture_at( publication.target.parent, parent_fd, publication.target.name, self.project.descriptor.limits.max_source_bytes, ) backup = self._capture_at( publication.staged.parent, staging_fd, publication.staged.name, self.project.descriptor.limits.max_source_bytes, ) if ( publication.published_snapshot is None or publication.backup_snapshot is None or not publication.published_snapshot.unchanged(current) or not publication.backup_snapshot.unchanged(backup) ): return self._recovery_conflict(publication, "target_or_backup_changed") if not self._exchange_back(publication, parent_fd, staging_fd): return self._recovery_conflict(publication, "atomic_restore_unconfirmed") return self._remove_private( publication, publication.staged, publication.staged_snapshot, "rollback_staging_cleanup_failed", ) finally: os.close(staging_fd) os.close(parent_fd) def _rollback_delete( self, publication: _CanonicalPublication, ) -> dict[str, object] | None: parent_fd = open_bound_directory(publication.target.parent) staging_fd = open_bound_directory(publication.staged.parent) try: current = self._capture_at( publication.target.parent, parent_fd, publication.target.name, self.project.descriptor.limits.max_source_bytes, ) backup = self._capture_at( publication.staged.parent, staging_fd, publication.staged.name, self.project.descriptor.limits.max_source_bytes, ) if current is not None: return self._recovery_conflict(publication, "deleted_target_reappeared") if publication.backup_snapshot is None or not publication.backup_snapshot.unchanged( backup ): return self._recovery_conflict(publication, "backup_changed") if not rename_noreplace_between_at( staging_fd, publication.staged.name, parent_fd, publication.target.name, ): return self._recovery_conflict(publication, "deleted_target_reappeared") restored = self._capture_at( publication.target.parent, parent_fd, publication.target.name, self.project.descriptor.limits.max_source_bytes, ) if not publication.backup_snapshot.renamed_to(restored): return self._recovery_conflict(publication, "restore_unconfirmed") publication.backup_snapshot = None publication.committed = False os.fsync(parent_fd) os.fsync(staging_fd) return None finally: os.close(staging_fd) os.close(parent_fd) def _rollback_create( self, publication: _CanonicalPublication, ) -> dict[str, object] | None: parent_fd = open_bound_directory(publication.target.parent) staging_fd = open_bound_directory(publication.staged.parent) try: current = self._capture_at( publication.target.parent, parent_fd, publication.target.name, self.project.descriptor.limits.max_source_bytes, ) if current is None: publication.committed = False return None if ( publication.published_snapshot is None or not publication.published_snapshot.unchanged(current) ): return self._recovery_conflict(publication, "created_target_changed") conflict = self._detach_canonical( publication, parent_fd, staging_fd, current, ) if conflict is not None: return conflict publication.committed = False publication.published_snapshot = None return None finally: os.close(staging_fd) os.close(parent_fd) def _discard_backups( self, publications: Sequence[_CanonicalPublication], ) -> list[dict[str, object]]: retained: list[dict[str, object]] = [] for publication in publications: if publication.action != "create" and publication.backup_snapshot is not None: try: staging_fd = open_bound_directory(publication.staged.parent) try: backup = self._capture_at( publication.staged.parent, staging_fd, publication.staged.name, self.project.descriptor.limits.max_source_bytes, ) finally: os.close(staging_fd) except Exception as error: conflict = self._recovery_conflict( publication, "backup_cleanup_inspection_failed", ) conflict["error"] = ( error.code if isinstance(error, DocForgeError) else type(error).__name__ ) retained.append(conflict) continue if not publication.backup_snapshot.unchanged(backup): retained.append(self._recovery_conflict(publication, "backup_cleanup_raced")) continue conflict = self._remove_private( publication, publication.staged, publication.backup_snapshot, "backup_cleanup_failed", ) if conflict is not None: retained.append(conflict) continue publication.committed = False publication.backup_snapshot = None return retained def _discard_unowned_staging( self, publications: Sequence[_CanonicalPublication], ) -> list[dict[str, object]]: retained: list[dict[str, object]] = [] for publication in publications: if publication.committed: continue conflict = self._remove_private( publication, publication.staged, publication.staged_snapshot, "staging_cleanup_failed", ) if conflict is not None: retained.append(conflict) return retained def _remove_private( self, publication: _CanonicalPublication, path: Path, expected: _CanonicalFile, reason: str, ) -> dict[str, object] | None: try: directory_fd = open_bound_directory(path.parent) try: backup = self._capture_at( path.parent, directory_fd, path.name, self.project.descriptor.limits.max_source_bytes, ) if backup is None: return None if not expected.unchanged(backup): return self._private_recovery_conflict(publication, path, reason) os.unlink(path.name, dir_fd=directory_fd) os.fsync(directory_fd) return None finally: os.close(directory_fd) except Exception as error: conflict = self._private_recovery_conflict(publication, path, reason) conflict["error"] = ( error.code if isinstance(error, DocForgeError) else type(error).__name__ ) return conflict def _stage( self, staging_root: Path, content: bytes, *, mode: int, owner: int | None, group: int | None, source: str, ) -> tuple[Path, _CanonicalFile]: descriptor, temporary_name = tempfile.mkstemp( prefix="staged-", dir=staging_root, ) temporary = Path(temporary_name) try: with os.fdopen(descriptor, "wb") as handle: handle.write(content) handle.flush() if owner is not None and group is not None: os.fchown(handle.fileno(), owner, group) os.fchmod(handle.fileno(), mode) os.fsync(handle.fileno()) snapshot = self._capture(temporary, max(1, len(content))) if snapshot is None: raise DocForgeError( "application_mismatch", "Canonical staging file disappeared", source=source, ) return temporary, snapshot except Exception: with suppress(OSError): os.close(descriptor) temporary.unlink(missing_ok=True) raise def _capture(self, path: Path, maximum: int) -> _CanonicalFile | None: parent_fd = open_bound_directory(path.parent) try: return self._capture_at(path.parent, parent_fd, path.name, maximum) finally: os.close(parent_fd) @staticmethod def _capture_at( parent: Path, parent_fd: int, name: str, maximum: int, ) -> _CanonicalFile | None: del parent try: descriptor = os.open(name, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=parent_fd) except FileNotFoundError: return None except OSError as error: raise DocForgeError( "path_escape", "Canonical target cannot be opened safely", target=name, ) from error with os.fdopen(descriptor, "rb") as handle: before = os.fstat(handle.fileno()) if not stat.S_ISREG(before.st_mode) or before.st_size > maximum: raise DocForgeError( "source_too_large", "Canonical target is invalid or exceeds its configured limit", target=name, ) content = handle.read(maximum + 1) after = os.fstat(handle.fileno()) if len(content) > maximum: raise DocForgeError( "source_too_large", "Canonical target exceeds its configured limit", target=name, ) current = os.stat(name, dir_fd=parent_fd, follow_symlinks=False) before_identity = ( before.st_dev, before.st_ino, before.st_mode, before.st_uid, before.st_gid, before.st_size, before.st_mtime_ns, before.st_ctime_ns, ) after_identity = ( after.st_dev, after.st_ino, after.st_mode, after.st_uid, after.st_gid, after.st_size, after.st_mtime_ns, after.st_ctime_ns, ) current_identity = ( current.st_dev, current.st_ino, current.st_mode, current.st_uid, current.st_gid, current.st_size, current.st_mtime_ns, current.st_ctime_ns, ) if before_identity != after_identity or before_identity != current_identity: raise DocForgeError( "base_conflict", "Canonical target changed while it was captured", target=name, ) return _CanonicalFile(*before_identity, content) def _recovery_conflict( self, publication: _CanonicalPublication, reason: str, ) -> dict[str, object]: return { "source": publication.relative, "reason": reason, "target": self._relative(publication.target), "retained": ( self._relative(publication.staged) if publication.staged.exists() else None ), } def _private_recovery_conflict( self, publication: _CanonicalPublication, path: Path, reason: str, ) -> dict[str, object]: return { "source": publication.relative, "reason": reason, "target": self._relative(publication.target), "retained": self._relative(path) if path.exists() else None, } def _relative(self, path: Path) -> str: return path.relative_to(self.project.descriptor.root).as_posix() def _target(self, relative: str) -> Path: candidate = Path(relative) if candidate.is_absolute() or ".." in candidate.parts: raise DocForgeError("path_escape", "Canonical target path is unsafe", source=relative) root = self.project.descriptor.root target = (root / candidate).resolve(strict=False) if ( not target.is_relative_to(root) or not any( target.is_relative_to(item) for item in self.project.descriptor.content_roots ) or target.suffix not in {".md", ".toml"} ): raise DocForgeError( "path_escape", "Canonical target is outside a declared content root", source=relative, ) if target.exists() and (target.is_symlink() or not target.is_file()): raise DocForgeError("path_escape", "Canonical target is not a regular file") return target def _prepare_parent(self, parent: Path, created: list[Path]) -> None: root = self.project.descriptor.root created.extend(self._create_directories_durable(parent, root=root, mode=0o755)) def _prepare_transaction_root(self) -> Path: root = self.project.descriptor.root namespace = root / ".docforge/application" self._create_directories_durable(namespace, root=root, mode=0o700) transaction = Path(tempfile.mkdtemp(prefix="transaction-", dir=namespace)) transaction.chmod(0o700) self._fsync_directory(transaction) self._fsync_directory(namespace) return transaction def _create_directories_durable( self, path: Path, *, root: Path, mode: int, ) -> list[Path]: missing: list[Path] = [] cursor = path while not cursor.exists(): missing.append(cursor) cursor = cursor.parent if cursor.is_symlink() or cursor.resolve(strict=True) != cursor or not cursor.is_dir(): raise DocForgeError("path_escape", "Canonical target parent is unsafe") if not cursor.is_relative_to(root) or not path.is_relative_to(root): raise DocForgeError("path_escape", "Canonical target parent escaped the project root") created: list[Path] = [] for directory in reversed(missing): try: directory.mkdir(mode=mode) except FileExistsError as error: if ( directory.is_symlink() or not directory.is_dir() or directory.resolve(strict=True) != directory ): raise DocForgeError( "path_escape", "Canonical target parent became unsafe during creation", ) from error continue self._fsync_directory(directory) self._fsync_directory(directory.parent) created.append(directory) if path.resolve(strict=True) != path: raise DocForgeError("path_escape", "Canonical target parent resolves unexpectedly") return created def _finish_transaction(self, transaction: Path) -> list[dict[str, object]]: try: retained = sorted( (self._relative(path) for path in transaction.iterdir()), ) except Exception as error: return [ { "reason": "transaction_inspection_failed", "retained": self._relative(transaction), "error": ( error.code if isinstance(error, DocForgeError) else type(error).__name__ ), } ] if retained: return [ { "reason": "transaction_files_retained", "retained": retained, } ] try: transaction.rmdir() self._fsync_directory(transaction.parent) except OSError as error: return [ { "reason": "transaction_cleanup_failed", "retained": self._relative(transaction), "error": type(error).__name__, } ] return [] @staticmethod def _fsync_directory(path: Path) -> None: descriptor = os.open(path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW) try: os.fsync(descriptor) finally: os.close(descriptor) def _remove_empty_directories(self, paths: Sequence[Path]) -> None: for path in reversed(paths): try: path.rmdir() self._fsync_directory(path.parent) except OSError: pass @staticmethod def _nodes_by_source(snapshot: ProjectSnapshot) -> dict[str, tuple[Node, ...]]: grouped: dict[str, list[Node]] = defaultdict(list) for node in snapshot.nodes: grouped[node.source_path].append(node) return { source: tuple(sorted(nodes, key=lambda node: node.node_id)) for source, nodes in grouped.items() } def _changed_sources( self, base: ProjectSnapshot, projected: ProjectSnapshot, ) -> set[str]: base_sources = self._source_signatures(base) projected_sources = self._source_signatures(projected) return { source for source in set(base_sources) | set(projected_sources) if base_sources.get(source) != projected_sources.get(source) } @staticmethod def _source_signatures(snapshot: ProjectSnapshot) -> dict[str, object]: outgoing: dict[str, list[tuple[str, str]]] = defaultdict(list) for edge in snapshot.edges: outgoing[edge.source_id].append((edge.relation, edge.target_id)) signatures: dict[str, list[object]] = defaultdict(list) for node in snapshot.nodes: signatures[node.source_path].append( ( node.node_id, node.title, node.family, node.authority, node.status, node.tags, node.summary, node.content, node.source_anchor, tuple(sorted(outgoing[node.node_id])), ) ) return {source: tuple(items) for source, items in signatures.items()} @classmethod def _semantic_snapshot(cls, snapshot: ProjectSnapshot) -> tuple[object, object]: nodes = tuple( ( node.node_id, node.title, node.family, node.authority, node.status, node.tags, node.summary, node.content, node.source_path, node.source_anchor, ) for node in snapshot.nodes ) edges = tuple((edge.source_id, edge.relation, edge.target_id) for edge in snapshot.edges) return nodes, edges def _serialize_source( self, snapshot: ProjectSnapshot, relative: str, nodes: tuple[Node, ...], ) -> bytes: if Path(relative).suffix == ".md": if len(nodes) != 1: raise DocForgeError( "source_conflict", "Markdown canonical sources may contain only one node", source=relative, ) node = nodes[0] metadata = self._record(snapshot, node, include_content=False) lines = ["+++", *self._toml_record(metadata), "+++", "", node.content.strip(), ""] return "\n".join(lines).encode("utf-8") lines: list[str] = [] for index, node in enumerate(nodes): if index: lines.append("") lines.append("[[nodes]]") lines.extend(self._toml_record(self._record(snapshot, node, include_content=True))) lines.append("") return "\n".join(lines).encode("utf-8") @staticmethod def _record( snapshot: ProjectSnapshot, node: Node, *, include_content: bool, ) -> dict[str, object]: record: dict[str, object] = { "schema_version": 1, "id": node.node_id, "title": node.title, "family": node.family, "authority": node.authority, "status": node.status, "tags": list(node.tags), "summary": node.summary, } if node.source_anchor is not None: record["source_anchor"] = node.source_anchor for relation in snapshot.descriptor.allowed_relations: targets = sorted( edge.target_id for edge in snapshot.edges if edge.source_id == node.node_id and edge.relation == relation ) if targets: record[relation] = targets if include_content: record["content"] = node.content return record @staticmethod def _toml_record(record: dict[str, object]) -> list[str]: lines: list[str] = [] for key, value in record.items(): if isinstance(value, int): encoded = str(value) elif isinstance(value, str): encoded = json.dumps(value, ensure_ascii=False) elif isinstance(value, list): string_items: list[str] = [] for item in cast(list[object], value): if not isinstance(item, str): raise DocForgeError( "application_mismatch", "Generic canonical list values must contain only strings", field=key, ) string_items.append(item) items = ", ".join(json.dumps(item, ensure_ascii=False) for item in string_items) encoded = f"[{items}]" else: raise DocForgeError( "application_mismatch", "Generic canonical serialization encountered an unsupported value", field=key, ) lines.append(f"{key} = {encoded}") return lines class CanonicalApplicationService: """Apply one hash-bound changeset, then refresh all declared derived state.""" def __init__( self, project: ProjectService, *, applier_id: str | None, applier: CanonicalApplier | None, index: ProjectIndex | None = None, manual_policy: ManualProjectionMode = "auto", ) -> None: self.project = project self.applier_id = applier_id self.applier = applier self.changesets = ChangesetStore(project, applier_id) self.index = index or ProjectIndex(project) self.manual_policy = validate_manual_projection_mode(manual_policy) self.rendering = RenderService( project, self.changesets, manual_policy=self.manual_policy, ) @property def enabled(self) -> bool: return self.applier_id is not None and self.applier is not None def access(self) -> dict[str, object]: return { "enabled": self.enabled, "applier": self.applier_id if self.enabled else None, } def apply(self, changeset_id: str, expected_changeset_hash: str) -> dict[str, object]: if not self.enabled or self.applier is None or self.applier_id is None: raise DocForgeError( "canonical_application_disabled", "Server has no configured canonical applier", ) applied = self.changesets.apply( changeset_id=changeset_id, expected_changeset_hash=expected_changeset_hash, applier_id=self.applier_id, application=self.applier.apply, ) refresh_errors: list[dict[str, object]] = [] index_result: dict[str, object] | None = None index_check: dict[str, object] | None = None try: index_result = self.index.build() index_check = self.index.check() except DocForgeError as error: refresh_errors.append( { "component": "index", "error": error.as_dict(), "remediation": { "tool": "docforge_sync", "arguments": {}, }, } ) renders: list[dict[str, object]] = [] config = self.project.descriptor.render render_action = "not_configured" if config is not None and self.manual_policy == "auto": render_action = "rendered" for view in config.views: try: rendered = self.rendering.render(view.view_id) renders.append(rendered) if rendered.get("state") == "degraded": receipt = rendered.get("receipt") refresh_errors.append( { "component": "render_receipt", "view_id": view.view_id, "error": ( cast(Mapping[str, object], receipt).get("error") if isinstance(receipt, dict) else { "code": "render_receipt_failure", "message": ( "Rendered output was published without a " "verification receipt" ), "details": {}, } ), } ) except DocForgeError as error: refresh_errors.append( { "component": "render", "view_id": view.view_id, "error": error.as_dict(), } ) elif config is not None: render_action = ( "skipped_explicit" if self.manual_policy == "explicit" else "skipped_disabled" ) return { **applied, "derived_refresh": { "status": "degraded" if refresh_errors else "ok", "index": index_result, "check": index_check, "renders": renders, "render_policy": { "mode": self.manual_policy, "action": render_action, }, "errors": refresh_errors, }, }