Core

@dataclass(frozen=True)
class Diagnostic:
    """A single validation finding.

    Attributes:
        level: ``"error"``, ``"warning"``, or ``"info"``.
        code: A stable machine-readable code.
        message: A human-readable, self-correction-friendly description.
        ref: The id of the offending node or edge, if any.
    """

    level: str
    code: str
    message: str
    ref: str | None = None

    def to_dict(self) -> dict[str, Any]:
        """Serialise the diagnostic.

        Returns:
            A dictionary representation.

        """
        return {"level": self.level, "code": self.code, "message": self.message, "ref": self.ref}

@dataclass
class Edge:
    """A directed, typed connection between two nodes.

    Attributes:
        type: The edge's type, from the active profile's edge vocabulary.
        source: The id of the source node.
        target: The id of the target node (a local id, or a global
            ``article_id#node_id`` address for a cross-article edge).
        id: Stable unique identifier (UUID4 hex if not supplied).
        properties: Arbitrary structured metadata about the connection.
        created_at: Timezone-aware creation timestamp (UTC).
    """

    type: str
    source: str
    target: str
    id: str = field(default_factory=lambda: uuid4().hex)
    properties: dict[str, Any] = field(default_factory=dict)
    created_at: datetime = field(default_factory=_utcnow)

    def to_dict(self) -> dict[str, Any]:
        """Serialise the edge to a JSON-compatible dictionary.

        Returns:
            A dictionary representation of the edge.

        """
        return {
            "id": self.id,
            "type": self.type,
            "source": self.source,
            "target": self.target,
            "properties": dict(self.properties),
            "created_at": self.created_at.isoformat(),
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> Edge:
        """Reconstruct an edge from its dictionary representation.

        Args:
            data: A dictionary as produced by :meth:`to_dict`.

        Returns:
            The reconstructed edge.

        Raises:
            KeyError: If ``type``, ``source``, or ``target`` is missing.

        """
        kwargs: dict[str, Any] = {
            "type": data["type"],
            "source": data["source"],
            "target": data["target"],
        }
        if "id" in data:
            kwargs["id"] = data["id"]
        if data.get("properties") is not None:
            kwargs["properties"] = dict(data["properties"])
        if data.get("created_at") is not None:
            kwargs["created_at"] = datetime.fromisoformat(data["created_at"])
        return cls(**kwargs)

@dataclass(frozen=True)
class EdgeRule:
    """Schema for an edge type.

    Attributes:
        type: The edge type name.
        source_types: Allowed source node types (empty = any).
        target_types: Allowed target node types (empty = any). Ignored for
            cross-article targets, whose node lives in another graph.
        required_properties: Property keys every edge of this type must set.
    """

    type: str
    source_types: frozenset[str] = frozenset()
    target_types: frozenset[str] = frozenset()
    required_properties: frozenset[str] = frozenset()

@dataclass
class KnowledgeGraph:
    """An in-memory collection of typed nodes and the edges between them.

    Attributes:
        nodes: Nodes held by the graph, keyed by id.
        edges: Edges held by the graph, keyed by id.
        article_id: This graph's stable article id. Nodes are addressed globally
            as ``article_id#node_id``; required before another graph can
            reference this one.
        metadata: Arbitrary graph-level metadata (e.g. ``title``).
    """

    nodes: dict[str, Node] = field(default_factory=dict)
    edges: dict[str, Edge] = field(default_factory=dict)
    article_id: str | None = None
    metadata: dict[str, Any] = field(default_factory=dict)
    _out: dict[str, list[str]] = field(default_factory=lambda: defaultdict(list), repr=False, compare=False)
    _in: dict[str, list[str]] = field(default_factory=lambda: defaultdict(list), repr=False, compare=False)

    def add_node(self, node: Node) -> Node:
        """Add or replace a node.

        Args:
            node: The node to store.

        Returns:
            The stored node.

        """
        self.nodes[node.id] = node
        return node

    def add_edge(self, edge: Edge) -> Edge:
        """Add or replace an edge and update the traversal index.

        Args:
            edge: The edge to store.

        Returns:
            The stored edge.

        """
        if edge.id in self.edges:
            self._deindex(self.edges[edge.id])
        self.edges[edge.id] = edge
        self._out[edge.source].append(edge.id)
        self._in[edge.target].append(edge.id)
        return edge

    def _deindex(self, edge: Edge) -> None:
        """Remove an edge from the traversal index.

        Args:
            edge: The edge to remove from the index.

        """
        out_ids = self._out.get(edge.source)
        if out_ids and edge.id in out_ids:
            out_ids.remove(edge.id)
        in_ids = self._in.get(edge.target)
        if in_ids and edge.id in in_ids:
            in_ids.remove(edge.id)

    def outgoing(self, node_id: str, edge_type: str | None = None) -> list[Edge]:
        """Return edges whose source is ``node_id``.

        Args:
            node_id: The id of the source node.
            edge_type: If given, only edges of this type are returned.

        Returns:
            The matching edges, in insertion order.

        """
        edges = [self.edges[eid] for eid in self._out.get(node_id, [])]
        if edge_type is not None:
            edges = [e for e in edges if e.type == edge_type]
        return edges

    def incoming(self, node_id: str, edge_type: str | None = None) -> list[Edge]:
        """Return edges whose target is ``node_id``.

        Args:
            node_id: The id of the target node.
            edge_type: If given, only edges of this type are returned.

        Returns:
            The matching edges, in insertion order.

        """
        edges = [self.edges[eid] for eid in self._in.get(node_id, [])]
        if edge_type is not None:
            edges = [e for e in edges if e.type == edge_type]
        return edges

    def nodes_of_type(self, node_type: str) -> list[Node]:
        """Return all nodes of a given type, in insertion order.

        Args:
            node_type: The node type to filter by.

        Returns:
            The matching nodes.

        """
        return [n for n in self.nodes.values() if n.type == node_type]

    def global_id(self, node_id: str) -> str:
        """Return the global address ``article_id#node_id`` for a local node.

        Args:
            node_id: A local node id.

        Returns:
            The global address.

        Raises:
            ValueError: If this graph has no ``article_id`` set.

        """
        if self.article_id is None:
            raise ValueError("graph has no article_id; set one before building global ids")
        return _global_id(self.article_id, node_id)

    def to_dict(self) -> dict[str, Any]:
        """Serialise the whole graph to a JSON-compatible dictionary.

        Returns:
            A dictionary with ``article_id``, ``metadata``, ``nodes``, and
            ``edges``.

        """
        return {
            "article_id": self.article_id,
            "metadata": dict(self.metadata),
            "nodes": [n.to_dict() for n in self.nodes.values()],
            "edges": [e.to_dict() for e in self.edges.values()],
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> KnowledgeGraph:
        """Reconstruct a graph from its dictionary representation.

        Args:
            data: A dictionary as produced by :meth:`to_dict`.

        Returns:
            The reconstructed graph, with its traversal index rebuilt.

        """
        graph = cls()
        graph.article_id = data.get("article_id")
        if data.get("metadata") is not None:
            graph.metadata = dict(data["metadata"])
        for n in data.get("nodes", []):
            graph.add_node(Node.from_dict(n))
        for e in data.get("edges", []):
            graph.add_edge(Edge.from_dict(e))
        return graph

@dataclass
class Node:
    """A single piece of information in a knowledge graph.

    Attributes:
        type: The node's type, from the active profile's vocabulary.
        text: The human-readable content of the node.
        id: Stable unique identifier (UUID4 hex if not supplied).
        tags: Free-form labels for grouping and discovery.
        properties: Arbitrary structured, domain-specific fields.
        created_at: Timezone-aware creation timestamp (UTC).
        updated_at: Timezone-aware timestamp of the last change (UTC).
    """

    type: str
    text: str = ""
    id: str = field(default_factory=lambda: uuid4().hex)
    tags: list[str] = field(default_factory=list)
    properties: dict[str, Any] = field(default_factory=dict)
    created_at: datetime = field(default_factory=_utcnow)
    updated_at: datetime = field(default_factory=_utcnow)

    def touch(self) -> None:
        """Refresh :attr:`updated_at` to now."""
        self.updated_at = _utcnow()

    def to_dict(self) -> dict[str, Any]:
        """Serialise the node to a JSON-compatible dictionary.

        Returns:
            A dictionary representation of the node.

        """
        return {
            "id": self.id,
            "type": self.type,
            "text": self.text,
            "tags": list(self.tags),
            "properties": dict(self.properties),
            "created_at": self.created_at.isoformat(),
            "updated_at": self.updated_at.isoformat(),
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> Node:
        """Reconstruct a node from its dictionary representation.

        Args:
            data: A dictionary as produced by :meth:`to_dict`.

        Returns:
            The reconstructed node.

        Raises:
            KeyError: If ``type`` is missing.

        """
        kwargs: dict[str, Any] = {"type": data["type"], "text": data.get("text", "")}
        if "id" in data:
            kwargs["id"] = data["id"]
        if data.get("tags") is not None:
            kwargs["tags"] = list(data["tags"])
        if data.get("properties") is not None:
            kwargs["properties"] = dict(data["properties"])
        if data.get("created_at") is not None:
            kwargs["created_at"] = datetime.fromisoformat(data["created_at"])
        if data.get("updated_at") is not None:
            kwargs["updated_at"] = datetime.fromisoformat(data["updated_at"])
        return cls(**kwargs)

@dataclass(frozen=True)
class NodeRule:
    """Schema for a node type.

    Attributes:
        type: The node type name.
        required_properties: Property keys every node of this type must set.
    """

    type: str
    required_properties: frozenset[str] = frozenset()

@dataclass(frozen=True)
class Profile:
    """A named schema of node and edge types plus structural rules.

    Attributes:
        name: The profile's stable name.
        node_types: Mapping of node type name to its rule.
        edge_types: Mapping of edge type name to its rule.
    """

    name: str
    node_types: dict[str, NodeRule] = field(default_factory=dict)
    edge_types: dict[str, EdgeRule] = field(default_factory=dict)

    def allows_node_type(self, node_type: str) -> bool:
        """Report whether a node type is part of this profile.

        Args:
            node_type: The node type to check.

        Returns:
            ``True`` if the type is known.

        """
        return node_type in self.node_types

    def allows_edge_type(self, edge_type: str) -> bool:
        """Report whether an edge type is part of this profile.

        Args:
            edge_type: The edge type to check.

        Returns:
            ``True`` if the type is known.

        """
        return edge_type in self.edge_types

    def validate(self, graph: KnowledgeGraph) -> list[Diagnostic]:
        """Structurally validate a graph against this profile.

        Checks that every node/edge type is known, that required properties are
        present, that edges reference existing source nodes, and that endpoint
        types satisfy the edge rule. Cross-article targets (global ids) are not
        resolved here — that is a library-level concern.

        Args:
            graph: The graph to validate.

        Returns:
            A list of diagnostics (empty if the graph conforms).

        """
        out: list[Diagnostic] = []
        for node in graph.nodes.values():
            rule = self.node_types.get(node.type)
            if rule is None:
                out.append(Diagnostic("error", "unknown-node-type", f"unknown node type {node.type!r}", node.id))
                continue
            for prop in sorted(rule.required_properties - set(node.properties)):
                out.append(Diagnostic("error", "missing-property", f"node missing property {prop!r}", node.id))
        for edge in graph.edges.values():
            out.extend(self._validate_edge(graph, edge))
        return out

    def _validate_edge(self, graph: KnowledgeGraph, edge: Any) -> list[Diagnostic]:
        """Validate a single edge against its rule.

        Args:
            graph: The graph the edge belongs to.
            edge: The edge to validate.

        Returns:
            Diagnostics for this edge.

        """
        rule = self.edge_types.get(edge.type)
        if rule is None:
            return [Diagnostic("error", "unknown-edge-type", f"unknown edge type {edge.type!r}", edge.id)]
        out: list[Diagnostic] = []
        for prop in sorted(rule.required_properties - set(edge.properties)):
            out.append(Diagnostic("error", "missing-property", f"edge missing property {prop!r}", edge.id))
        source = graph.nodes.get(edge.source)
        if source is None:
            out.append(Diagnostic("error", "edge-dangling-source", f"edge source {edge.source!r} not found", edge.id))
        elif rule.source_types and source.type not in rule.source_types:
            out.append(
                Diagnostic("error", "edge-bad-source-type", f"{edge.type!r} source may not be {source.type!r}", edge.id)
            )
        if not is_global_id(edge.target):
            target = graph.nodes.get(edge.target)
            if target is None:
                out.append(
                    Diagnostic("error", "edge-dangling-target", f"edge target {edge.target!r} not found", edge.id)
                )
            elif rule.target_types and target.type not in rule.target_types:
                out.append(
                    Diagnostic(
                        "error", "edge-bad-target-type", f"{edge.type!r} target may not be {target.type!r}", edge.id
                    )
                )
        return out

@dataclass(frozen=True)
class StaleImport:
    """A copied node whose origin has drifted since it was extracted.

    Attributes:
        node_id: The local id of the imported node.
        source_gid: The origin's global id (``article_id#node_id``).
        reason: ``"changed"`` (origin text differs from the stamp) or
            ``"missing"`` (the origin is no longer resolvable).
    """

    node_id: str
    source_gid: str
    reason: str