"""Class-driven problem and runtime trouble definitions for compartments.
Every compartment declares what it is (SCHEMA, COMMANDS, NEEDS, STORES,
WORKERS, EVERY, CHANNELS, METRICS, LIFECYCLE). When a declaration is invalid,
`declaration_problems` collects `Problem` instances rather than loose strings,
carrying the surface, semantic code, target, and human-readable message.
Similarly, when a compartment is in an abnormal state, `trouble()` returns
`Trouble` instances carrying the fault code, severity, timestamp, and optional
remediation hint.
Both `Problem` and `Trouble` inherit from `str` so that:
- String formatting (`str(p)`, `f"{p}"`) produces the sentence directly.
- Substring checks (`'twice' in p`, `'relay' in t`) continue to pass.
- List comparisons (`[p] == ['message']`) evaluate True against raw strings.
- Existing callers, tests, and json encoders require zero breaking changes.
"""
from __future__ import annotations
from typing import Any, Mapping, Optional, TypeVar, TypedDict
P = TypeVar('P', bound='Problem')
T_tr = TypeVar('T_tr', bound='Trouble')
[docs]class ProblemDict(TypedDict, total=False):
"""Concrete dictionary structure for a declaration problem."""
message: str
surface: str
code: str
target: str
hint: Optional[str]
reference: str
expected: str
got: str
owner: str
[docs]class Problem(str):
"""A structured declaration problem.
Subclasses str for complete backwards compatibility with tests and callers
expecting str messages, while exposing structured metadata for linters,
checkers, and IDE diagnostics.
"""
surface: str
code: str
target: str
message: str
hint: Optional[str]
[docs] def __new__(
cls: type[P],
message: str,
*,
surface: str = '',
code: str = '',
target: str = '',
hint: Optional[str] = None,
) -> P:
obj = super().__new__(cls, message)
obj.surface = str(surface)
obj.code = str(code)
obj.target = str(target)
obj.message = str(message)
obj.hint = hint
return obj
[docs] def to_dict(self) -> ProblemDict:
"""Dictionary representation for structured reporting."""
d: ProblemDict = {
'message': self.message,
'surface': self.surface,
'code': self.code,
}
if self.target:
d['target'] = self.target
if self.hint is not None:
d['hint'] = self.hint
return d
[docs]class DuplicateProblem(Problem):
"""An item was declared twice on the same surface."""
[docs] def __new__(
cls,
surface: str,
target: str,
message: Optional[str] = None,
hint: Optional[str] = None,
) -> DuplicateProblem:
msg = message if message is not None else f"{surface} declares {target!r} twice"
return super().__new__(
cls,
msg,
surface=surface,
code='duplicate',
target=target,
hint=hint or 'remove or rename the duplicate declaration',
)
[docs]class InvalidIdentifierProblem(Problem):
"""An identifier name does not follow the required naming pattern."""
[docs] def __new__(
cls,
surface: str,
target: str,
message: Optional[str] = None,
hint: Optional[str] = None,
) -> InvalidIdentifierProblem:
msg = message if message is not None else f"{surface} identifier {target!r} is not a valid identifier"
return super().__new__(
cls,
msg,
surface=surface,
code='invalid_identifier',
target=target,
hint=hint or 'identifiers must start with a letter/underscore and contain only alphanumeric characters',
)
[docs]class ReferenceProblem(Problem):
"""A declaration references an entity that is unknown or missing."""
reference: str
[docs] def __new__(
cls,
surface: str,
target: str,
reference: str,
message: Optional[str] = None,
hint: Optional[str] = None,
) -> ReferenceProblem:
msg = message if message is not None else f"{surface} {target} references unknown {reference!r}"
obj = super().__new__(
cls,
msg,
surface=surface,
code='unknown_reference',
target=target,
hint=hint,
)
obj.reference = str(reference)
return obj
[docs] def to_dict(self) -> ProblemDict:
d = super().to_dict()
d['reference'] = self.reference
return d
[docs]class TypeMismatchProblem(Problem):
"""A declaration entry has the wrong type or does not implement the expected class."""
expected: str
got: str
[docs] def __new__(
cls,
surface: str,
expected: str,
got: str,
message: Optional[str] = None,
hint: Optional[str] = None,
) -> TypeMismatchProblem:
msg = message if message is not None else f"{surface} holds {expected}, not {got}"
obj = super().__new__(
cls,
msg,
surface=surface,
code='type_mismatch',
target=got,
hint=hint or f"use instances of {expected}",
)
obj.expected = str(expected)
obj.got = str(got)
return obj
[docs] def to_dict(self) -> ProblemDict:
d = super().to_dict()
d['expected'] = self.expected
d['got'] = self.got
return d
[docs]class ShadowingProblem(Problem):
"""A declared key would shadow a method or class attribute."""
owner: str
[docs] def __new__(
cls,
surface: str,
target: str,
owner: str,
message: Optional[str] = None,
hint: Optional[str] = None,
) -> ShadowingProblem:
msg = message if message is not None else f"{surface} {target} would shadow {owner}.{target}; pick another key"
obj = super().__new__(
cls,
msg,
surface=surface,
code='shadows_attribute',
target=target,
hint=hint or 'pick another key to avoid overwriting attributes',
)
obj.owner = str(owner)
return obj
[docs] def to_dict(self) -> ProblemDict:
d = super().to_dict()
d['owner'] = self.owner
return d
[docs]class IncompatibleProblem(Problem):
"""Two declarations or declarations and method implementations are incompatible."""
[docs] def __new__(
cls,
surface: str,
target: str,
message: str,
hint: Optional[str] = None,
) -> IncompatibleProblem:
return super().__new__(
cls,
message,
surface=surface,
code='incompatible',
target=target,
hint=hint,
)
[docs]class Problems(list[Any]):
"""A list of Problem instances providing query methods and surface filtering."""
[docs] def for_surface(self, surface: str) -> list[Problem]:
"""Return all problems recorded for a specific declaration surface."""
return [p for p in self if isinstance(p, Problem) and p.surface == surface]
[docs] def by_code(self, code: str) -> list[Problem]:
"""Return all problems with a specific semantic code."""
return [p for p in self if isinstance(p, Problem) and p.code == code]
[docs] def surfaces(self) -> set[str]:
"""Set of surfaces that have problems."""
return {p.surface for p in self if isinstance(p, Problem) and p.surface}
[docs] def codes(self) -> set[str]:
"""Set of unique problem codes."""
return {p.code for p in self if isinstance(p, Problem) and p.code}
[docs] def to_dicts(self) -> list[ProblemDict]:
"""Serialize all problems to dictionaries."""
return [p.to_dict() if isinstance(p, Problem) else {'message': str(p), 'surface': '', 'code': ''} for p in self]
[docs] def add(
self,
problem_or_message: Any,
*,
surface: str = '',
code: str = '',
target: str = '',
hint: Optional[str] = None,
) -> None:
"""Append a problem or wrap a string message into a Problem."""
if isinstance(problem_or_message, Problem):
self.append(problem_or_message)
else:
self.append(Problem(str(problem_or_message), surface=surface, code=code, target=target, hint=hint))
# ---- Runtime Trouble --------------------------------------------------------
[docs]class TroubleDict(TypedDict, total=False):
"""Concrete dictionary structure for runtime trouble."""
message: str
code: str
severity: str
compartment: str
since: Optional[int]
hint: Optional[str]
metadata: Mapping[str, Any]
[docs]class Trouble(str):
"""What an operator should be told without having to ask for it.
Subclasses str so that existing tests asserting against `trouble()`
strings, substring matches (`'relay' in t`), list equality (`[t] == ['foo']`),
and string formatting continue to work 100% identically without breaking changes.
"""
code: str
compartment: str
message: str
severity: str
since: Optional[int]
hint: Optional[str]
metadata: Mapping[str, Any]
[docs] def __new__(
cls: type[T_tr],
message: str,
*,
code: str = 'fault',
compartment: str = '',
severity: str = 'trouble',
since: Optional[int] = None,
hint: Optional[str] = None,
**metadata: Any,
) -> T_tr:
obj = super().__new__(cls, message)
obj.code = str(code)
obj.compartment = str(compartment)
obj.message = str(message)
obj.severity = str(severity)
obj.since = since
obj.hint = hint
obj.metadata = metadata
return obj
[docs] def to_dict(self) -> TroubleDict:
"""Serialize to a JSON-compatible dictionary."""
d: TroubleDict = {
'message': self.message,
'code': self.code,
'severity': self.severity,
}
if self.compartment:
d['compartment'] = self.compartment
if self.since is not None:
d['since'] = self.since
if self.hint is not None:
d['hint'] = self.hint
if self.metadata:
d['metadata'] = self.metadata
return d
[docs]class TroubleList(list[Any]):
"""A list of Trouble items offering filtering and serialization."""
[docs] def for_compartment(self, compartment: str) -> list[Trouble]:
"""Filter troubles belonging to a specific compartment."""
return [t for t in self if isinstance(t, Trouble) and t.compartment == compartment]
[docs] def by_code(self, code: str) -> list[Trouble]:
"""Filter troubles by fault code."""
return [t for t in self if isinstance(t, Trouble) and t.code == code]
[docs] def by_severity(self, severity: str) -> list[Trouble]:
"""Filter troubles by severity ('trouble', 'warning', 'fatal', etc.)."""
return [t for t in self if isinstance(t, Trouble) and t.severity == severity]
[docs] def codes(self) -> set[str]:
"""Set of unique trouble codes."""
return {t.code for t in self if isinstance(t, Trouble) and t.code}
[docs] def compartments(self) -> set[str]:
"""Set of compartments reporting trouble."""
return {t.compartment for t in self if isinstance(t, Trouble) and t.compartment}
[docs] def to_dicts(self) -> list[TroubleDict]:
"""Serialize all troubles to dictionaries."""
return [t.to_dict() if isinstance(t, Trouble) else {'message': str(t), 'code': 'fault', 'severity': 'trouble'} for t in self]
[docs] def add(
self,
trouble_or_message: Any,
*,
code: str = 'fault',
compartment: str = '',
severity: str = 'trouble',
since: Optional[int] = None,
hint: Optional[str] = None,
**kw: Any,
) -> None:
"""Append a trouble item or wrap a raw string into a Trouble instance."""
if isinstance(trouble_or_message, Trouble):
self.append(trouble_or_message)
else:
self.append(Trouble(
str(trouble_or_message),
code=code,
compartment=compartment,
severity=severity,
since=since,
hint=hint,
**kw,
))
# ---- Runtime Notes ----------------------------------------------------------
T_note = TypeVar('T_note', bound='Note')
[docs]class NoteDict(TypedDict, total=False):
"""Concrete dictionary structure for runtime notes."""
message: str
topic: str
level: str
compartment: str
since: Optional[int]
metadata: Mapping[str, Any]
[docs]class Note(str):
"""What an operator would want to read, that is not a fault.
A relay cooling after a rate-limit, a peer that announced it is
leaving: the node behaving, and the reason a quiet mesh is quiet.
Kept apart from `trouble()` so no reader has to classify prose.
Subclasses str so that existing tests asserting against `notes()`
strings, substring matches, or list equality continue to work 100% identically.
"""
topic: str
compartment: str
message: str
level: str
since: Optional[int]
metadata: Mapping[str, Any]
[docs] def __new__(
cls: type[T_note],
message: str,
*,
topic: str = 'general',
compartment: str = '',
level: str = 'info',
since: Optional[int] = None,
**metadata: Any,
) -> T_note:
obj = super().__new__(cls, message)
obj.topic = str(topic)
obj.compartment = str(compartment)
obj.message = str(message)
obj.level = str(level)
obj.since = since
obj.metadata = metadata
return obj
[docs] def to_dict(self) -> NoteDict:
"""Serialize to a JSON-compatible dictionary."""
d: NoteDict = {
'message': self.message,
'topic': self.topic,
'level': self.level,
}
if self.compartment:
d['compartment'] = self.compartment
if self.since is not None:
d['since'] = self.since
if self.metadata:
d['metadata'] = self.metadata
return d
[docs]class NoteList(list[Any]):
"""A list of Note items offering filtering and serialization."""
[docs] def for_compartment(self, compartment: str) -> list[Note]:
"""Filter notes belonging to a specific compartment."""
return [n for n in self if isinstance(n, Note) and n.compartment == compartment]
[docs] def by_topic(self, topic: str) -> list[Note]:
"""Filter notes by topic."""
return [n for n in self if isinstance(n, Note) and n.topic == topic]
[docs] def by_level(self, level: str) -> list[Note]:
"""Filter notes by level ('info', 'notice', 'debug', etc.)."""
return [n for n in self if isinstance(n, Note) and n.level == level]
[docs] def topics(self) -> set[str]:
"""Set of unique note topics."""
return {n.topic for n in self if isinstance(n, Note) and n.topic}
[docs] def compartments(self) -> set[str]:
"""Set of compartments reporting notes."""
return {n.compartment for n in self if isinstance(n, Note) and n.compartment}
[docs] def to_dicts(self) -> list[NoteDict]:
"""Serialize all notes to dictionaries."""
return [n.to_dict() if isinstance(n, Note) else {'message': str(n), 'topic': 'general', 'level': 'info'} for n in self]
[docs] def add(
self,
note_or_message: Any,
*,
topic: str = 'general',
compartment: str = '',
level: str = 'info',
since: Optional[int] = None,
**kw: Any,
) -> None:
"""Append a note item or wrap a raw string into a Note instance."""
if isinstance(note_or_message, Note):
self.append(note_or_message)
else:
self.append(Note(
str(note_or_message),
topic=topic,
compartment=compartment,
level=level,
since=since,
**kw,
))