Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

Merge upstream main into codex/context-graph-markdown-round-trip

Saurabh Meena3b710c79d240
diff --cc CHANGELOG.md
index 86e63631,9ac9df42..e8e7096c
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -67,14 -395,14 +395,20 @@@ and this project adheres to [Semantic V
- Entities and relationships round-trip as memory-local provenance only — Markdown import intentionally does not write into `ContextGraph`, matching the MVP scope agreed on in #765
- Documented the file contract and workflow in `docs/reference/context.md`; 43 new tests in `tests/context/test_agent_memory_markdown.py` cover round-trip losslessness, idempotency, validation errors, rollback on failure, and vector-store sync ordering
+- **Markdown directory round trips for `ContextGraph`** (#852) by @SaurabhScripts
+ - `ContextGraph.save_to_file(..., format="markdown")` and `load_from_file(..., format="markdown")` persist a deterministic `graph.md` relationship manifest plus one human-editable Markdown file per node, preserving graph, node, edge, family, temporal, and cross-graph link identities
+ - Imports validate the complete directory before replacing graph state, rebuild indexes and analytics state atomically, create JSON-compatible stub nodes for dangling edge endpoints, and emit the same granular node/edge audit events as JSON loading
+ - Existing exports are replaced atomically only after their complete canonical layout is validated; untracked files, renamed node files, symlinks, Windows directory junctions, and other reparse points cause a fail-closed error instead of authorizing directory deletion
+ - Added 30 focused tests covering deterministic round trips, manual edits, validation rollback, managed-directory identity, publish rollback, audit-manager compatibility, stale-cache clearing, mocked and real Windows junctions, and missing-path behavior
+
### Fixed
+ - **`PipelineWithProvenance` raised `ModuleNotFoundError` on import and `AttributeError` on `.run()`** (#858, closes #858) by @Karunasagar12
+ - `from .pipeline import Pipeline` failed because `semantica/pipeline/pipeline.py` does not exist; corrected to `from .pipeline_builder import Pipeline`
+ - `.run()` called `self._pipeline.run()` on the `Pipeline` dataclass, which has no such method; replaced with `self._engine.execute_pipeline(self._pipeline, ...)` delegating to `ExecutionEngine`
+ - Constructor now accepts a built `Pipeline` instance (from `PipelineBuilder.build()`) instead of `**config`; the old `Pipeline(**config)` internal construction was invalid and never functional
+ - Replaced deprecated `datetime.utcnow()` with `datetime.now(timezone.utc)` in `run()`
+
- **`VectorStore.search_vectors()` returned inconsistent result shapes across backend implementations** (#853, closes #845) by @Sameer6305, reviewed by @KaifAhmad1
- Every built-in backend (FAISS, Milvus, pgvector, Pinecone, Qdrant, SQLite-vec, Weaviate, in-memory) now returns the same canonical `SearchResult` shape (`id`, `score`, `metadata`, `vector`, `distance`), instead of some backends omitting `vector`/`metadata`/`distance` or, for Weaviate, returning a backend-specific `properties` key instead of `metadata`
- Added a `SearchResult` `TypedDict` (`semantica/vector_store/vector_store.py`, exported from `semantica.vector_store`) documenting the contract; `metadata` now always defaults to `{}` rather than being absent, and `id` accepts `Union[str, int]` to accommodate Milvus/Qdrant's native integer IDs without casting
diff --cc semantica/context/context_graph.py
index cb8359c2,ac3f134f..55441fda
--- a/semantica/context/context_graph.py
+++ b/semantica/context/context_graph.py
@@@ -1132,7 -1156,10 +1240,11 @@@ class ContextGraph
self.edge_type_index.clear()
self._linked_graphs.clear()
self._unresolved_links.clear()
+ self._analytics_cache.clear()
+ # Deletion metadata belongs to the graph being replaced; keeping it
+ # would make entities in the loaded graph read as already retracted.
+ self._retractions.clear()
+ self._tombstones.clear()
if "graph_id" in data:
self.graph_id = data["graph_id"]
@@@ -1164,794 -1191,18 +1276,810 @@@
self.logger.info(f"Loaded context graph from {path}")
+ @staticmethod
+ def _normalize_persistence_format(format: str) -> str:
+ if not isinstance(format, str) or not format.strip():
+ raise ValueError("Context graph persistence format must be a string.")
+ normalized = format.strip().lower()
+ if normalized not in {"json", "markdown"}:
+ raise ValueError(
+ f"Unsupported context graph persistence format: {format!r}. "
+ "Expected 'json' or 'markdown'."
+ )
+ return normalized
+
+ def _save_markdown_directory(self, destination: Path) -> None:
+ if not destination.name:
+ raise ValueError("Markdown export destination cannot be a filesystem root.")
+ linked_component = find_filesystem_link(destination)
+ if linked_component is not None:
+ raise ValueError(
+ "Refusing to replace Markdown symbolic link or junction: "
+ f"{linked_component}"
+ )
+ if destination.exists() and not destination.is_dir():
+ raise ValueError(
+ f"Markdown export destination is not a directory: {destination}"
+ )
+ if destination.exists() and any(destination.iterdir()):
+ try:
+ self._parse_markdown_directory(
+ destination, require_canonical_layout=True
+ )
+ except (FileNotFoundError, ValueError):
+ is_managed = False
+ else:
+ is_managed = True
+ if not is_managed:
+ raise ValueError(
+ "Refusing to replace a non-empty directory that is not a "
+ f"managed ContextGraph export: {destination}"
+ )
+
+ manifest_document, node_documents = self._markdown_documents()
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ linked_component = find_filesystem_link(destination.parent)
+ if linked_component is not None:
+ raise ValueError(
+ "Refusing to export through Markdown symbolic link or junction: "
+ f"{linked_component}"
+ )
+ staging_path = Path(
+ tempfile.mkdtemp(
+ dir=str(destination.parent), prefix=f".{destination.name}.staging-"
+ )
+ )
+ backup_path: Optional[Path] = None
+ try:
+ nodes_path = staging_path / self._MARKDOWN_NODES_DIRECTORY
+ nodes_path.mkdir()
+ self._write_staged_markdown(
+ staging_path / self._MARKDOWN_MANIFEST, manifest_document
+ )
+ for filename, document in node_documents:
+ self._write_staged_markdown(nodes_path / filename, document)
+
+ if destination.exists():
+ backup_path = destination.parent / (
+ f".{destination.name}.backup-{uuid.uuid4().hex}"
+ )
+ os.replace(destination, backup_path)
+ try:
+ os.replace(staging_path, destination)
+ staging_path = None
+ except BaseException as publish_error:
+ if backup_path is not None and not destination.exists():
+ try:
+ os.replace(backup_path, destination)
+ except BaseException as restore_error:
+ self.logger.error(
+ "Failed to restore previous ContextGraph Markdown "
+ "export from %s after publish failure; preserving "
+ "the original publish error",
+ backup_path,
+ exc_info=(
+ type(restore_error),
+ restore_error,
+ restore_error.__traceback__,
+ ),
+ )
+ add_note = getattr(publish_error, "add_note", None)
+ if add_note is not None:
+ add_note(
+ "Restoring the previous ContextGraph Markdown "
+ f"export also failed: {restore_error}"
+ )
+ else:
+ backup_path = None
+ raise
+
+ if backup_path is not None:
+ shutil.rmtree(backup_path)
+ backup_path = None
+ finally:
+ if staging_path is not None:
+ shutil.rmtree(staging_path, ignore_errors=True)
+ if backup_path is not None and backup_path.exists():
+ self.logger.warning(
+ "ContextGraph export left backup directory %s", backup_path
+ )
+
+ @staticmethod
+ def _write_staged_markdown(path: Path, document: str) -> None:
+ with path.open("x", encoding="utf-8") as output:
+ output.write(document)
+ output.flush()
+ os.fsync(output.fileno())
+
+ def _markdown_documents(self) -> Tuple[str, List[Tuple[str, str]]]:
+ with self._lock:
+ nodes = [
+ {
+ "id": node.node_id,
+ "type": node.node_type,
+ "properties": copy.deepcopy(node.properties),
+ "metadata": copy.deepcopy(node.metadata),
+ "valid_from": node.valid_from,
+ "valid_until": node.valid_until,
+ "content": node.content,
+ }
+ for node in self.nodes.values()
+ ]
+ edges = [
+ {
+ "id": edge.edge_id,
+ "family_id": edge.family_id or edge.edge_id,
+ "source": edge.source_id,
+ "target": edge.target_id,
+ "type": edge.edge_type,
+ "weight": edge.weight,
+ "metadata": copy.deepcopy(edge.metadata),
+ "valid_from": edge.valid_from,
+ "valid_until": edge.valid_until,
+ }
+ for edge in self.edges
+ ]
+ graph_id = self.graph_id
+ links_by_id = {
+ link_id: copy.deepcopy(link)
+ for link_id, link in self._unresolved_links.items()
+ }
+ for link_id, (
+ other_graph,
+ source_node_id,
+ target_node_id,
+ ) in self._linked_graphs.items():
+ links_by_id[link_id] = {
+ "link_id": link_id,
+ "source_node_id": source_node_id,
+ "target_node_id": target_node_id,
+ "other_graph_id": other_graph.graph_id,
+ }
+
+ edges.sort(
+ key=lambda edge: (
+ str(edge["id"]),
+ str(edge["source"]),
+ str(edge["target"]),
+ str(edge["type"]),
+ )
+ )
+ seen_edge_ids: Set[str] = set()
+ duplicate_edge_ids: Set[str] = set()
+ for edge in edges:
+ edge_id = edge["id"]
+ if not isinstance(edge_id, str) or not edge_id.strip():
+ raise ValueError(
+ "Cannot export ContextGraph: every edge must have a string ID."
+ )
+ if edge_id in seen_edge_ids:
+ duplicate_edge_ids.add(edge_id)
+ seen_edge_ids.add(edge_id)
+ if duplicate_edge_ids:
+ duplicates = ", ".join(
+ repr(edge_id) for edge_id in sorted(duplicate_edge_ids)
+ )
+ raise ValueError(
+ f"Cannot export ContextGraph: duplicate edge ID(s): {duplicates}."
+ )
+ links = sorted(
+ links_by_id.values(), key=lambda link: str(link.get("link_id", ""))
+ )
+ manifest = {
+ "format": self._MARKDOWN_FORMAT,
+ "version": self._MARKDOWN_VERSION,
+ "graph_id": graph_id,
+ "edges": edges,
+ "links": links,
+ }
+ manifest_body = (
+ "# Context Graph\n\n"
+ "Graph relationships are stored in frontmatter. Node content is in "
+ "the `nodes` directory.\n"
+ )
+ manifest_document = self._render_markdown_document(
+ manifest, manifest_body, "graph manifest"
+ )
+
+ node_documents = []
+ filenames = set()
+ for node in sorted(nodes, key=lambda item: str(item["id"])):
+ filename = self._node_markdown_filename(node["id"])
+ normalized_filename = filename.casefold()
+ if normalized_filename in filenames:
+ raise ValueError(
+ f"Cannot export ContextGraph: duplicate filename {filename!r}."
+ )
+ filenames.add(normalized_filename)
+ content = node.pop("content")
+ node_documents.append(
+ (
+ filename,
+ self._render_markdown_document(
+ node, content, f"node {node['id']!r}"
+ ),
+ )
+ )
+ return manifest_document, node_documents
+
+ @staticmethod
+ def _node_markdown_filename(node_id: Any) -> str:
+ if not isinstance(node_id, str) or not node_id.strip():
+ raise ValueError("Cannot export a ContextGraph node without a string ID.")
+ slug = re.sub(r"[^A-Za-z0-9._-]+", "-", node_id)
+ slug = re.sub(r"-+", "-", slug).strip("._-")[:80].rstrip("._-")
+ slug = slug or "node"
+ digest = hashlib.sha256(node_id.encode("utf-8")).hexdigest()[:12]
+ return f"{slug}--{digest}.md"
+
+ @classmethod
+ def _render_markdown_document(
+ cls, frontmatter: Dict[str, Any], body: str, source: str
+ ) -> str:
+ if not isinstance(body, str):
+ raise ValueError(f"Cannot export {source}: Markdown body must be a string.")
+ canonical = cls._canonical_markdown_value(frontmatter, source)
+ try:
+ yaml_text = yaml.safe_dump(
+ canonical,
+ sort_keys=False,
+ allow_unicode=True,
+ default_flow_style=False,
+ )
+ except yaml.YAMLError as exc:
+ raise ValueError(
+ f"Cannot export {source}: metadata is not YAML serializable."
+ ) from exc
+ return f"---\n{yaml_text}---\n\n{body}"
+
+ @classmethod
+ def _canonical_markdown_value(
+ cls, value: Any, source: str, ancestors: Optional[Set[int]] = None
+ ) -> Any:
+ ancestors = set() if ancestors is None else ancestors
+ if isinstance(value, dict):
+ if any(not isinstance(key, str) for key in value):
+ raise ValueError(
+ f"Invalid Markdown metadata in {source}: "
+ "mapping keys must be strings."
+ )
+ identity = id(value)
+ if identity in ancestors:
+ raise ValueError(
+ f"Invalid Markdown metadata in {source}: "
+ "values cannot contain cycles."
+ )
+ ancestors.add(identity)
+ try:
+ return {
+ key: cls._canonical_markdown_value(
+ value[key], source, ancestors
+ )
+ for key in sorted(value)
+ }
+ finally:
+ ancestors.remove(identity)
+ if isinstance(value, list):
+ identity = id(value)
+ if identity in ancestors:
+ raise ValueError(
+ f"Invalid Markdown metadata in {source}: "
+ "values cannot contain cycles."
+ )
+ ancestors.add(identity)
+ try:
+ return [
+ cls._canonical_markdown_value(item, source, ancestors)
+ for item in value
+ ]
+ finally:
+ ancestors.remove(identity)
+ if isinstance(value, tuple) or isinstance(value, set):
+ raise ValueError(
+ f"Invalid Markdown metadata in {source}: "
+ "tuples and sets are not supported."
+ )
+ return value
+
+ def _load_markdown_directory(self, source: Path) -> None:
+ parsed_state = self._parse_markdown_directory(source)
+ graph_id, nodes_by_id, edges, unresolved_links = parsed_state
+
+ adjacency: Dict[str, List[ContextEdge]] = defaultdict(list)
++ edge_index: Dict[str, ContextEdge] = {}
+ node_type_index: Dict[str, Set[str]] = defaultdict(set)
+ edge_type_index: Dict[str, List[ContextEdge]] = defaultdict(list)
+ for node in nodes_by_id.values():
+ node_type_index[node.node_type].add(node.node_id)
+ for edge in edges:
++ edge_index[edge.edge_id] = edge
+ adjacency[edge.source_id].append(edge)
+ edge_type_index[edge.edge_type].append(edge)
+
+ with self._lock:
+ self.graph_id = graph_id
+ self.nodes.clear()
+ self.nodes.update(nodes_by_id)
+ self.edges.clear()
+ self.edges.extend(edges)
++ self._edge_index.clear()
++ self._edge_index.update(edge_index)
+ self._adjacency.clear()
+ self._adjacency.update(adjacency)
+ self.node_type_index.clear()
+ self.node_type_index.update(node_type_index)
+ self.edge_type_index.clear()
+ self.edge_type_index.update(edge_type_index)
+ self._linked_graphs.clear()
+ self._unresolved_links.clear()
+ self._unresolved_links.update(unresolved_links)
+ self._analytics_cache.clear()
++ self._retractions.clear()
++ self._tombstones.clear()
+
+ if self.mutation_callback and not self._suspend_mutation_callback:
+ mutation_events = [
+ ("ADD_NODE", node.node_id, node.to_dict())
+ for node in nodes_by_id.values()
+ ]
+ mutation_events.extend(
+ ("ADD_EDGE", edge.edge_id, edge.to_dict()) for edge in edges
+ )
+ for operation, entity_id, payload in mutation_events:
+ try:
+ self.mutation_callback(operation, entity_id, payload)
+ except Exception as exc:
+ self.logger.warning(
+ "Audit trail callback failed for Markdown graph load "
+ "%s %s: %s",
+ operation,
+ entity_id,
+ exc,
+ )
+
+ def _parse_markdown_directory(
+ self, source: Path, require_canonical_layout: bool = False
+ ) -> Tuple[
+ str,
+ Dict[str, ContextNode],
+ List[ContextEdge],
+ Dict[str, Dict[str, str]],
+ ]:
+ manifest_document, node_documents = self._read_markdown_directory(
+ source, require_canonical_layout=require_canonical_layout
+ )
+ manifest, _ = self._parse_markdown_document(
+ manifest_document, str(source / self._MARKDOWN_MANIFEST)
+ )
+ graph_id, edges, links = self._parse_markdown_manifest(manifest, source)
+
+ nodes_by_id: Dict[str, ContextNode] = {}
+ for node_source, document in node_documents:
+ frontmatter, body = self._parse_markdown_document(document, node_source)
+ node = self._parse_markdown_node(frontmatter, body, node_source)
+ if node.node_id in nodes_by_id:
+ raise ValueError(
+ f"Duplicate Markdown node ID {node.node_id!r} in {node_source}."
+ )
+ node_filename = Path(node_source).name
+ if (
+ require_canonical_layout
+ and node_filename != self._node_markdown_filename(node.node_id)
+ ):
+ raise ValueError(
+ "Invalid managed ContextGraph export: node file "
+ f"{node_filename!r} is not the canonical filename "
+ f"for node {node.node_id!r}."
+ )
+ nodes_by_id[node.node_id] = node
+
+ missing_endpoints = sorted(
+ {
+ endpoint
+ for edge in edges
+ for endpoint in (edge.source_id, edge.target_id)
+ if endpoint not in nodes_by_id
+ }
+ )
+ if missing_endpoints and require_canonical_layout:
+ missing = ", ".join(repr(endpoint) for endpoint in missing_endpoints)
+ raise ValueError(
+ "Invalid managed ContextGraph export: edge endpoint(s) "
+ f"{missing} do not have node files."
+ )
+ for endpoint in missing_endpoints:
+ nodes_by_id[endpoint] = ContextNode(endpoint, "entity", endpoint)
+
+ hierarchy_edges = [
+ {
+ "source": edge.source_id,
+ "target": edge.target_id,
+ "type": edge.edge_type,
+ }
+ for edge in edges
+ if is_skos_hierarchy_edge(edge.to_dict())
+ ]
+ if hierarchy_edges:
+ validate_skos_hierarchy(hierarchy_edges, [])
+
+ unresolved_links = {}
+ for link in links:
+ link_id = link["link_id"]
+ if link_id in unresolved_links:
+ raise ValueError(
+ f"Duplicate cross-graph link ID {link_id!r} in graph manifest."
+ )
+ if link["source_node_id"] not in nodes_by_id:
+ raise ValueError(
+ f"Cross-graph link {link_id!r} references missing source node "
+ f"{link['source_node_id']!r}."
+ )
+ unresolved_links[link_id] = link
+ return graph_id, nodes_by_id, edges, unresolved_links
+
+ def _read_markdown_directory(
+ self, source: Path, require_canonical_layout: bool = False
+ ) -> Tuple[str, List[Tuple[str, str]]]:
+ linked_component = find_filesystem_link(source)
+ if linked_component is not None:
+ raise ValueError(
+ "Refusing to import Markdown symbolic link or junction: "
+ f"{linked_component}"
+ )
+ if not source.exists():
+ raise FileNotFoundError(
+ f"ContextGraph Markdown import path does not exist: {source}"
+ )
+ if not source.is_dir():
+ raise ValueError(
+ f"ContextGraph Markdown import path is not a directory: {source}"
+ )
+
+ if require_canonical_layout:
+ expected_entries = {
+ self._MARKDOWN_MANIFEST,
+ self._MARKDOWN_NODES_DIRECTORY,
+ }
+ actual_entries = {path.name for path in source.iterdir()}
+ if actual_entries != expected_entries:
+ unexpected = sorted(actual_entries - expected_entries)
+ missing = sorted(expected_entries - actual_entries)
+ details = []
+ if unexpected:
+ details.append(f"unexpected entries: {unexpected!r}")
+ if missing:
+ details.append(f"missing entries: {missing!r}")
+ raise ValueError(
+ "Invalid managed ContextGraph export layout ("
+ + "; ".join(details)
+ + ")."
+ )
+
+ manifest_path = source / self._MARKDOWN_MANIFEST
+ manifest_document = self._read_markdown_file(manifest_path)
+ nodes_path = source / self._MARKDOWN_NODES_DIRECTORY
+ linked_component = find_filesystem_link(nodes_path)
+ if linked_component is not None:
+ raise ValueError(
+ "Refusing to import Markdown symbolic link or junction: "
+ f"{linked_component}"
+ )
+ if not nodes_path.is_dir():
+ raise ValueError(
+ f"ContextGraph Markdown nodes directory is missing: {nodes_path}"
+ )
+
+ node_paths = []
+ for path in nodes_path.iterdir():
+ linked_component = find_filesystem_link(path)
+ if linked_component is not None:
+ raise ValueError(
+ "Refusing to import Markdown symbolic link or junction: "
+ f"{linked_component}"
+ )
+ if path.suffix.lower() not in self._MARKDOWN_EXTENSIONS:
+ if require_canonical_layout:
+ raise ValueError(
+ "Invalid managed ContextGraph export: unexpected node "
+ f"entry {path.name!r}."
+ )
+ continue
+ if not path.is_file():
+ raise ValueError(f"Markdown node path is not a regular file: {path}")
+ node_paths.append(path)
+ linked_component = find_filesystem_link(nodes_path)
+ if linked_component is not None:
+ raise ValueError(
+ "Refusing to import Markdown symbolic link or junction: "
+ f"{linked_component}"
+ )
+ node_paths.sort(key=lambda path: (path.name.casefold(), path.name))
+ return manifest_document, [
+ (str(path), self._read_markdown_file(path)) for path in node_paths
+ ]
+
+ @staticmethod
+ def _read_markdown_file(path: Path) -> str:
+ linked_component = find_filesystem_link(path)
+ if linked_component is not None:
+ raise ValueError(
+ "Refusing to import Markdown symbolic link or junction: "
+ f"{linked_component}"
+ )
+ flags = os.O_RDONLY
+ if hasattr(os, "O_NOFOLLOW"):
+ flags |= os.O_NOFOLLOW
+ try:
+ descriptor = os.open(path, flags)
+ except OSError as exc:
+ linked_component = find_filesystem_link(path)
+ if exc.errno == errno.ELOOP or linked_component is not None:
+ raise ValueError(
+ "Refusing to import Markdown symbolic link or junction: "
+ f"{linked_component or path}"
+ ) from exc
+ if exc.errno == errno.ENOENT:
+ raise FileNotFoundError(f"Markdown file is missing: {path}") from exc
+ raise OSError(
+ exc.errno,
+ f"Failed to read Markdown file {path}: {exc.strerror or str(exc)}",
+ exc.filename or str(path),
+ ) from exc
+
+ try:
+ linked_component = find_filesystem_link(path)
+ if linked_component is not None:
+ raise ValueError(
+ "Refusing to import Markdown symbolic link or junction: "
+ f"{linked_component}"
+ )
+ if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+ raise ValueError(f"Markdown path is not a regular file: {path}")
+ with os.fdopen(descriptor, "r", encoding="utf-8") as input_file:
+ descriptor = None
+ return input_file.read()
+ finally:
+ if descriptor is not None:
+ os.close(descriptor)
+
+ @staticmethod
+ def _parse_markdown_document(
+ document: str, source: str
+ ) -> Tuple[Dict[str, Any], str]:
+ lines = document.splitlines(keepends=True)
+ if not lines or lines[0].rstrip("\r\n") != "---":
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: "
+ "document must start with '---'."
+ )
+ closing_index = next(
+ (
+ index
+ for index, line in enumerate(lines[1:], start=1)
+ if line.rstrip("\r\n") == "---"
+ ),
+ None,
+ )
+ if closing_index is None:
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: missing closing '---'."
+ )
+ try:
+ loaded = yaml.load(
+ "".join(lines[1:closing_index]), Loader=_UniqueKeySafeLoader
+ )
+ except yaml.YAMLError as exc:
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: {exc}"
+ ) from exc
+ frontmatter = {} if loaded is None else loaded
+ if not isinstance(frontmatter, dict):
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: expected a YAML mapping."
+ )
+ if any(not isinstance(key, str) for key in frontmatter):
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: "
+ "field names must be strings."
+ )
+
+ body = "".join(lines[closing_index + 1 :])
+ if body.startswith("\r\n"):
+ body = body[2:]
+ elif body.startswith("\n"):
+ body = body[1:]
+ return frontmatter, body
+
+ def _parse_markdown_manifest(
+ self, manifest: Dict[str, Any], source: Path
+ ) -> Tuple[str, List[ContextEdge], List[Dict[str, str]]]:
+ manifest_source = str(source / self._MARKDOWN_MANIFEST)
+ if manifest.get("format") != self._MARKDOWN_FORMAT:
+ raise ValueError(
+ f"Invalid ContextGraph Markdown manifest in {manifest_source}: "
+ f"'format' must be {self._MARKDOWN_FORMAT!r}."
+ )
+ version = manifest.get("version")
+ if isinstance(version, bool) or version != self._MARKDOWN_VERSION:
+ raise ValueError(
+ f"Unsupported ContextGraph Markdown version {version!r} in "
+ f"{manifest_source}; expected {self._MARKDOWN_VERSION}."
+ )
+ graph_id = self._required_markdown_string(
+ manifest.get("graph_id"), "graph_id", manifest_source
+ )
+
+ raw_edges = manifest.get("edges", [])
+ if not isinstance(raw_edges, list):
+ raise ValueError(
+ f"Invalid ContextGraph Markdown manifest in {manifest_source}: "
+ "'edges' must be a list."
+ )
+ edges = []
+ edge_ids = set()
+ for index, raw_edge in enumerate(raw_edges):
+ edge_source = f"{manifest_source} edge[{index}]"
+ edge = self._parse_markdown_edge(raw_edge, edge_source)
+ if edge.edge_id in edge_ids:
+ raise ValueError(
+ f"Duplicate Markdown edge ID {edge.edge_id!r} in {edge_source}."
+ )
+ edge_ids.add(edge.edge_id)
+ edges.append(edge)
+
+ raw_links = manifest.get("links", [])
+ if not isinstance(raw_links, list):
+ raise ValueError(
+ f"Invalid ContextGraph Markdown manifest in {manifest_source}: "
+ "'links' must be a list."
+ )
+ links = [
+ self._parse_markdown_link(link, f"{manifest_source} link[{index}]")
+ for index, link in enumerate(raw_links)
+ ]
+ return graph_id, edges, links
+
+ def _parse_markdown_node(
+ self, frontmatter: Dict[str, Any], body: str, source: str
+ ) -> ContextNode:
+ node_id = self._required_markdown_string(frontmatter.get("id"), "id", source)
+ node_type = self._required_markdown_string(
+ frontmatter.get("type"), "type", source
+ )
+ properties = self._markdown_mapping(
+ frontmatter.get("properties", {}), "properties", source
+ )
+ metadata = self._markdown_mapping(
+ frontmatter.get("metadata", {}), "metadata", source
+ )
+ return ContextNode(
+ node_id=node_id,
+ node_type=node_type,
+ content=body,
+ properties=properties,
+ metadata=metadata,
+ valid_from=self._markdown_temporal_value(
+ frontmatter.get("valid_from"), "valid_from", source
+ ),
+ valid_until=self._markdown_temporal_value(
+ frontmatter.get("valid_until"), "valid_until", source
+ ),
+ )
+
+ def _parse_markdown_edge(self, raw_edge: Any, source: str) -> ContextEdge:
+ if not isinstance(raw_edge, dict):
+ raise ValueError(f"Invalid Markdown edge in {source}: expected a mapping.")
+ edge_id = self._required_markdown_string(raw_edge.get("id"), "id", source)
+ family_value = raw_edge.get("family_id", raw_edge.get("familyId", edge_id))
+ family_id = self._required_markdown_string(family_value, "family_id", source)
+ source_id = self._required_markdown_string(
+ raw_edge.get("source"), "source", source
+ )
+ target_id = self._required_markdown_string(
+ raw_edge.get("target"), "target", source
+ )
+ edge_type = self._required_markdown_string(raw_edge.get("type"), "type", source)
+ weight = raw_edge.get("weight", 1.0)
+ if isinstance(weight, bool) or not isinstance(weight, (int, float)):
+ raise ValueError(
+ f"Invalid Markdown edge in {source}: 'weight' must be a number."
+ )
+ metadata = self._markdown_mapping(
+ raw_edge.get("metadata", {}), "metadata", source
+ )
+ return ContextEdge(
+ edge_id=edge_id,
+ family_id=family_id,
+ source_id=source_id,
+ target_id=target_id,
+ edge_type=edge_type,
+ weight=float(weight),
+ metadata=metadata,
+ valid_from=self._markdown_temporal_value(
+ raw_edge.get("valid_from"), "valid_from", source
+ ),
+ valid_until=self._markdown_temporal_value(
+ raw_edge.get("valid_until"), "valid_until", source
+ ),
+ )
+
+ def _parse_markdown_link(self, raw_link: Any, source: str) -> Dict[str, str]:
+ if not isinstance(raw_link, dict):
+ raise ValueError(
+ f"Invalid cross-graph link in {source}: expected a mapping."
+ )
+ return {
+ field_name: self._required_markdown_string(
+ raw_link.get(field_name), field_name, source
+ )
+ for field_name in (
+ "link_id",
+ "source_node_id",
+ "target_node_id",
+ "other_graph_id",
+ )
+ }
+
+ @staticmethod
+ def _required_markdown_string(value: Any, field_name: str, source: str) -> str:
+ if not isinstance(value, str) or not value.strip():
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: "
+ f"'{field_name}' must be a non-empty string."
+ )
+ return value
+
+ @classmethod
+ def _markdown_mapping(
+ cls, value: Any, field_name: str, source: str
+ ) -> Dict[str, Any]:
+ if value is None:
+ return {}
+ if not isinstance(value, dict):
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: "
+ f"'{field_name}' must be a mapping."
+ )
+ canonical = cls._canonical_markdown_value(value, source)
+ return dict(canonical)
+
+ @staticmethod
+ def _markdown_temporal_value(
+ value: Any, field_name: str, source: str
+ ) -> Optional[str]:
+ if value is None:
+ return None
+ if isinstance(value, datetime):
+ return _normalize_temporal_input(value)
+ if isinstance(value, date):
+ return value.isoformat()
+ if isinstance(value, str) and value.strip():
+ try:
+ _normalize_temporal_input(value)
+ except ValueError as exc:
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: "
+ f"'{field_name}' must be a valid ISO-8601 string."
+ ) from exc
+ return value
+ raise ValueError(
+ f"Invalid Markdown frontmatter in {source}: "
+ f"'{field_name}' must be a valid ISO-8601 string."
+ )
+
+
def find_node(self, node_id: str) -> Optional[Dict[str, Any]]:
- """Find a node by ID."""
+ """Return a dict representation of the node identified by *node_id*.
+
+ Returns ``None`` when the node does not exist.
+
+ Args:
+ node_id: ID of the node to look up.
+
+ Returns:
+ A dict with keys ``id``, ``type``, ``content``, and ``metadata``,
+ or ``None`` if the node is not found.
+ """
with self._lock:
node = self.nodes.get(node_id)
if node:
diff --cc tests/context/test_context_graph_markdown.py
index f81dce3b,00000000..538421f3
mode 100644,000000..100644
--- a/tests/context/test_context_graph_markdown.py
+++ b/tests/context/test_context_graph_markdown.py
@@@ -1,708 -1,0 +1,713 @@@
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+import pytest
+import yaml
+
+import semantica.context.context_graph as context_graph_module
+from semantica.change_management.managers import TemporalVersionManager
+from semantica.context.context_graph import ContextEdge, ContextGraph, ContextNode
+
+
+def _read_markdown(path: Path):
+ lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+ closing_index = next(
+ index
+ for index, line in enumerate(lines[1:], start=1)
+ if line.rstrip("\r\n") == "---"
+ )
+ frontmatter = yaml.safe_load("".join(lines[1:closing_index])) or {}
+ body = "".join(lines[closing_index + 1 :])
+ if body.startswith("\r\n"):
+ body = body[2:]
+ elif body.startswith("\n"):
+ body = body[1:]
+ return frontmatter, body
+
+
+def _write_markdown(path: Path, frontmatter, body: str) -> None:
+ yaml_text = yaml.safe_dump(
+ frontmatter,
+ sort_keys=False,
+ allow_unicode=True,
+ default_flow_style=False,
+ )
+ path.write_text(f"---\n{yaml_text}---\n\n{body}", encoding="utf-8")
+
+
+def _node_file(export_path: Path, node_id: str) -> Path:
+ for path in (export_path / "nodes").glob("*.md"):
+ frontmatter, _ = _read_markdown(path)
+ if frontmatter.get("id") == node_id:
+ return path
+ raise AssertionError(f"No Markdown file found for node {node_id!r}")
+
+
+def _normalized_state(graph: ContextGraph):
+ links = {link_id: dict(link) for link_id, link in graph._unresolved_links.items()}
+ for link_id, (
+ other_graph,
+ source_node_id,
+ target_node_id,
+ ) in graph._linked_graphs.items():
+ links[link_id] = {
+ "link_id": link_id,
+ "source_node_id": source_node_id,
+ "target_node_id": target_node_id,
+ "other_graph_id": other_graph.graph_id,
+ }
+ return {
+ "graph_id": graph.graph_id,
+ "nodes": {
+ node_id: {
+ "type": node.node_type,
+ "content": node.content,
+ "properties": node.properties,
+ "metadata": node.metadata,
+ "valid_from": node.valid_from,
+ "valid_until": node.valid_until,
+ }
+ for node_id, node in graph.nodes.items()
+ },
+ "edges": sorted(
+ (
+ {
+ "id": edge.edge_id,
+ "family_id": edge.family_id,
+ "source": edge.source_id,
+ "target": edge.target_id,
+ "type": edge.edge_type,
+ "weight": edge.weight,
+ "metadata": edge.metadata,
+ "valid_from": edge.valid_from,
+ "valid_until": edge.valid_until,
+ }
+ for edge in graph.edges
+ ),
+ key=lambda edge: edge["id"],
+ ),
+ "links": links,
+ }
+
+
+def _sample_graph():
+ graph = ContextGraph(advanced_analytics=False)
+ graph.graph_id = "graph-primary"
+ graph._add_internal_node(
+ ContextNode(
+ node_id="policy/\u6771\u4eac",
+ node_type="Policy",
+ content="# Retention\n\nKeep evidence.\n---\n",
+ properties={"priority": 2, "nested": {"owner": "governance"}},
+ metadata={"source": "manual", "tags": ["retention", "legal"]},
+ valid_from="2026-01-01T00:00:00+00:00",
+ valid_until="2027-01-01T00:00:00+00:00",
+ )
+ )
+ graph._add_internal_node(
+ ContextNode(
+ node_id="evidence-1",
+ node_type="Evidence",
+ content="Original source",
+ properties={"checksum": "abc123"},
+ metadata={"classification": "internal"},
+ )
+ )
+ graph._add_internal_edge(
+ ContextEdge(
+ edge_id="edge-supports",
+ family_id="family-supports",
+ source_id="evidence-1",
+ target_id="policy/\u6771\u4eac",
+ edge_type="SUPPORTS",
+ weight=0.75,
+ metadata={"confidence": 0.9},
+ valid_from="2026-02-01",
+ valid_until="2026-12-31",
+ )
+ )
+
+ other = ContextGraph(advanced_analytics=False)
+ other.graph_id = "graph-secondary"
+ other.add_node("source-page", "Page", "Source page")
+ link_id = graph.link_graph(other, "policy/\u6771\u4eac", "source-page")
+ return graph, other, link_id
+
+
+def _directory_contents(path: Path):
+ return {
+ str(file_path.relative_to(path)): file_path.read_bytes()
+ for file_path in path.rglob("*")
+ if file_path.is_file()
+ }
+
+
+def test_markdown_round_trip_preserves_complete_graph_state(tmp_path):
+ graph, other, link_id = _sample_graph()
+ export_path = tmp_path / "context-graph"
+
+ graph.save_to_file(export_path, format="markdown")
+
+ restored = ContextGraph(advanced_analytics=False)
+ restored.load_from_file(export_path, format="markdown")
+
+ assert _normalized_state(restored) == _normalized_state(graph)
+ assert restored.resolve_links({other.graph_id: other}) == 1
+ linked_graph, entry_node = restored.navigate_to(link_id)
+ assert linked_graph is other
+ assert entry_node == "source-page"
+
+
+def test_markdown_manual_node_and_edge_edits_are_imported(tmp_path):
+ graph, _, _ = _sample_graph()
+ export_path = tmp_path / "context-graph"
+ graph.save_to_file(export_path, format="markdown")
+
+ node_path = _node_file(export_path, "policy/\u6771\u4eac")
+ node_frontmatter, _ = _read_markdown(node_path)
+ node_frontmatter["metadata"]["reviewed"] = True
+ _write_markdown(node_path, node_frontmatter, "# Updated policy\n")
+
+ manifest_path = export_path / "graph.md"
+ manifest, manifest_body = _read_markdown(manifest_path)
+ manifest["edges"][0]["type"] = "VERIFIES"
+ manifest["edges"][0]["weight"] = 1.0
+ manifest["edges"][0]["metadata"]["reviewed_by"] = "human"
+ _write_markdown(manifest_path, manifest, manifest_body)
+
+ restored = ContextGraph(advanced_analytics=False)
+ restored.load_from_file(export_path, format="markdown")
+
+ node = restored.nodes["policy/\u6771\u4eac"]
+ assert node.content == "# Updated policy\n"
+ assert node.metadata["reviewed"] is True
+ edge = restored.edges[0]
+ assert edge.edge_type == "VERIFIES"
+ assert edge.weight == 1.0
+ assert edge.metadata["reviewed_by"] == "human"
+
+
+def test_markdown_export_is_deterministic_and_removes_stale_nodes(tmp_path):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.graph_id = "deterministic-graph"
+ graph.add_node("kept", "Note", "Keep")
+ graph.add_node("removed", "Note", "Remove")
+ graph.add_edge("kept", "removed", "REFERENCES")
+ first = tmp_path / "first"
+ second = tmp_path / "second"
+
+ graph.save_to_file(first, format="markdown")
+ graph.save_to_file(second, format="markdown")
+ assert _directory_contents(first) == _directory_contents(second)
+
+ stale_path = _node_file(first, "removed")
+ graph.nodes.pop("removed")
+ graph.edges.clear()
+ graph.save_to_file(first, format="markdown")
+
+ assert not stale_path.exists()
+ restored = ContextGraph(advanced_analytics=False)
+ restored.load_from_file(first, format="markdown")
+ assert set(restored.nodes) == {"kept"}
+ assert restored.edges == []
+
+
+def test_markdown_empty_graph_round_trip(tmp_path):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.graph_id = "empty-graph"
+ export_path = tmp_path / "empty"
+
+ graph.save_to_file(export_path, format="markdown")
+ restored = ContextGraph(advanced_analytics=False)
+ restored.load_from_file(export_path, format="markdown")
+
+ assert restored.graph_id == "empty-graph"
+ assert restored.nodes == {}
+ assert restored.edges == []
+
+
+def test_markdown_export_rejects_duplicate_edge_ids_before_writing(tmp_path):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("source", "Note", "Source")
+ graph.add_node("target", "Note", "Target")
+ graph.add_edge("source", "target", "REFERENCES")
- graph.add_edge("source", "target", "REFERENCES")
++ graph.edges.append(graph.edges[0])
+ export_path = tmp_path / "graph"
+
+ assert graph.edges[0].edge_id == graph.edges[1].edge_id
+ with pytest.raises(ValueError, match=r"duplicate edge ID.*[0-9a-f-]+"):
+ graph.save_to_file(export_path, format="markdown")
+
+ assert not export_path.exists()
+
+
+ "corruption, expected_error",
+ [
+ ("unsupported-version", "Unsupported ContextGraph Markdown version"),
+ ("duplicate-edge", "Duplicate Markdown edge ID"),
+ ("duplicate-node", "Duplicate Markdown node ID"),
+ ("cyclic-skos", "SKOS hierarchy contains a cycle"),
+ ],
+)
+def test_invalid_markdown_does_not_mutate_existing_graph(
+ tmp_path, corruption, expected_error
+):
+ source, _, _ = _sample_graph()
+ export_path = tmp_path / corruption
+ source.save_to_file(export_path, format="markdown")
+
+ manifest_path = export_path / "graph.md"
+ manifest, manifest_body = _read_markdown(manifest_path)
+ if corruption == "unsupported-version":
+ manifest["version"] = 2
+ elif corruption == "duplicate-edge":
+ manifest["edges"].append(dict(manifest["edges"][0]))
+ elif corruption == "duplicate-node":
+ original = _node_file(export_path, "evidence-1")
+ (original.parent / "duplicate.md").write_bytes(original.read_bytes())
+ elif corruption == "cyclic-skos":
+ manifest["edges"] = [
+ {
+ "id": "broader-1",
+ "family_id": "broader-1",
+ "source": "evidence-1",
+ "target": "policy/\u6771\u4eac",
+ "type": "skos:broader",
+ "weight": 1.0,
+ "metadata": {},
+ },
+ {
+ "id": "broader-2",
+ "family_id": "broader-2",
+ "source": "policy/\u6771\u4eac",
+ "target": "evidence-1",
+ "type": "skos:broader",
+ "weight": 1.0,
+ "metadata": {},
+ },
+ ]
+ _write_markdown(manifest_path, manifest, manifest_body)
+
+ target = ContextGraph(advanced_analytics=False)
+ target.add_node("sentinel", "Existing", "Do not replace")
+ before = _normalized_state(target)
+
+ with pytest.raises(ValueError, match=expected_error):
+ target.load_from_file(export_path, format="markdown")
+
+ assert _normalized_state(target) == before
+
+
+def test_markdown_import_creates_json_compatible_stub_nodes_for_dangling_edges(
+ tmp_path,
+):
+ source, _, _ = _sample_graph()
+ export_path = tmp_path / "dangling-edge"
+ source.save_to_file(export_path, format="markdown")
+ manifest_path = export_path / "graph.md"
+ manifest, manifest_body = _read_markdown(manifest_path)
+ manifest["edges"][0]["target"] = "missing-node"
+ _write_markdown(manifest_path, manifest, manifest_body)
+
+ restored = ContextGraph(advanced_analytics=False)
+ restored.load_from_file(export_path, format="markdown")
+
+ stub = restored.nodes["missing-node"]
+ assert stub.node_type == "entity"
+ assert stub.content == "missing-node"
+ assert any(edge.target_id == "missing-node" for edge in restored.edges)
+
+
+ ("location", "field_name"),
+ [("node", "valid_from"), ("edge", "valid_until")],
+)
+def test_invalid_markdown_temporal_value_does_not_mutate_existing_graph(
+ tmp_path, location, field_name
+):
+ source, _, _ = _sample_graph()
+ export_path = tmp_path / location
+ source.save_to_file(export_path, format="markdown")
+
+ if location == "node":
+ document_path = _node_file(export_path, "policy/\u6771\u4eac")
+ else:
+ document_path = export_path / "graph.md"
+ frontmatter, body = _read_markdown(document_path)
+ if location == "node":
+ frontmatter[field_name] = "not-a-date"
+ else:
+ frontmatter["edges"][0][field_name] = "not-a-date"
+ _write_markdown(document_path, frontmatter, body)
+
+ target = ContextGraph(advanced_analytics=False)
+ target.add_node("sentinel", "Existing", "Do not replace")
+ before = _normalized_state(target)
+
+ with pytest.raises(ValueError, match=rf"'{field_name}'.*valid ISO-8601"):
+ target.load_from_file(export_path, format="markdown")
+
+ assert _normalized_state(target) == before
+
+
+def test_duplicate_yaml_keys_are_rejected(tmp_path):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("node-1", "Note", "Body")
+ export_path = tmp_path / "graph"
+ graph.save_to_file(export_path, format="markdown")
+ node_path = _node_file(export_path, "node-1")
+ document = node_path.read_text(encoding="utf-8")
+ node_path.write_text(document.replace("id: node-1", "id: node-1\nid: duplicate"))
+
+ with pytest.raises(ValueError, match="duplicate key 'id'"):
+ ContextGraph(advanced_analytics=False).load_from_file(
+ export_path, format="markdown"
+ )
+
+
+def test_markdown_export_refuses_unmanaged_nonempty_directory(tmp_path):
+ destination = tmp_path / "existing"
+ destination.mkdir()
+ marker = destination / "keep.txt"
+ marker.write_text("keep", encoding="utf-8")
+
+ with pytest.raises(ValueError, match="not a managed ContextGraph export"):
+ ContextGraph(advanced_analytics=False).save_to_file(
+ destination, format="markdown"
+ )
+
+ assert marker.read_text(encoding="utf-8") == "keep"
+
+
+def test_markdown_export_rejects_unrelated_graph_markdown_file(tmp_path):
+ destination = tmp_path / "existing"
+ destination.mkdir()
+ unrelated = destination / "graph.md"
+ _write_markdown(unrelated, {"title": "Unrelated notes"}, "Keep me")
+
+ with pytest.raises(ValueError, match="not a managed ContextGraph export"):
+ ContextGraph(advanced_analytics=False).save_to_file(
+ destination, format="markdown"
+ )
+
+ assert unrelated.exists()
+
+
[email protected]("extra_location", ["root", "nodes"])
+def test_markdown_export_refuses_managed_directory_with_untracked_files(
+ tmp_path, extra_location
+):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("node-1", "Note", "Body")
+ destination = tmp_path / "existing"
+ graph.save_to_file(destination, format="markdown")
+ parent = destination if extra_location == "root" else destination / "nodes"
+ human_file = parent / "human-notes.txt"
+ human_file.write_text("do not delete", encoding="utf-8")
+ original_contents = _directory_contents(destination)
+
+ with pytest.raises(ValueError, match="not a managed ContextGraph export"):
+ graph.save_to_file(destination, format="markdown")
+
+ assert _directory_contents(destination) == original_contents
+
+
+def test_markdown_export_refuses_noncanonical_node_layout(tmp_path):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("node-1", "Note", "Body")
+ destination = tmp_path / "existing"
+ graph.save_to_file(destination, format="markdown")
+ canonical = _node_file(destination, "node-1")
+ renamed = canonical.with_name("human-name.md")
+ canonical.rename(renamed)
+ original_contents = _directory_contents(destination)
+
+ with pytest.raises(ValueError, match="not a managed ContextGraph export"):
+ graph.save_to_file(destination, format="markdown")
+
+ assert _directory_contents(destination) == original_contents
+
+
+def test_markdown_export_preserves_manifest_inspection_errors(tmp_path, monkeypatch):
+ graph = ContextGraph(advanced_analytics=False)
+ destination = tmp_path / "existing"
+ graph.save_to_file(destination, format="markdown")
+ real_reader = ContextGraph._read_markdown_file
+
+ def fail_manifest_read(path):
+ if path == destination / "graph.md":
+ raise PermissionError("permission denied")
+ return real_reader(path)
+
+ monkeypatch.setattr(
+ ContextGraph, "_read_markdown_file", staticmethod(fail_manifest_read)
+ )
+
+ with pytest.raises(PermissionError, match="permission denied"):
+ graph.save_to_file(destination, format="markdown")
+
+
+def test_markdown_export_restores_previous_directory_when_publish_fails(
+ tmp_path, monkeypatch
+):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("original", "Note", "Original")
+ destination = tmp_path / "graph"
+ graph.save_to_file(destination, format="markdown")
+ original_contents = _directory_contents(destination)
+ graph.add_node("new", "Note", "New")
+
+ real_replace = context_graph_module.os.replace
+
+ def fail_staged_publish(source, target):
+ if ".staging-" in Path(source).name and Path(target) == destination:
+ raise OSError("simulated publish failure")
+ return real_replace(source, target)
+
+ monkeypatch.setattr(context_graph_module.os, "replace", fail_staged_publish)
+
+ with pytest.raises(OSError, match="simulated publish failure"):
+ graph.save_to_file(destination, format="markdown")
+
+ assert _directory_contents(destination) == original_contents
+ assert not list(tmp_path.glob(".graph.staging-*"))
+ assert not list(tmp_path.glob(".graph.backup-*"))
+
+
+def test_markdown_export_preserves_publish_error_when_restore_fails(
+ tmp_path, monkeypatch, caplog
+):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("original", "Note", "Original")
+ destination = tmp_path / "graph"
+ graph.save_to_file(destination, format="markdown")
+ original_contents = _directory_contents(destination)
+ graph.add_node("new", "Note", "New")
+
+ real_replace = context_graph_module.os.replace
+
+ def fail_publish_and_restore(source, target):
+ source_path = Path(source)
+ if ".staging-" in source_path.name and Path(target) == destination:
+ raise OSError("simulated publish failure")
+ if ".backup-" in source_path.name and Path(target) == destination:
+ raise PermissionError("simulated restore failure")
+ return real_replace(source, target)
+
+ monkeypatch.setattr(context_graph_module.os, "replace", fail_publish_and_restore)
+ caplog.set_level("ERROR")
+
+ with pytest.raises(OSError, match="simulated publish failure"):
+ graph.save_to_file(destination, format="markdown")
+
+ assert "preserving the original publish error" in caplog.text
+ assert "simulated restore failure" in caplog.text
+ assert not destination.exists()
+ backup_paths = list(tmp_path.glob(".graph.backup-*"))
+ assert len(backup_paths) == 1
+ assert _directory_contents(backup_paths[0]) == original_contents
+ assert not list(tmp_path.glob(".graph.staging-*"))
+
+
+def test_markdown_load_rebuilds_indexes_and_emits_json_compatible_events(tmp_path):
+ source, _, _ = _sample_graph()
+ destination = tmp_path / "graph"
+ source.save_to_file(destination, format="markdown")
+ events = []
+ target = ContextGraph(
+ advanced_analytics=False,
+ mutation_callback=lambda *event: events.append(event),
+ )
++ target._retractions[("node", "stale")] = {"entity_id": "stale"}
++ target._tombstones[("edge", "stale")] = {"entity_id": "stale"}
+
+ target.load_from_file(destination, format="markdown")
+
+ assert target.node_type_index["Policy"] == {"policy/\u6771\u4eac"}
+ assert target.edge_type_index["SUPPORTS"][0].edge_id == "edge-supports"
++ assert target._edge_index["edge-supports"].edge_type == "SUPPORTS"
+ assert target._adjacency["evidence-1"][0].target_id == "policy/\u6771\u4eac"
++ assert target._retractions == {}
++ assert target._tombstones == {}
+ assert [event[0] for event in events] == ["ADD_NODE"] * len(target.nodes) + [
+ "ADD_EDGE"
+ ] * len(target.edges)
+ assert {event[1] for event in events if event[0] == "ADD_NODE"} == set(target.nodes)
+ assert {event[1] for event in events if event[0] == "ADD_EDGE"} == {
+ edge.edge_id for edge in target.edges
+ }
+
+
+def test_markdown_load_records_granular_change_manager_history(tmp_path):
+ source, _, _ = _sample_graph()
+ destination = tmp_path / "graph"
+ source.save_to_file(destination, format="markdown")
+ target = ContextGraph(advanced_analytics=False)
+ manager = TemporalVersionManager()
+ manager.attach_to_graph(target)
+
+ target.load_from_file(destination, format="markdown")
+
+ assert manager.get_node_history("evidence-1")[0]["operation"] == "ADD_NODE"
+ assert manager.get_node_history("edge-supports")[0]["operation"] == "ADD_EDGE"
+
+
+def test_markdown_export_rejects_recursive_metadata(tmp_path):
+ recursive = {}
+ recursive["self"] = recursive
+ graph = ContextGraph(advanced_analytics=False)
+ graph._add_internal_node(ContextNode("node-1", "Note", "Body", metadata=recursive))
+
+ with pytest.raises(ValueError, match="values cannot contain cycles"):
+ graph.save_to_file(tmp_path / "graph", format="markdown")
+
+
+def test_markdown_import_and_export_reject_symlinks(tmp_path):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("node-1", "Note", "Body")
+ real_export = tmp_path / "real"
+ graph.save_to_file(real_export, format="markdown")
+
+ directory_link = tmp_path / "directory-link"
+ try:
+ directory_link.symlink_to(real_export, target_is_directory=True)
+ except (NotImplementedError, OSError):
+ pytest.skip("Symbolic links are not available on this platform")
+
+ with pytest.raises(ValueError, match="symbolic link"):
+ ContextGraph(advanced_analytics=False).load_from_file(
+ directory_link, format="markdown"
+ )
+ with pytest.raises(ValueError, match="symbolic link"):
+ graph.save_to_file(directory_link, format="markdown")
+
+ manifest_path = real_export / "graph.md"
+ manifest_target = tmp_path / "manifest.md"
+ manifest_target.write_bytes(manifest_path.read_bytes())
+ manifest_path.unlink()
+ manifest_path.symlink_to(manifest_target)
+ with pytest.raises(ValueError, match="symbolic link"):
+ ContextGraph(advanced_analytics=False).load_from_file(
+ real_export, format="markdown"
+ )
+
+
+def test_markdown_import_and_export_reject_windows_junctions(tmp_path, monkeypatch):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("node-1", "Note", "Body")
+ export_path = tmp_path / "junction"
+ graph.save_to_file(export_path, format="markdown")
+
+ monkeypatch.setattr(
+ os.path,
+ "isjunction",
+ lambda candidate: Path(candidate) == export_path,
+ raising=False,
+ )
+
+ with pytest.raises(ValueError, match="junction"):
+ ContextGraph(advanced_analytics=False).load_from_file(
+ export_path, format="markdown"
+ )
+ with pytest.raises(ValueError, match="junction"):
+ graph.save_to_file(export_path, format="markdown")
+
+
+def test_markdown_import_rejects_windows_reparse_point_fallback(tmp_path, monkeypatch):
+ source = tmp_path / "reparse-point"
+ source.mkdir()
+ real_lstat = os.lstat
+
+ class ReparseStat:
+ st_file_attributes = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+
+ monkeypatch.delattr(os.path, "isjunction", raising=False)
+ monkeypatch.setattr(Path, "is_symlink", lambda self: False)
+ monkeypatch.setattr(
+ os,
+ "lstat",
+ lambda candidate: (
+ ReparseStat() if Path(candidate) == source else real_lstat(candidate)
+ ),
+ )
+
+ with pytest.raises(ValueError, match="junction"):
+ ContextGraph(advanced_analytics=False).load_from_file(source, format="markdown")
+
+
[email protected](os.name != "nt", reason="requires Windows junctions")
+def test_markdown_import_rejects_real_windows_junction(tmp_path):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("node-1", "Note", "Body")
+ outside = tmp_path / "outside"
+ graph.save_to_file(outside, format="markdown")
+ source = tmp_path / "junction"
+ result = subprocess.run(
+ ["cmd.exe", "/c", "mklink", "/J", str(source), str(outside)],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ if result.returncode != 0:
+ pytest.skip(f"could not create Windows junction: {result.stderr}")
+
+ try:
+ with pytest.raises(ValueError, match="junction"):
+ ContextGraph(advanced_analytics=False).load_from_file(
+ source, format="markdown"
+ )
+ finally:
+ os.rmdir(source)
+
+
+ not hasattr(context_graph_module.os, "O_NOFOLLOW"),
+ reason="O_NOFOLLOW is unavailable on this platform",
+)
+def test_markdown_import_nofollow_check_closes_symlink_race(tmp_path, monkeypatch):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("node-1", "Note", "Body")
+ export_path = tmp_path / "graph"
+ graph.save_to_file(export_path, format="markdown")
+ node_path = _node_file(export_path, "node-1")
+ target = tmp_path / "target.md"
+ target.write_bytes(node_path.read_bytes())
+ node_path.unlink()
+ node_path.symlink_to(target)
+
+ real_is_symlink = Path.is_symlink
+
+ def miss_precheck(path):
+ if path == node_path:
+ return False
+ return real_is_symlink(path)
+
+ monkeypatch.setattr(Path, "is_symlink", miss_precheck)
+
+ with pytest.raises(ValueError, match="symbolic link"):
+ ContextGraph(advanced_analytics=False).load_from_file(
+ export_path, format="markdown"
+ )
+
+
+def test_json_remains_default_and_unknown_format_is_rejected(tmp_path):
+ graph = ContextGraph(advanced_analytics=False)
+ graph.add_node("node-1", "Note", "Body")
+ json_path = tmp_path / "graph.json"
+ graph.save_to_file(json_path)
+
+ restored = ContextGraph(advanced_analytics=False)
+ restored._analytics_cache["stale"] = {"value": True}
+ restored.load_from_file(json_path)
+ assert "node-1" in restored.nodes
+ assert restored._analytics_cache == {}
+
+ before = _normalized_state(restored)
+ restored.load_from_file(tmp_path / "missing", format="markdown")
+ assert _normalized_state(restored) == before
+
+ with pytest.raises(ValueError, match="Unsupported context graph"):
+ graph.save_to_file(tmp_path / "graph", format="html")