colca-data-contracts 0.2.0__tar.gz → 0.3.0__tar.gz

{colca_data_contracts-0.2.0 → colca_data_contracts-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: colca-data-contracts
-Version: 0.2.0
+Version: 0.3.0
 Summary: Payload contracts, topic helpers and golden vectors for Colca
 Author: Colca contributors
 License: FSL-1.1-ALv2

{colca_data_contracts-0.2.0 → colca_data_contracts-0.3.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "colca-data-contracts"
 # Release builds take the version from the git tag.
-version = "0.2.0"
+version = "0.3.0"
 description = "Payload contracts, topic helpers and golden vectors for Colca"
 readme = "README.md"
 license = { text = "FSL-1.1-ALv2" }

{colca_data_contracts-0.2.0 → colca_data_contracts-0.3.0}/src/colca_data_contracts/__init__.py

@@ -70,7 +70,10 @@ from colca_data_contracts.payload import (
     ActorKind,
     AlarmNotificationConfigSnapshot,
     AlarmNotificationSummary,
+    AlarmSeverity,
+    AlarmState,
     AlarmStateChange,
+    AlarmStatus,
     AuditAction,
     AuditEvent,
     AuditOutcome,
@@ -203,6 +206,10 @@ __all__ = [  # noqa: RUF022 - grouped by topic
     "AlarmNotificationSummary",
     "AlarmStateChange",
     "NotificationDispatched",
+    # The standing alarm, one retained record per alarm definition
+    "AlarmState",
+    "AlarmStatus",
+    "AlarmSeverity",
     # Annotation instances, on their own stream like alarms
     "AnnotationPayload",
     "derive_annotation_id",

{colca_data_contracts-0.2.0 → colca_data_contracts-0.3.0}/src/colca_data_contracts/payload.py

@@ -131,6 +131,21 @@ class ActorKind(BaseStrEnum):
     ANONYMOUS = "anonymous"
 
 
+class AlarmStatus(BaseStrEnum):
+    """What a standing alarm is doing. No ``normal`` and no ``recovered``: an
+    alarm that no longer stands is deleted, not set to a quiet status."""
+
+    PENDING = "pending"
+    FIRING = "firing"
+    UNKNOWN = "unknown"
+
+
+class AlarmSeverity(BaseStrEnum):
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
 class CustomEncoder(json.JSONEncoder):
     def default(self, obj):
         if isinstance(
@@ -144,6 +159,8 @@ class CustomEncoder(json.JSONEncoder):
                 AuditAction,
                 AuditOutcome,
                 ActorKind,
+                AlarmStatus,
+                AlarmSeverity,
             ),
         ):
             return str(obj)
@@ -480,6 +497,55 @@ class NotificationDispatched(Payload):
     terminal: bool = True
 
 
+@dataclass
+class AlarmState(Payload):
+    """The alarm that stands right now: one record per alarm definition.
+
+    State, not an event. A new record replaces the one before it, and an empty
+    payload retires the path — that tombstone is "the alarm has gone". Nothing
+    else says so: there is no ``normal`` status, because what is not in the
+    key-value view is not standing. The transitions themselves stay events, on
+    the ``alarms`` stream as ``_AlarmStateChange``.
+
+    The record sits at the alarm's own element path,
+    ``{root}/v1/_AlarmState/{node}/{element-path}/{alarm-name}``, so read
+    grants and zones reach it like any signal. ``_Alarm`` stays reserved for
+    the definition, which has another writer.
+
+    Recipients are deliberately absent: another writer owns them, they are
+    personal data that does not belong in the retained view, and a policy
+    change must never rewrite an alarm's state. Who was reached and when is in
+    ``_NotificationDispatched``. No title or message either: the name comes
+    from the alarm's ``_SystemElement``, and the topic path is the link.
+    """
+
+    alarm_id: ULID
+    status: AlarmStatus
+    severity: AlarmSeverity
+    #: Unix seconds this status has held since.
+    since: float
+    signal_id: ULID
+    #: Why it stands. ``threshold``, ``no_data`` and ``stream_gap`` are the
+    #: known values, but the vocabulary stays open so a derived diagnosis can
+    #: name its own reason.
+    reason: str
+    #: The measurement that brought it here, with the rule's operator and
+    #: threshold, so a reader can render "82.4 > 80" without the definition.
+    value: Any | None = None
+    op: str | None = None
+    threshold: float | None = None
+    #: The `_AlarmStateChange` this state came out of.
+    event_id: str | None = None
+    #: ``sub`` of the person, as the node witnessed it (the command's
+    #: actor_id), never self-asserted.
+    acknowledged_by: str | None = None
+    acknowledged_at: float | None = None
+    note: str | None = None
+    silenced_by: str | None = None
+    #: Unix seconds.
+    silenced_until: float | None = None
+
+
 def derive_annotation_id(
     annotation_type_id: str,
     source: str,

{colca_data_contracts-0.2.0 → colca_data_contracts-0.3.0}/src/colca_data_contracts/routing.py

@@ -33,6 +33,9 @@ CLASS_TABLE: dict[str, str] = {
     "_ExternalReference": "entity",
     "_AlarmNotificationConfig": "entity",
     "_NotificationConfigStatus": "entity",
+    # The standing alarm, one record per definition: it overwrites itself and
+    # a tombstone retires it, so a new subscriber sees what stands.
+    "_AlarmState": "entity",
     # Alarm events: append-only, not in KV, not retained, and on their own
     # stream so they never queue behind a metrics backlog.
     "_AlarmStateChange": "alarm",

{colca_data_contracts-0.2.0 → colca_data_contracts-0.3.0}/src/colca_data_contracts.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: colca-data-contracts
-Version: 0.2.0
+Version: 0.3.0
 Summary: Payload contracts, topic helpers and golden vectors for Colca
 Author: Colca contributors
 License: FSL-1.1-ALv2

{colca_data_contracts-0.2.0 → colca_data_contracts-0.3.0}/tests/test_alarm_payloads.py

@@ -3,7 +3,10 @@ from franzmq import Topic
 from colca_data_contracts import (
     AlarmNotificationConfigSnapshot,
     AlarmNotificationSummary,
+    AlarmSeverity,
+    AlarmState,
     AlarmStateChange,
+    AlarmStatus,
     NotificationChannelConfig,
     NotificationChannelOutcome,
     NotificationConfigStatus,
@@ -245,3 +248,76 @@ def test_dispatch_round_trip_includes_provider_delivery_result():
 
 def test_service_types_include_notifications():
     assert ServiceType.NOTIFICATIONS == "notifications"
+
+
+def test_standing_alarm_is_one_retained_record_at_the_alarm_element():
+    state = AlarmState(
+        alarm_id="01H0000000000000000000ARM1",
+        status=AlarmStatus.FIRING,
+        severity=AlarmSeverity.CRITICAL,
+        since=1710000000.0,
+        signal_id="01H0000000000000000000SGN2",
+        reason="threshold",
+        value=82.4,
+        op=">",
+        threshold=80.0,
+        event_id="evt-1",
+    )
+    topic = Topic(payload_type=AlarmState, node_id="n-edge1", context=("line1", "press3", "overheat"))
+
+    assert str(topic) == "colca/v1/_AlarmState/n-edge1/line1/press3/overheat"
+    assert AlarmState.get_identifier() == "_AlarmState"
+    # The alarm is an element in the tree, not a reserved _colca path, so read
+    # grants and zones reach it like any signal.
+    assert "_colca" not in str(topic)
+
+    decoded = AlarmState.decode(state.encode(), timestamp=0)
+
+    assert decoded.status == "firing"
+    assert decoded.severity == "critical"
+    assert decoded.value == 82.4
+    assert decoded.op == ">"
+    assert decoded.threshold == 80.0
+    assert decoded.event_id == "evt-1"
+
+
+def test_standing_alarm_carries_no_recipients_and_no_presentation():
+    fields = set(AlarmState.__dataclass_fields__)
+
+    # Recipients have another writer, are personal data, and a policy change
+    # must not rewrite an alarm's state; who was reached is _NotificationDispatched.
+    assert not fields & {"recipients", "channels", "policies", "policy_id", "recipient_id"}
+    # The name comes from the alarm's _SystemElement, the link is the topic.
+    assert not fields & {"title", "message", "deepLink", "deep_link"}
+
+
+def test_standing_alarm_has_no_normal_status():
+    # "Gone" is the tombstone, not a status: what is not in the KV view is not
+    # standing.
+    assert {str(member) for member in AlarmStatus} == {"pending", "firing", "unknown"}
+    assert {str(member) for member in AlarmSeverity} == {"info", "warning", "critical"}
+
+
+def test_acknowledgement_is_witnessed_by_the_node():
+    state = AlarmState(
+        alarm_id="01H0000000000000000000ARM1",
+        status=AlarmStatus.FIRING,
+        severity=AlarmSeverity.WARNING,
+        since=1710000000.0,
+        signal_id="01H0000000000000000000SGN2",
+        reason="no_data",
+        acknowledged_by="keycloak-sub-1",
+        acknowledged_at=1710000060.0,
+        note="Sensor wird getauscht",
+        silenced_by="keycloak-sub-1",
+        silenced_until=1710003600.0,
+    )
+
+    decoded = AlarmState.decode(state.encode(), timestamp=0)
+
+    # The evaluator writes the actor_id the node witnessed, never a claim the
+    # payload made about itself.
+    assert decoded.acknowledged_by == "keycloak-sub-1"
+    assert decoded.acknowledged_at == 1710000060.0
+    assert decoded.note == "Sensor wird getauscht"
+    assert decoded.silenced_until == 1710003600.0

{colca_data_contracts-0.2.0 → colca_data_contracts-0.3.0}/tests/test_bundle_generator.py

@@ -305,6 +305,48 @@ def test_alarm_notification_contracts_have_revised_direction_and_shape():
     assert {"revision", "notification"} <= set(event["schema"]["required"])
 
 
+def test_standing_alarm_is_retained_state_with_a_closed_status_vocabulary():
+    body, _ = gb.build_bundle()
+    standing = body["contracts"]["_AlarmState"]
+    schema = standing["schema"]
+
+    # One record per alarm definition: it overwrites itself, and the tombstone
+    # is how an alarm goes away.
+    assert standing["class"] == "entity"
+    assert standing["tombstone"] is True
+    assert set(schema["required"]) == {
+        "alarm_id",
+        "status",
+        "severity",
+        "since",
+        "signal_id",
+        "reason",
+    }
+    # Status and severity are closed; reason stays open so a derived diagnosis
+    # can name its own.
+    assert schema["properties"]["status"]["enum"] == ["pending", "firing", "unknown"]
+    assert schema["properties"]["severity"]["enum"] == ["info", "warning", "critical"]
+    assert "enum" not in schema["properties"]["reason"]
+
+    validator = jsonschema.Draft202012Validator(schema)
+    standing_now = {
+        "alarm_id": "01H0000000000000000000ARM1",
+        "status": "firing",
+        "severity": "critical",
+        "since": 1710000000.0,
+        "signal_id": "01H0000000000000000000SGN2",
+        "reason": "threshold",
+        "value": 82.4,
+        "op": ">",
+        "threshold": 80.0,
+    }
+    validator.validate(standing_now)
+    # There is no "normal": an alarm that no longer stands is deleted.
+    assert not validator.is_valid({**standing_now, "status": "normal"})
+    assert not validator.is_valid({**standing_now, "status": "recovered"})
+    assert validator.is_valid({**standing_now, "reason": "compressor_stall"})
+
+
 def test_alarm_channel_schema_requires_sealed_secret_and_rejects_cleartext_fields():
     body, _ = gb.build_bundle()
     channel = body["contracts"]["_AlarmNotificationConfig"]["schema"]["properties"]["channels"]["items"]
@@ -405,6 +447,7 @@ ULID_CONSTRAINED_FIELDS = {
     "_Constant": ["id", "system_element_id", "semantic_type_id"],
     "_Resource": ["id", "system_element_id"],
     "_ExternalReference": ["id", "external_system_id"],
+    "_AlarmState": ["alarm_id", "signal_id"],
     # annotation_type_id stays unconstrained until the golden annotation-id
     # vectors derive from ULID type ids — see payload.Annotation.
     "_Annotation": ["annotation_id", "signal_ids/items"],