span-panel-api 3.0.0b11__tar.gz → 3.0.0b13__tar.gz

{span_panel_api-3.0.0b11 → span_panel_api-3.0.0b13}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0b13]
+
+Carries `span-panel-api-schema-1` 0.1.0b10, which gives the two lugs devices their own extension subject. No behaviour change in this distribution: `ExtensionSubject.kind` documents `lugs` alongside the kinds it already accepted, which the type never
+enumerated in code.
+
+## [3.0.0b12]
+
+### Added
+
+- **A vendor property on a device this library already models now reaches a consumer, instead of stopping at diagnostics.** The schema is explicitly vendor-extensible and adoption covered only half of that: a device type nothing here models is adopted with
+  its readings, while a new property on the BESS, a charger, a circuit or the panel became a `DiscoveredMetadata` row — a declaration, no value, visible only to a maintainer reading a diagnostics attachment. `SpanPanelSnapshot.extension_properties` carries
+  those properties with their values, so a consumer can render what the publisher published.
+- **`ExtensionProperty` and `ExtensionSubject`.** The subject names which modelled snapshot subject a property hangs off — `battery`, `mid`, `pv`, `panel`, and `evse`/`circuit` with the instance key the snapshot's own maps use — so a consumer resolves the
+  device it belongs on with a lookup it already performs. What is _not_ exposed is the field-level mapping: the subject is one value per device and cannot drift, while the wire-property-to-snapshot-field map is the adapter's internal business and exporting
+  it would freeze it as API.
+
+### Notes
+
+- **The value never reaches diagnostics, and that is structural rather than remembered.** `ExtensionProperty` is deliberately not a `FieldMetadata`, so it cannot enter the map `partition()` walks and has no path into a payload that leaves the machine. The
+  discovery rows keep flowing unchanged: the same property appears in both surfaces on purpose, joined by its `{node}/{property}` path — a declaration for the maintainer, a reading for the user.
+- **Read-only by construction.** An extension property carries `settable` for curation triage and no set topic, and there is no member a write path could be built from. These properties live on exactly the devices whose curated controls do real work — the
+  EVSE limit refuses a value above the commissioned ceiling, the islanding assertion translates `GRID` into `ON_GRID` — and a generic write beside them would have neither.
+- **Additive in both skew directions.** The snapshot field defaults empty, so an older adapter degrades to the previous behaviour with no new `SchemaAdapter` member required — a required member would fail at _discovery_, taking down every install whose
+  adapter wheel lags the bootstrap by a release. The reverse skew is handled by `span-panel-api-schema-1` 0.1.0b9 declaring this release as its floor.
+
 ## [3.0.0b11]
 
 Carries `span-panel-api-schema-1` 0.1.0b8, which restores `dominant_power_source` on a panel with no MID. No change in this distribution.

{span_panel_api-3.0.0b11 → span_panel_api-3.0.0b13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.0.0b11
+Version: 3.0.0b13
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues

{span_panel_api-3.0.0b11 → span_panel_api-3.0.0b13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.0.0b11"
+version = "3.0.0b13"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}

{span_panel_api-3.0.0b11 → span_panel_api-3.0.0b13}/src/span_panel_api/__init__.py

@@ -37,6 +37,8 @@ from .models import (
     AdoptedDevice,
     AdoptedProperty,
     DiscoveredMetadata,
+    ExtensionProperty,
+    ExtensionSubject,
     FieldMetadata,
     HomieSchemaTypes,
     SpanBatterySnapshot,
@@ -107,6 +109,8 @@ __all__ = [  # noqa: RUF022
     "ADOPTION_TOPOLOGY_NODE",
     "AdoptedDevice",
     "AdoptedProperty",
+    "ExtensionProperty",
+    "ExtensionSubject",
     # Snapshots
     "SpanBatterySnapshot",
     "SpanCircuitSnapshot",

{span_panel_api-3.0.0b11 → span_panel_api-3.0.0b13}/src/span_panel_api/models.py

@@ -776,6 +776,116 @@ class AdoptedDevice:
     """Everything outside `info` and `connection`, in declaration order."""
 
 
+@dataclass(frozen=True, slots=True)
+class ExtensionSubject:
+    """Which modelled snapshot subject an extension property hangs off.
+
+    The adapter already knows which wire device populated which snapshot subject
+    -- that mapping is how `battery.power_w` gets a value. This type exposes the
+    *subject* and never the mapping: a consumer needs "this belongs to the
+    battery", not "this is how `battery.*` is assembled". Exporting the
+    field-level map would freeze the adapter's internals as API; exporting the
+    subject cannot, because it is one value per device drawn from a closed set.
+
+    Resolution is by declared `$type` and is indifferent to proxying: the
+    reference tree's own MID arrives proxied as `bess-mid` and still resolves to
+    `mid`. A proxied device of an *unmodelled* type resolves to no subject at all
+    and belongs to `AdoptedDevice`, which carries `parent` for that shape.
+    """
+
+    kind: str
+    """One of: `panel`, `lugs`, `battery`, `mid`, `pv`, `evse`, `circuit`.
+
+    `lugs` is separate from `panel` although its curated fields land in the panel
+    snapshot, because a subject is an identity and the two lugs devices are two
+    devices: they run the same firmware, so a vendor extension on one is the
+    expected case of the same extension on both, and folding them into `panel`
+    made two wire addresses one identity.
+    """
+
+    instance_key: str | None = None
+    """The snapshot map key for multi-instance kinds, `None` for the singletons.
+
+    The EVSE's `node_id` and the circuit's `circuit_id` -- the same keys
+    `snapshot.evse` and `snapshot.circuits` use, so a consumer holding the
+    snapshot resolves the subject with a lookup it already performs.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionProperty:
+    """One property a *modelled* device declares that no snapshot field carries.
+
+    The value-carrying counterpart to `DiscoveredMetadata`, and deliberately a
+    third type rather than either neighbour. A discovered row exists to be
+    forwarded in diagnostics -- payloads that leave the machine into issues and
+    forum posts -- so it carries no value by construction. An `AdoptedProperty`
+    belongs to a device nothing here models, and its `set_topic` scoping *is* a
+    write authorisation this type must not inherit. This one belongs to a device
+    the adapter does model, exists to reach a consumer as a reading, and is
+    read-only by construction: no set topic, and no member a write path could be
+    built from.
+
+    **Not a `FieldMetadata`, and that is the diagnostics guarantee.**
+    `partition()` walks `build_field_metadata()`; this type rides
+    `build_snapshot()` instead, so there is no code path from here into
+    `SchemaFindings` or a diagnostics payload. The same wire property appears in
+    both surfaces on purpose -- as a declaration for the maintainer, as a value
+    for the user -- joined by the `{node}/{property}` path body.
+
+    **Read-only is not a policy this type states, it is a shape it has.** A
+    settable extension property is carried with `settable=True` for curation
+    triage and still surfaces as a reading: a control on a modelled device would
+    sit beside curated controls that do real safety work (the EVSE limit refuses
+    a value above the commissioned ceiling; schema_1 translates `GRID` into
+    `ON_GRID`), and a generic write path would bypass both on the same wire.
+    """
+
+    subject: ExtensionSubject
+    """The curated device this property hangs off."""
+
+    node_id: str
+    """The Homie node, e.g. `battery-2`. Never `info` or `connection`."""
+
+    property_id: str
+    """The Homie property, e.g. `cell-temperature`."""
+
+    datatype: str
+    """The declared Homie datatype -- `float`, `integer`, `boolean`, `enum`, `string`."""
+
+    unit: str | None = None
+    """The declared unit, verbatim. `None` is normal for a `boolean` or an `enum`."""
+
+    format: str | None = None
+    """The declared `$format`: an option list for an `enum`, `min:max:step` for a number."""
+
+    settable: bool = False
+    """Declaration fact, carried for curation triage.
+
+    Deliberately not paired with a set topic. See the read-only note above: the
+    absence of a write member is what makes the ruling structural rather than
+    remembered.
+    """
+
+    value: str | None = None
+    """The retained value as published, unparsed. `None` when declared and never valued."""
+
+    node_has_curated_siblings: bool = False
+    """Whether the adapter maps any *other* property of this node to a snapshot field.
+
+    The one bit of the node-to-field mapping worth exporting: a vendor extending
+    `meter` is probably extending the meter. Stamped in one pass over knowledge
+    the adapter already holds, and it says nothing about *which* fields, so it
+    freezes no internals. A weak signal -- Homie nodes are organisational rather
+    than editorial -- and advisory only.
+    """
+
+    @property
+    def path(self) -> str:
+        """`{node}/{property}` -- how the capability catalogs spell it."""
+        return f"{self.node_id}/{self.property_id}"
+
+
 @dataclass(frozen=True, slots=True)
 class SpanPanelSnapshot:
     """Complete panel state — single point-in-time view."""
@@ -938,6 +1048,26 @@ class SpanPanelSnapshot:
     field that defaults empty is additive and costs neither.
     """
 
+    extension_properties: tuple[ExtensionProperty, ...] = ()
+    """Properties *modelled* devices declare that no snapshot field carries.
+
+    The other half of vendor extensibility from `adopted_devices` above: that
+    one covers a device type nothing models, this one a new property on a device
+    something does. Until this existed the second case reached a consumer
+    nowhere -- it became a `DiscoveredMetadata` row and stopped at diagnostics.
+
+    Empty is deliberately ambiguous between "none declared" and "this adapter
+    predates the field", and a consumer must not try to tell them apart: the
+    older-wheel case is the normal partial-upgrade state, because the adapters
+    are separately published packages that version independently of this core.
+    A defaulted snapshot field rather than a protocol member for exactly the
+    reason `adopted_devices` gives -- a required member would fail at
+    *discovery*, taking down every install whose adapter lags by one release.
+
+    schema_0 leaves it empty: flat has no device tree to find a declared-but
+    -unmapped property in, and panels upgrade to v1.0 and stay there.
+    """
+
     pcs: SpanPcsSnapshot | None = None
     """The enclosure's Power Control System, when it publishes a `pcs` node. v1.0 only.
 

{span_panel_api-3.0.0b11 → span_panel_api-3.0.0b13}/tests/test_public_api_unchanged.py

@@ -51,6 +51,8 @@ EXPECTED_PUBLIC_API = {
     "ADOPTION_TOPOLOGY_NODE",
     "AdoptedDevice",
     "AdoptedProperty",
+    "ExtensionProperty",
+    "ExtensionSubject",
     "AdoptedControlProtocol",
     "is_discovery_path",
     # Snapshots

{span_panel_api-3.0.0b11 → span_panel_api-3.0.0b13}/tests/test_schema_one_discovery.py

@@ -114,6 +114,16 @@ def _snapshot_fields(snapshot: SpanPanelSnapshot) -> dict[str, str]:
     fields: dict[str, str] = {}
     for field in dataclasses.fields(snapshot):
         value = getattr(snapshot, field.name)
+        if field.name == "extension_properties":
+            # Excluded, and the exclusion is the point rather than a convenience.
+            # This field carries every *unaddressed* declaration by construction,
+            # so republishing any property discovery reports would move it — and
+            # "does republishing this move a snapshot field" would answer yes for
+            # every discovered row, which is the question this oracle exists to
+            # ask. What the test still catches is the real defect: a discovered
+            # property that moves a *curated* field, i.e. one the mapper reads
+            # while the addressed set says it does not.
+            continue
         if field.name in {"circuits", "evse"}:
             for key, item in value.items():
                 _record(fields, f"{field.name}@{key}", item)

span_panel_api-3.0.0b13/tests/test_schema_one_extension.py

@@ -0,0 +1,303 @@
+"""What the adapter emits as vendor extensions on devices it *does* model.
+
+`build_extension_properties` is the value-carrying twin of `build_discovery`:
+the same declared-but-unaddressed question, asked of the same tree, answered for
+a consumer that will render it rather than for a maintainer reading an
+attachment. The two must agree exactly, so the first test here is the join —
+every extension row has a discovery row and vice versa.
+
+The rest are structural, and they are structural on purpose. "Adopted values
+never reach diagnostics" and "an extension property is read-only" are claims the
+design makes about *shapes*, so they are asserted about shapes: a type that is
+not a `FieldMetadata` cannot enter the metadata map that diagnostics is built
+from, and a type with no set-topic member cannot grow a write path by someone
+forgetting a rule.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import json
+
+from ebus_sdk.homie import DiscoveredDevice
+import pytest
+
+from span_panel_api.models import (
+    ADOPTION_IDENTITY_NODE,
+    ADOPTION_TOPOLOGY_NODE,
+    ExtensionProperty,
+    ExtensionSubject,
+    FieldMetadata,
+    SpanPanelSnapshot,
+    discovery_path,
+)
+from span_panel_api_schema_1.extension import build_extension_properties
+from span_panel_api_schema_1.field_metadata import addressed_rows, build_discovery
+from span_panel_api_schema_1.reference_payloads import device_from_topics, parent_child_tree
+from span_panel_api_schema_1.snapshot import build_snapshot
+
+PANEL_DEVICE_ID = "example-40t-001"
+"""The enclosure in the reference capture. Every other device is its child."""
+
+Tree = dict[str, dict[str, str]]
+
+
+def _tree() -> Tree:
+    return {device_id: dict(topics) for device_id, topics in parent_child_tree().items()}
+
+
+def _snapshot(tree: Tree) -> SpanPanelSnapshot:
+    panel = device_from_topics(PANEL_DEVICE_ID, tree[PANEL_DEVICE_ID])
+    children = [device_from_topics(device_id, topics) for device_id, topics in tree.items() if device_id != PANEL_DEVICE_ID]
+    return build_snapshot(panel, children)
+
+
+def _devices(tree: Tree) -> list[DiscoveredDevice]:
+    return [device_from_topics(device_id, topics) for device_id, topics in tree.items()]
+
+
+def _short_type(device_type: str) -> str:
+    return device_type.rsplit(".", 1)[-1]
+
+
+def _declared_type(tree: Tree, device_id: str) -> str:
+    description: Mapping[str, object] = json.loads(tree[device_id]["$description"])
+    return str(description.get("type") or "")
+
+
+# --- the join with discovery ------------------------------------------------
+
+
+def test_every_extension_row_is_also_a_discovery_row() -> None:
+    """The two surfaces describe the same properties, joined by the wire path.
+
+    A property in one and not the other is the defect this test exists for: an
+    entity a consumer renders while the diagnostics report it ignored, or a
+    property reported ignored while an entity shows its value. Both read as a
+    bug in whichever surface disagreed.
+    """
+    tree = _tree()
+    snapshot = _snapshot(tree)
+    discovered = set(build_discovery(_devices(tree)))
+
+    for row in snapshot.extension_properties:
+        # The discovery path is keyed by the *device type*, so rebuild it from
+        # the subject's device rather than from the subject kind, which is a
+        # snapshot concept.
+        assert any(
+            path.endswith(f"/{row.path}") for path in discovered
+        ), f"extension row {row.path} on {row.subject.kind} has no discovery row"
+
+
+def test_no_extension_row_is_addressed() -> None:
+    """An addressed property has a snapshot field; surfacing it twice is the bug."""
+    tree = _tree()
+    addressed = addressed_rows(_devices(tree))
+    for row in _snapshot(tree).extension_properties:
+        assert not any(
+            node == row.node_id and prop == row.property_id for _type, node, prop in addressed
+        ), f"{row.path} is addressed and must not be emitted as an extension"
+
+
+# --- structure: the diagnostics and read-only guarantees --------------------
+
+
+def test_extension_property_is_not_field_metadata() -> None:
+    """The diagnostics guarantee, asserted as a shape rather than as a rule.
+
+    `partition()` walks `build_field_metadata()`; a type that cannot enter that
+    map has no path into a payload that leaves the machine.
+    """
+    row = ExtensionProperty(
+        subject=ExtensionSubject(kind="battery"),
+        node_id="battery-2",
+        property_id="cell-temperature",
+        datatype="float",
+    )
+    assert not isinstance(row, FieldMetadata)
+
+
+def test_extension_property_has_no_write_surface() -> None:
+    """No set topic, and no member one could be put in.
+
+    A literal `hasattr` check, because the point is to fail the change that adds
+    one rather than to describe today's fields.
+    """
+    row = ExtensionProperty(
+        subject=ExtensionSubject(kind="evse", instance_key="acme-001"),
+        node_id="acme",
+        property_id="charge-limit",
+        datatype="float",
+        settable=True,
+    )
+    assert not hasattr(row, "set_topic")
+    assert row.settable is True, "settable is carried for triage, and still carries no write path"
+
+
+def test_identity_and_topology_nodes_are_never_extensions() -> None:
+    """`info` and `connection` resolve to the device card and the tree.
+
+    Excluded by node, as `adoption._readings` excludes them, because the
+    catalogs carry no marker for "this string is a device reference" and a name
+    list goes stale silently.
+    """
+    for row in _snapshot(_tree()).extension_properties:
+        assert row.node_id not in (ADOPTION_IDENTITY_NODE, ADOPTION_TOPOLOGY_NODE)
+
+
+# --- emission against a synthetic vendor extension --------------------------
+
+
+VENDOR_NODE = "battery-2"
+
+
+def _with_vendor_extension(tree: Tree, device_id: str) -> Tree:
+    """Add an Acme pack node to one device's description, with one retained value."""
+    mutated = {other: dict(topics) for other, topics in tree.items()}
+    description = json.loads(mutated[device_id]["$description"])
+    description["nodes"][VENDOR_NODE] = {
+        "name": VENDOR_NODE,
+        "type": "energy.ebus.capability.vendor.acme.pack",
+        "properties": {
+            "cell-temperature": {"name": "Cell temperature", "datatype": "float", "unit": "°C"},
+            "pack-enabled": {"name": "Pack enabled", "datatype": "boolean", "settable": True},
+        },
+    }
+    mutated[device_id]["$description"] = json.dumps(description)
+    mutated[device_id][f"{VENDOR_NODE}/cell-temperature"] = "31.4"
+    return mutated
+
+
+def _bess_device_id(tree: Tree) -> str:
+    for device_id in tree:
+        if _declared_type(tree, device_id).endswith(".bess"):
+            return device_id
+    pytest.skip("reference tree carries no BESS")
+
+
+def test_a_vendor_node_on_a_modelled_device_becomes_extension_rows() -> None:
+    """The whole point: a property hung off the BESS reaches the snapshot."""
+    tree = _tree()
+    device_id = _bess_device_id(tree)
+    snapshot = _snapshot(_with_vendor_extension(tree, device_id))
+
+    rows = {row.path: row for row in snapshot.extension_properties}
+    assert f"{VENDOR_NODE}/cell-temperature" in rows
+    assert f"{VENDOR_NODE}/pack-enabled" in rows
+
+    temperature = rows[f"{VENDOR_NODE}/cell-temperature"]
+    assert temperature.subject.kind == "battery"
+    assert temperature.subject.instance_key is None
+    assert temperature.datatype == "float"
+    assert temperature.unit == "°C"
+    assert temperature.value == "31.4"
+    # Declared and never valued is distinguishable from valued: `None` rather
+    # than an invented default, so a consumer can tell "nothing has arrived".
+    assert rows[f"{VENDOR_NODE}/pack-enabled"].value is None
+    assert rows[f"{VENDOR_NODE}/pack-enabled"].settable is True
+
+
+def test_a_wholly_vendor_node_has_no_curated_siblings() -> None:
+    """The one exported bit of the node-to-field map, on a node with none."""
+    tree = _tree()
+    snapshot = _snapshot(_with_vendor_extension(tree, _bess_device_id(tree)))
+    rows = [row for row in snapshot.extension_properties if row.node_id == VENDOR_NODE]
+    assert rows
+    assert all(row.node_has_curated_siblings is False for row in rows)
+
+
+def test_an_extension_to_a_curated_node_reports_curated_siblings() -> None:
+    """A vendor extending `meter` is extending something this adapter reads."""
+    tree = _tree()
+    device_id = _bess_device_id(tree)
+    mutated = {other: dict(topics) for other, topics in tree.items()}
+    description = json.loads(mutated[device_id]["$description"])
+    meter = description["nodes"].get("meter")
+    if meter is None:
+        pytest.skip("reference BESS declares no meter node")
+    meter["properties"]["acme-cell-balance"] = {"name": "Cell balance", "datatype": "float", "unit": "%"}
+    mutated[device_id]["$description"] = json.dumps(description)
+
+    rows = [row for row in _snapshot(mutated).extension_properties if row.property_id == "acme-cell-balance"]
+    assert len(rows) == 1
+    assert rows[0].node_has_curated_siblings is True
+    # `%` is deliberately unrankable: the consumer maps no device class for it.
+    assert rows[0].unit == "%"
+
+
+def test_an_undeclared_device_is_skipped_rather_than_emitted() -> None:
+    """A device mid-discovery declares no type; that is a state, not a finding."""
+    tree = _tree()
+    device_id = _bess_device_id(tree)
+    mutated = {other: dict(topics) for other, topics in tree.items()}
+    description = json.loads(mutated[device_id]["$description"])
+    description.pop("type", None)
+    mutated[device_id]["$description"] = json.dumps(description)
+
+    subjects = [(device_from_topics(device_id, mutated[device_id]), ExtensionSubject(kind="battery"))]
+    assert build_extension_properties(subjects, addressed_rows(_devices(mutated))) == ()
+
+
+def test_the_reference_tree_alone_emits_nothing_addressed() -> None:
+    """A sanity floor: every row the untouched tree emits is genuinely unread."""
+    snapshot = _snapshot(_tree())
+    addressed = addressed_rows(_devices(_tree()))
+    for row in snapshot.extension_properties:
+        assert not any(node == row.node_id and prop == row.property_id for _t, node, prop in addressed)
+
+
+def test_discovery_path_joins_the_two_surfaces() -> None:
+    """The documented join key actually joins."""
+    tree = _tree()
+    device_id = _bess_device_id(tree)
+    mutated = _with_vendor_extension(tree, device_id)
+    discovered = set(build_discovery(_devices(mutated)))
+    expected = discovery_path(_short_type(_declared_type(mutated, device_id)), VENDOR_NODE, "cell-temperature")
+    assert expected in discovered
+
+    rows = {row.path for row in _snapshot(mutated).extension_properties}
+    assert f"{VENDOR_NODE}/cell-temperature" in rows
+    assert expected.endswith(f"/{VENDOR_NODE}/cell-temperature")
+
+
+def test_the_two_lugs_devices_are_two_subjects() -> None:
+    """Identical firmware on both lugs is what made one subject a collision.
+
+    A vendor extension on the upstream lugs is the expected case of the same
+    extension on the downstream lugs, so folding both into `panel` gave two wire
+    addresses one identity -- a consumer keying on
+    `(kind, instance_key, node/property)` would mint one id for two readings and
+    show whichever sorted first.
+    """
+    tree = _tree()
+    lugs = [
+        device_id
+        for device_id in tree
+        if ".lugs" in _declared_type(tree, device_id) or _declared_type(tree, device_id).endswith("lugs")
+    ]
+    if len(lugs) < 2:
+        pytest.skip("reference tree carries fewer than two lugs devices")
+
+    mutated = {other: dict(topics) for other, topics in tree.items()}
+    for device_id, value in zip(lugs, ("1.5", "99.9"), strict=False):
+        description = json.loads(mutated[device_id]["$description"])
+        description["nodes"]["acme"] = {
+            "name": "acme",
+            "type": "energy.ebus.capability.vendor.acme.balance",
+            "properties": {"phase-balance": {"name": "Phase balance", "datatype": "float", "unit": "%"}},
+        }
+        mutated[device_id]["$description"] = json.dumps(description)
+        mutated[device_id]["acme/phase-balance"] = value
+
+    rows = [row for row in _snapshot(mutated).extension_properties if row.path == "acme/phase-balance"]
+    assert len(rows) == 2
+    assert all(row.subject.kind == "lugs" for row in rows)
+    assert {row.subject.instance_key for row in rows} == {"upstream", "downstream"}
+    # Distinct identities carrying distinct readings, which is the point.
+    assert {row.value for row in rows} == {"1.5", "99.9"}
+
+
+def test_every_subject_identity_is_unique_per_property() -> None:
+    """No two rows may share `(kind, instance_key, path)` -- that tuple is the identity."""
+    identities = [(row.subject.kind, row.subject.instance_key, row.path) for row in _snapshot(_tree()).extension_properties]
+    assert len(identities) == len(set(identities))