fleet-sensor-baseline 0.2.0__tar.gz → 0.2.2__tar.gz

{fleet_sensor_baseline-0.2.0 → fleet_sensor_baseline-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fleet-sensor-baseline
-Version: 0.2.0
+Version: 0.2.2
 Summary: Which units differ from their cohort, and what changed across time.
 Project-URL: Homepage, https://github.com/james-sheen/fleet-sensor-baseline
 Project-URL: Source, https://github.com/james-sheen/fleet-sensor-baseline
@@ -25,9 +25,26 @@ Description-Content-Type: text/markdown
 list of machines and the history of captures, and answers the two questions the
 referee cannot.
 
-**Released — 0.2.0**, tagged `v0.2.0`, Apache-2.0, on PyPI as
+**Released — 0.2.2**, tagged `v0.2.2`, Apache-2.0, on PyPI as
 `fleet-sensor-baseline`.
 
+**0.2.2 adds `compare`, the threshold audit across time.** `drift` reads records
+and never opens a walk, so a threshold edited on a sensor that stayed present was
+invisible to it — and invisible to `collect --etag-cache` too, which is why a
+skip record says it proves membership. `compare` resolves the newest capture at
+or before each of two times, per surface, and hands both to the referee's
+`regression`. A record filed from a skip is refused as an input: it reuses the
+earlier payload, so comparing against one would judge a file against itself and
+report no drift.
+
+**0.2.1 closes the seam with the referee, and fixes a validator that could
+not check the one file it most needed to.** `baseline --for-referee` writes the
+referee's declaration-source format, which both projects described and neither
+produced; it comes out as a candidate nobody has signed, and it does not declare
+the sensors the cohort disagreed about. Separately, `validate` refused every
+`targets/2` file while naming `targets/2` among the formats it read — so the
+format that exists to carry `pin_sha256` was the one the checker would not check.
+
 **0.2.0 is a compatibility break, and it changes an answer.** The presence
 threshold was a single line, so a sensor either belonged to the baseline or was
 foreign to it — and at rack scale the majority won. On 24 trays where 2 lost a
@@ -64,7 +81,9 @@ pip install fleet-sensor-baseline
 
 The core has **no dependencies**. Ingest, baseline, outliers, drift, verdict and
 validate are JSON and arithmetic, so the vertical and horizontal axes run on a jump
-host with nothing provisioned. The collector needs the referee on PATH:
+host with nothing provisioned. `collect` and `compare` both need the referee on
+PATH -- one to walk a BMC, the other to judge two stored walks -- and the extra
+is named for the first only because renaming it would break every install line:
 
 ```
 pip install "fleet-sensor-baseline[collect]"
@@ -87,14 +106,56 @@ fleet-sensor-baseline outliers --store fleet-store --baseline baseline.json
 # the fleet run: every expected unit must have reported
 fleet-sensor-baseline verdict --store fleet-store --expect-units racks.txt
 
+# did a threshold move between two stored walks? ask the referee
+fleet-sensor-baseline compare --store fleet-store --unit h-0042 \
+    --before 2026-08-01T00:00:00Z --after 2026-08-20T00:00:00Z
+
 # check any artifact against the format it declares
 fleet-sensor-baseline validate baseline.json
 
+# hand the cohort's baseline back to the referee, as a candidate
+fleet-sensor-baseline baseline --store fleet-store --model GB200-NVL-tray \
+    --out baseline.json --for-referee declaration.json
+
 # walk a rack of BMCs yourself, serially, and file what comes back
 fleet-sensor-baseline collect --targets rack-17.json --store fleet-store \
     --collector-id rack-17
 ```
 
+### Handing a baseline back to the referee
+
+`--for-referee PATH` writes the cohort's baseline a second time, in
+`bmc-sensor-audit/fleet-baseline/1` — the referee's own declaration-source
+format, for `coverage --declaration`. It is the third source in that tool's
+precedence, under entity-manager and under a reviewed `pdr/1`.
+
+**It comes out as a candidate.** `"reviewed": null`, so the referee refuses to
+consume it until a person adds their name and a date. The conversion is not the
+review: a baseline derived from a fleet of unprovisioned boards is an empty
+declaration that reads healthy against every other unprovisioned board, and at
+fleet scale consensus makes that answer look corroborated. A marker this tool
+could write is a marker nobody put their name to, so there is no flag to write
+one.
+
+**The sensors the cohort disagreed about are not declared.** That band exists
+because a proportion is a coarse instrument at rack scale; the referee's format
+has two states, not three, and declaring a divergent sensor would expect it of
+every unit while 8 percent of the fleet does not have it — charging each of
+those units a finding for a fact about the cohort. That is the 0.1.x inversion,
+reached through a different door. They are written into the file under
+`divergent_not_declared`, which the referee ignores by its own `/1` rule, and
+named on stderr at export: the reviewer is the reader who needs them.
+
+The cohort must be scoped to one model — `--model`, or `--for-referee-platform`
+to name it directly — because the referee requires a platform on every
+declaration and a cohort spanning models has no single answer.
+
+`tests/test_seam.py::TestTheExportedDeclarationIsWhatTheRefereeReads` runs the
+real `bmc-sensor-audit` against a file this emits: refused as a candidate,
+consumed once reviewed, and the unit that lost the divergent sensor coming back
+clean — with the counterfactual that declares it anyway and watches the same
+unit get charged.
+
 ### Asking before walking
 
 ```
@@ -169,8 +230,10 @@ renders incompleteness as silence renders a dead collector as a clean rack.
    is never the source of judgment. Silence cannot impersonate a pass.
 2. **Never metric values.** This audits presence and configuration, not readings.
 3. **Never majority-truth over declarations.** A fleet-derived baseline is an
-   *additional, labeled, downgraded* declaration source. Wherever a manufacturer
-   declaration exists, it wins.
+   *additional, labeled, downgraded* declaration source — reachable through
+   `baseline --for-referee`, which writes the referee's own format as a
+   candidate nobody has signed yet. Wherever a manufacturer declaration exists,
+   it wins.
 4. **Never identity inside the referee's artifacts.** The walk payload carries no
    `unit_key`. Identity binds here.
 
@@ -210,9 +273,34 @@ key the file declares rather than on a shape guessed from the fields present.
 
 See [docs/formats.md](docs/formats.md).
 
-## Storage
+## Comparing across time
 
-### When the cohort disagrees with itself
+`drift` answers what changed in the RECORDS -- firmware, the sensor set, which
+units reported. It does not open the walks. A threshold edited on a sensor that
+stayed present is invisible to it, and invisible to `collect --etag-cache` too:
+a collection ETag moves when membership changes, so a skip record says in as
+many words that it proves `membership`, and the docs say membership is not
+enough for a threshold audit.
+
+`compare` is the missing half, and it is selection rather than judgment. It
+resolves the newest capture at or before each of two times, pulls both payloads
+out of the store, and hands them to `bmc-sensor-audit regression`, whose job
+this is. `--strict-fields` and `--aggregation-prefix` pass straight through.
+Exit codes come back in the family's vocabulary; the referee's refusals come
+back in the referee's own words.
+
+**A record filed from a skip is refused as an input, and that rule is the whole
+point rather than tidiness.** A skip reuses the earlier capture's payload
+digest, so comparing a walk against one resolves both ends to the same stored
+object: the referee would be handed a file and itself, and would correctly
+answer *no drift*. The question asked was whether a threshold moved. Force a
+full walk for that surface, or pick a time when one was taken.
+
+Pairing is surface to surface, per [a unit is a tuple](#a-unit-is-a-tuple), so a
+machine answering on a host BMC and an HMC gets one comparison each rather than
+one compared against the other.
+
+## When the cohort disagrees with itself
 
 A sensor is **expected** at or above `--present-threshold` (0.99), **foreign** at
 or below `--absent-threshold` (0.01), and between the two the cohort simply
@@ -262,9 +350,16 @@ to surface; presence across the cohort is the union across a unit's surfaces.
 ## The boundary
 
 This package **never imports `bmc_sensor_audit`**. It reads exit codes, stdout and
-the files the tool writes. One module is exempt — `collect/backends/mock.py`, which
-imports the referee's `MockBMC`, and the distinction is the design: that is a fake
-*machine*, standing in for the thing being walked, not the thing doing the walking.
+the files the tool writes. One module is exempt — `collect/backends/mock.py` — and
+the distinction is the design: it stands in for the thing being walked, not the
+thing doing the walking.
+
+It imports the referee's mock BMC *and* its `RedfishClient` and `walk_chassis`, so
+the payloads it produces are real `walk/1` files written by the real walker rather
+than approximations of them. The exemption is file-level and that is the actual
+contract `tests/test_boundary.py` enforces; an earlier version of this sentence
+named only the mock, which was narrower than the code and would have made a
+correct file look like a violation.
 
 `tests/test_boundary.py` asserts both halves by reading the source: that nothing
 else imports it, and that the mock backend still does. Without the second, the
@@ -274,15 +369,15 @@ first would pass by finding nothing.
 
 | | count |
 |---|---|
-| tests collected | 280 |
-| of those, requiring `bmc-sensor-audit` | 34 |
+| tests collected | 363 |
+| of those, requiring `bmc-sensor-audit` | 40 |
 
 **The predicate**: `pytest --collect-only` over the test files git tracks, and
 the same again with `-m seam` for the second row. Collection rather than a pass
 tally, because a skip count is true only on the machine that measured it —
 `tests/test_readme_counts.py` derives both and fails if either drifts.
 
-Run it dependency-free and the 34 skip. Install the referee and they run.
+Run it dependency-free and the 40 skip. Install the referee and they run.
 
 **No pass/skip tally is quoted here on purpose.** The first version of this
 section did, and both numbers were wrong within a day — not because tests

{fleet_sensor_baseline-0.2.0 → fleet_sensor_baseline-0.2.2}/README.md

@@ -6,9 +6,26 @@
 list of machines and the history of captures, and answers the two questions the
 referee cannot.
 
-**Released — 0.2.0**, tagged `v0.2.0`, Apache-2.0, on PyPI as
+**Released — 0.2.2**, tagged `v0.2.2`, Apache-2.0, on PyPI as
 `fleet-sensor-baseline`.
 
+**0.2.2 adds `compare`, the threshold audit across time.** `drift` reads records
+and never opens a walk, so a threshold edited on a sensor that stayed present was
+invisible to it — and invisible to `collect --etag-cache` too, which is why a
+skip record says it proves membership. `compare` resolves the newest capture at
+or before each of two times, per surface, and hands both to the referee's
+`regression`. A record filed from a skip is refused as an input: it reuses the
+earlier payload, so comparing against one would judge a file against itself and
+report no drift.
+
+**0.2.1 closes the seam with the referee, and fixes a validator that could
+not check the one file it most needed to.** `baseline --for-referee` writes the
+referee's declaration-source format, which both projects described and neither
+produced; it comes out as a candidate nobody has signed, and it does not declare
+the sensors the cohort disagreed about. Separately, `validate` refused every
+`targets/2` file while naming `targets/2` among the formats it read — so the
+format that exists to carry `pin_sha256` was the one the checker would not check.
+
 **0.2.0 is a compatibility break, and it changes an answer.** The presence
 threshold was a single line, so a sensor either belonged to the baseline or was
 foreign to it — and at rack scale the majority won. On 24 trays where 2 lost a
@@ -45,7 +62,9 @@ pip install fleet-sensor-baseline
 
 The core has **no dependencies**. Ingest, baseline, outliers, drift, verdict and
 validate are JSON and arithmetic, so the vertical and horizontal axes run on a jump
-host with nothing provisioned. The collector needs the referee on PATH:
+host with nothing provisioned. `collect` and `compare` both need the referee on
+PATH -- one to walk a BMC, the other to judge two stored walks -- and the extra
+is named for the first only because renaming it would break every install line:
 
 ```
 pip install "fleet-sensor-baseline[collect]"
@@ -68,14 +87,56 @@ fleet-sensor-baseline outliers --store fleet-store --baseline baseline.json
 # the fleet run: every expected unit must have reported
 fleet-sensor-baseline verdict --store fleet-store --expect-units racks.txt
 
+# did a threshold move between two stored walks? ask the referee
+fleet-sensor-baseline compare --store fleet-store --unit h-0042 \
+    --before 2026-08-01T00:00:00Z --after 2026-08-20T00:00:00Z
+
 # check any artifact against the format it declares
 fleet-sensor-baseline validate baseline.json
 
+# hand the cohort's baseline back to the referee, as a candidate
+fleet-sensor-baseline baseline --store fleet-store --model GB200-NVL-tray \
+    --out baseline.json --for-referee declaration.json
+
 # walk a rack of BMCs yourself, serially, and file what comes back
 fleet-sensor-baseline collect --targets rack-17.json --store fleet-store \
     --collector-id rack-17
 ```
 
+### Handing a baseline back to the referee
+
+`--for-referee PATH` writes the cohort's baseline a second time, in
+`bmc-sensor-audit/fleet-baseline/1` — the referee's own declaration-source
+format, for `coverage --declaration`. It is the third source in that tool's
+precedence, under entity-manager and under a reviewed `pdr/1`.
+
+**It comes out as a candidate.** `"reviewed": null`, so the referee refuses to
+consume it until a person adds their name and a date. The conversion is not the
+review: a baseline derived from a fleet of unprovisioned boards is an empty
+declaration that reads healthy against every other unprovisioned board, and at
+fleet scale consensus makes that answer look corroborated. A marker this tool
+could write is a marker nobody put their name to, so there is no flag to write
+one.
+
+**The sensors the cohort disagreed about are not declared.** That band exists
+because a proportion is a coarse instrument at rack scale; the referee's format
+has two states, not three, and declaring a divergent sensor would expect it of
+every unit while 8 percent of the fleet does not have it — charging each of
+those units a finding for a fact about the cohort. That is the 0.1.x inversion,
+reached through a different door. They are written into the file under
+`divergent_not_declared`, which the referee ignores by its own `/1` rule, and
+named on stderr at export: the reviewer is the reader who needs them.
+
+The cohort must be scoped to one model — `--model`, or `--for-referee-platform`
+to name it directly — because the referee requires a platform on every
+declaration and a cohort spanning models has no single answer.
+
+`tests/test_seam.py::TestTheExportedDeclarationIsWhatTheRefereeReads` runs the
+real `bmc-sensor-audit` against a file this emits: refused as a candidate,
+consumed once reviewed, and the unit that lost the divergent sensor coming back
+clean — with the counterfactual that declares it anyway and watches the same
+unit get charged.
+
 ### Asking before walking
 
 ```
@@ -150,8 +211,10 @@ renders incompleteness as silence renders a dead collector as a clean rack.
    is never the source of judgment. Silence cannot impersonate a pass.
 2. **Never metric values.** This audits presence and configuration, not readings.
 3. **Never majority-truth over declarations.** A fleet-derived baseline is an
-   *additional, labeled, downgraded* declaration source. Wherever a manufacturer
-   declaration exists, it wins.
+   *additional, labeled, downgraded* declaration source — reachable through
+   `baseline --for-referee`, which writes the referee's own format as a
+   candidate nobody has signed yet. Wherever a manufacturer declaration exists,
+   it wins.
 4. **Never identity inside the referee's artifacts.** The walk payload carries no
    `unit_key`. Identity binds here.
 
@@ -191,9 +254,34 @@ key the file declares rather than on a shape guessed from the fields present.
 
 See [docs/formats.md](docs/formats.md).
 
-## Storage
+## Comparing across time
 
-### When the cohort disagrees with itself
+`drift` answers what changed in the RECORDS -- firmware, the sensor set, which
+units reported. It does not open the walks. A threshold edited on a sensor that
+stayed present is invisible to it, and invisible to `collect --etag-cache` too:
+a collection ETag moves when membership changes, so a skip record says in as
+many words that it proves `membership`, and the docs say membership is not
+enough for a threshold audit.
+
+`compare` is the missing half, and it is selection rather than judgment. It
+resolves the newest capture at or before each of two times, pulls both payloads
+out of the store, and hands them to `bmc-sensor-audit regression`, whose job
+this is. `--strict-fields` and `--aggregation-prefix` pass straight through.
+Exit codes come back in the family's vocabulary; the referee's refusals come
+back in the referee's own words.
+
+**A record filed from a skip is refused as an input, and that rule is the whole
+point rather than tidiness.** A skip reuses the earlier capture's payload
+digest, so comparing a walk against one resolves both ends to the same stored
+object: the referee would be handed a file and itself, and would correctly
+answer *no drift*. The question asked was whether a threshold moved. Force a
+full walk for that surface, or pick a time when one was taken.
+
+Pairing is surface to surface, per [a unit is a tuple](#a-unit-is-a-tuple), so a
+machine answering on a host BMC and an HMC gets one comparison each rather than
+one compared against the other.
+
+## When the cohort disagrees with itself
 
 A sensor is **expected** at or above `--present-threshold` (0.99), **foreign** at
 or below `--absent-threshold` (0.01), and between the two the cohort simply
@@ -243,9 +331,16 @@ to surface; presence across the cohort is the union across a unit's surfaces.
 ## The boundary
 
 This package **never imports `bmc_sensor_audit`**. It reads exit codes, stdout and
-the files the tool writes. One module is exempt — `collect/backends/mock.py`, which
-imports the referee's `MockBMC`, and the distinction is the design: that is a fake
-*machine*, standing in for the thing being walked, not the thing doing the walking.
+the files the tool writes. One module is exempt — `collect/backends/mock.py` — and
+the distinction is the design: it stands in for the thing being walked, not the
+thing doing the walking.
+
+It imports the referee's mock BMC *and* its `RedfishClient` and `walk_chassis`, so
+the payloads it produces are real `walk/1` files written by the real walker rather
+than approximations of them. The exemption is file-level and that is the actual
+contract `tests/test_boundary.py` enforces; an earlier version of this sentence
+named only the mock, which was narrower than the code and would have made a
+correct file look like a violation.
 
 `tests/test_boundary.py` asserts both halves by reading the source: that nothing
 else imports it, and that the mock backend still does. Without the second, the
@@ -255,15 +350,15 @@ first would pass by finding nothing.
 
 | | count |
 |---|---|
-| tests collected | 280 |
-| of those, requiring `bmc-sensor-audit` | 34 |
+| tests collected | 363 |
+| of those, requiring `bmc-sensor-audit` | 40 |
 
 **The predicate**: `pytest --collect-only` over the test files git tracks, and
 the same again with `-m seam` for the second row. Collection rather than a pass
 tally, because a skip count is true only on the machine that measured it —
 `tests/test_readme_counts.py` derives both and fails if either drifts.
 
-Run it dependency-free and the 34 skip. Install the referee and they run.
+Run it dependency-free and the 40 skip. Install the referee and they run.
 
 **No pass/skip tally is quoted here on purpose.** The first version of this
 section did, and both numbers were wrong within a day — not because tests

{fleet_sensor_baseline-0.2.0 → fleet_sensor_baseline-0.2.2}/docs/formats.md

@@ -1,10 +1,30 @@
 # Formats
 
-Four, each versioned in its own key and each with a validator that ships, because
-**the person who receives the file is the one who needs to check it.** A control
-plane ingesting thousands of records has to be able to refuse a malformed one
-using the format's own words, not a shape it inferred from the files that
-happened to arrive first.
+Six this build reads, each versioned in its own key and each with a validator
+that ships, because **the person who receives the file is the one who needs to
+check it.** A control plane ingesting thousands of records has to be able to
+refuse a malformed one using the format's own words, not a shape it inferred
+from the files that happened to arrive first.
+
+| format | is |
+|---|---|
+| `fleet-sensor-baseline/fleet-record/1` | one capture of one unit |
+| `fleet-sensor-baseline/fleet-baseline/1` | **superseded; refused, not upgraded** |
+| `fleet-sensor-baseline/fleet-baseline/2` | a derived declaration, carrying `divergent` |
+| `fleet-sensor-baseline/summary/1` | a verdict, in the family's one vocabulary |
+| `fleet-sensor-baseline/targets/1` | the collector's rack list |
+| `fleet-sensor-baseline/targets/2` | the same, and may declare `pin_sha256` |
+
+and one it **writes for somebody else to read**:
+`bmc-sensor-audit/fleet-baseline/1`, produced by `baseline --for-referee`. That
+one is not validated here; the tool that consumes it is the tool that checks it.
+
+`tests/test_formats.py::TestThisDocumentNamesEveryFormat` derives this list from
+the code. It exists because the list was hand-written and went stale: for two
+releases this page opened *Four*, presented `fleet-baseline/1` as current, and
+did not mention `targets/2` or the `divergent` band at all — while the README,
+whose count IS pinned by a test, said six. Two records of one fact, and the
+unguarded one drifted.
 
 Every validator returns *problems* rather than raising, so a caller reports all
 of them at once instead of one per run. Every one checks **malformation only**:
@@ -91,43 +111,95 @@ per identity, and position in the file decides, not the timestamp.
 
 ---
 
-## `fleet-sensor-baseline/fleet-baseline/1`
+## `fleet-sensor-baseline/fleet-baseline/2`
 
 A derived declaration, labeled as such.
 
 ```json
 {
-  "format": "fleet-sensor-baseline/fleet-baseline/1",
+  "format": "fleet-sensor-baseline/fleet-baseline/2",
   "scope": {"model": "GB200-NVL-tray", "firmware_range": ">=1.4,<1.5"},
   "derived": {"units": 1987, "present_threshold": 0.99,
+              "absent_threshold": 0.01,
               "captured_between": ["2026-08-01T00:00:00Z",
                                    "2026-08-21T00:00:00Z"]},
   "sensors": [{"name": "Fan_CPU_1", "uri_suffix": "/Sensors/Fan_CPU_1",
                "present_ratio": 0.9975}],
+  "divergent": [{"name": "Fan_CPU_2", "present_ratio": 0.916667,
+                 "present_on": 22, "of": 24}],
   "provenance": "fleet-derived",
   "notice": "This baseline was derived from the fleet, not declared by a manufacturer. It cannot see an absence the whole cohort shares."
 }
 ```
 
 **The `notice` sentence is part of the format.** Every consumer that judges
-against a `fleet-baseline/1` prints it verbatim, and the validator refuses a
-baseline that lost it or reworded it. That is not pedantry about prose: a
-baseline without the sentence validates as a manufacturer declaration everywhere
-downstream, and the loss is invisible because every other field still reads
-correctly.
+against a baseline prints it verbatim, and the validator refuses a baseline that
+lost it or reworded it. That is not pedantry about prose: a baseline without the
+sentence validates as a manufacturer declaration everywhere downstream, and the
+loss is invisible because every other field still reads correctly.
 
-`provenance` carries the same fact in a machine-readable field, and every
-summary this layer emits records which kind of truth decided it.
+`provenance` carries the same fact in a machine-readable field, and every summary
+this layer emits records which kind of truth decided it.
 
-**A baseline refuses to derive from fewer than 20 units** (`--floor N` to change
-it, explicitly). A cohort of nine is an anecdote wearing a format key: at that
-size one unlucky machine moves every ratio past any threshold worth setting.
+### `divergent` — the third state, and why the format had to move
+
+A sensor is **expected** at or above `present_threshold`, **foreign** at or below
+`absent_threshold`, and between the two the cohort **disagrees with itself**. That
+middle band is reported once, against the cohort, naming the minority, and charged
+to no unit.
+
+Two states were not enough, and the failure was not a miss — it was an inversion.
+With 22 of 24 trays carrying a sensor the ratio is 0.9167, below the 0.99 default,
+so the sensor left the baseline entirely and every tray that **had** it was
+reported as carrying something unexpected while the two that had lost it came back
+clean. A proportion is a coarse instrument at rack scale: 0.99 of 24 is 23.76, so
+one deviant unit crosses it, and `--floor` admits cohorts from 20.
+
+**`divergent` is why this is `/2` and not a new key on `/1`.** An unknown format
+is refused; an unknown key is dropped. A reader that predated the key would ignore
+it and charge every divergent sensor to the units that have it — the same
+inversion, arrived at silently, which is the one way it could get worse.
 
 `uri_suffix` is written **only when every contributing unit agrees**. Matching is
 by name regardless; a baseline asserting one URI while the cohort reports several
 would be asserting something no unit said, and advisory metadata that is wrong is
 worse than absent.
 
+**A baseline refuses to derive from fewer than 20 units** (`--floor N` to change
+it, explicitly). A cohort of nine is an anecdote wearing a format key: at that size
+one unlucky machine moves every ratio past any threshold worth setting.
+
+## `fleet-sensor-baseline/fleet-baseline/1`
+
+**Superseded. Refused, and deliberately not upgraded.**
+
+A `/1` recorded only the sensors that cleared the presence threshold and silently
+forgot every sensor the cohort disagreed about. `validate` refuses one and says
+why; nothing reads it. There is no migration path and there cannot be one: the
+information needed to judge was discarded at derivation, so a `/1` cannot be told
+apart from a cohort that genuinely never had those sensors. **Derive again** — the
+records it came from are still in the store, which is what an append-only store is
+for.
+
+## `bmc-sensor-audit/fleet-baseline/1` — written, not read
+
+`baseline --for-referee PATH` writes the referee's declaration-source format, so a
+cohort baseline can be used as the third source in `bmc-sensor-audit coverage`.
+It is specified in that repository's `docs/declaration-sources.md`, not here, and
+this build has no validator for it — the consumer is the checker.
+
+Two properties of the conversion belong on this page because they are decisions
+about what a format may lose:
+
+- **It is a candidate.** `"reviewed": null`, so the referee refuses it until a
+  person adds their name and a date. The conversion is not the review.
+- **The divergent band does not cross.** The referee's format has two states, not
+  three, because it judges one machine against a list of what that machine should
+  have. Divergent sensors are carried under `divergent_not_declared`, a key that
+  reader ignores by its own `/1` rule, and named on stderr at export. Declaring
+  them would rebuild the inversion one tool over; dropping them without a word
+  would rebuild `/1`.
+
 ---
 
 ## `fleet-sensor-baseline/summary/1`
@@ -174,6 +246,53 @@ satellites is fine — that is one machine with two surfaces.
 
 ---
 
+## `fleet-sensor-baseline/targets/2`
+
+The same rack list, and the only one that may declare a certificate pin.
+
+```json
+{
+  "format": "fleet-sensor-baseline/targets/2",
+  "targets": [
+    {"unit_key": "h-0042", "base_url": "https://192.0.2.1",
+     "pin_sha256": "AB:CD:...:EF", "password_env": "BMC_PASS_RACK17"}
+  ]
+}
+```
+
+**A pin is an expectation, not a credential.** A SHA-256 fingerprint of a public
+certificate is public — anyone who can connect can compute it — so it belongs in
+the file, where a change to it shows up in a review diff. A CA bundle is a path on
+one operator's disk and is `collect --cafile PATH` instead.
+
+**Version 2 exists for one reason: a declaration an older reader would IGNORE.**
+`pin_sha256` says *require exactly this certificate*. A reader that does not know
+the key would drop it and connect unpinned — a security expectation stated by an
+operator and met with silence. An older build refuses an unknown format outright,
+so bumping is what turns a silent downgrade into a refusal. `targets/1` stays
+valid and stays the right choice for a rack list that pins nothing.
+
+The validator refuses, in the file, before any connection is made:
+
+- `pin_sha256` in a `targets/1`, naming `targets/2` as what to write instead;
+- `pin_sha256` beside a `base_url` that is not `https` — nothing would verify the
+  connection. The referee refuses this too, from 0.1.4, but a rack list is
+  reviewed long before it is run, and catching it in the file is catching it where
+  somebody is looking;
+- a fingerprint that is not 64 hex digits, colons optional;
+- `pin_sha256` beside `insecure` — two answers to one question, and whichever won
+  would be a guess about which the operator meant.
+
+**This section is here because `validate` could not check any of it.** `targets/2`
+shipped in the format list and not in the dispatch table, so every `targets/2` file
+was refused — with a message that named `targets/2` among the formats it had just
+said it read. The validator had handled both versions from the day `/2` landed;
+only the wiring was missing, and every test called the validator directly rather
+than through `validate`. The format that exists to carry a security expectation was
+the one the checker would not check.
+
+---
+
 ## Content handles
 
 `payload_digest` is `sha256:` and the hex digest of the **file bytes**, identical

{fleet_sensor_baseline-0.2.0 → fleet_sensor_baseline-0.2.2}/docs/upstream-asks.md

@@ -193,7 +193,11 @@ than absorbed:
   matches `\bsensor set unchanged\b`. That works and is the wrong kind of
   contract: prose can be reworded without it reading as a breaking change, while
   `walk/1`'s format string carries a written stability statement. Filed as
-  [#6](https://github.com/james-sheen/bmc-sensor-audit/issues/6), **open**.
+  [#6](https://github.com/james-sheen/bmc-sensor-audit/issues/6), **closed in
+  `bmc-sensor-audit` 0.1.3 and consumed here** -- Section 5 below is the same
+  ask, written up. This bullet said *open* for two days after the fix shipped,
+  while the table above and Section 5 both said consumed: one fact recorded in
+  three places, and the copy nobody re-read was the stale one.
 - A test assertion written expecting the old digest-dedup behaviour FAILED,
   which is how the *store collapses a homogeneous fleet* claim was finally
   measured and found false. See `store.py`.

{fleet_sensor_baseline-0.2.0 → fleet_sensor_baseline-0.2.2}/pyproject.toml

@@ -70,6 +70,11 @@ dependencies = []
 # this floor rather than merely old, and `preflight()` can refuse instead of
 # saying it could not tell. That is the whole reason this floor moved: the check
 # was written before the thing it checks existed.
+#
+# **The name is narrower than the contents, and renaming it would break every
+# caller's install line.** `compare` needs the referee too -- it hands two
+# stored walks to `regression` -- so this extra now gates two commands. Both
+# were verified against every release the range admits: 0.2.0, 0.2.1, 0.2.2.
 collect = ["bmc-sensor-audit>=0.2.0,<0.3"]
 dev = ["pytest>=7"]
 

{fleet_sensor_baseline-0.2.0 → fleet_sensor_baseline-0.2.2}/src/fleet_sensor_baseline/__init__.py

@@ -15,6 +15,6 @@ from __future__ import annotations
 # read this to decide whether the README may name a tag at all: an unreleased
 # tree that announces `v0.1.0` hands a reader a tag to check out that does not
 # exist. Bump this at step 1 of a release, not at step 9.
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 __all__ = ["__version__"]

{fleet_sensor_baseline-0.2.0 → fleet_sensor_baseline-0.2.2}/src/fleet_sensor_baseline/baseline.py

@@ -1,4 +1,4 @@
-"""Deriving a `fleet-baseline/1` -- an additional, labeled, downgraded declaration.
+"""Deriving a `fleet-baseline/2` -- an additional, labeled, downgraded declaration.
 
 **Wherever a manufacturer declaration exists, it wins.** A fleet-derived
 baseline is blind to an absence the whole cohort shares, which is the founding
@@ -181,7 +181,7 @@ def derive(present_by_unit: dict[str, set[str]],
            absent_threshold: float = DEFAULT_ABSENT_THRESHOLD,
            floor: int = DEFAULT_FLOOR,
            window: tuple[str, str] | None = None) -> dict:
-    """Build the `fleet-baseline/1`. Raises `BaselineError` below the floor."""
+    """Build the `fleet-baseline/2`. Raises `BaselineError` below the floor."""
     total = len(present_by_unit)
     if total == 0:
         raise BaselineError(