export: align reanimator contract v2.7

bible-local/03-api.md

@@ -55,6 +55,23 @@ Responses:
 - `400` on malformed JSON
 - `422` on validation errors
 
+Optional request field:
+- `power_on_if_host_off`: when `true`, Redfish collection may power on the host before collection if preflight found it powered off
+
+### `POST /api/collect/probe`
+
+Checks that live API connectivity works and returns host power state before collection starts.
+
+Typical request body is the same as `POST /api/collect`.
+
+Typical response fields:
+- `reachable`
+- `protocol`
+- `host_power_state`
+- `host_powered_on`
+- `power_control_available`
+- `message`
+
 ### `GET /api/collect/{id}`
 
 Returns async collection job status, progress, timestamps, and accumulated logs.

bible-local/05-collectors.md

@@ -20,12 +20,28 @@ Request fields passed from the server:
 - `auth_type`
 - credential field (`password` or token)
 - `tls_mode`
+- optional `power_on_if_host_off`
 
 ### Core rule
 
 Live collection and replay must stay behaviorally aligned.
 If the collector adds a fallback, probe, or normalization rule, replay must mirror it.
 
+### Preflight and host power
+
+- `Probe()` may be used before collection to verify API connectivity and current host `PowerState`
+- if the host is off and the user chose power-on, the collector may issue `ComputerSystem.Reset`
+  with `ResetType=On`
+- power-on attempts are bounded and logged
+- after a successful power-on, the collector waits an extra stabilization window, then checks
+  `PowerState` again and only starts collection if the host is still on
+- if the collector powered on the host itself for collection, it must attempt to power it back off
+  after collection completes
+- if the host was already on before collection, the collector must not power it off afterward
+- if power-on fails, collection still continues against the powered-off host
+- all power-control decisions and attempts must be visible in the collection log so they are
+  preserved in raw-export bundles
+
 ### Discovery model
 
 The collector does not rely on one fixed vendor tree.

bible-local/07-exporters.md

@@ -35,25 +35,34 @@ Implementation files:
 Conversion rules:
 - canonical source is merged canonical inventory derived from `hardware.devices` plus legacy hardware slices
 - output must conform to the strict Reanimator ingest contract in `docs/hardware-ingest-contract.md`
+- local mirror currently tracks upstream contract `v2.7`
 - timestamps are RFC3339
 - status is normalized to Reanimator-friendly values
-- missing PCIe serials may be generated from board serial + slot
-- missing CPU serials may be generated from board serial + socket
+- missing component serial numbers must stay absent; LOGPile must not synthesize fake serials for Reanimator export
 - CPU `firmware` field means CPU microcode, not generic processor firmware inventory
 - `NULL`-style board manufacturer/product values are treated as absent
 - optional component telemetry/health fields are exported when LOGPile already has the data
 - partial `hardware.devices` must not suppress components still present only in legacy parser/collector fields
 - `present` is not serialized for exported components; presence is expressed by the existence of the component record itself
+- Reanimator ingest may apply its own server-side fallback serial rules for CPU and PCIe when LOGPile leaves serials absent
 
 ## Inclusion rules
 
 Included:
-- PCIe-class devices even when serial must be synthesized
-- contract `v2.4` component telemetry and health fields when source data exists
-- hardware sensors grouped into `fans`, `power`, `temperatures`, `other`
+- PCIe-class devices when the component itself is present, even if serial number is missing
+- contract `v2.7` component telemetry and health fields when source data exists
+- hardware sensors grouped into `fans`, `power`, `temperatures`, `other` only when the sensor has a real numeric reading
+- sensor `location` is not exported; LOGPile keeps only sensor `name` plus measured values and status
 - Redfish linked metric docs that carry component telemetry: `ProcessorMetrics`, `MemoryMetrics`, `DriveMetrics`, `EnvironmentMetrics`, `Metrics`
+- `pcie_devices.slot` is treated as the canonical PCIe address; `bdf` is used only as an internal fallback/dedupe key and is not serialized in the payload
+- `event_logs` are exported only from normalized parser/collector events that can be mapped to contract sources `host` / `bmc` / `redfish` without synthesizing content
+- `manufactured_year_week` is exported only as a reliable passthrough when the parser/collector already extracted a valid `YYYY-Www` value
 
 Excluded:
+- storage endpoints from `pcie_devices`; disks and NVMe drives export only through `hardware.storage`
+- fake serial numbers for PCIe-class devices; any fallback serial generation belongs to Reanimator ingest, not LOGPile
+- sensors without a real numeric reading
+- events with internal-only or unmappable sources such as LOGPile internal warnings
 - memory with missing serial number
 - memory with `present=false` or `status=Empty`
 - CPUs with `present=false`

bible-local/10-decisions.md

@@ -455,3 +455,129 @@ live collection and raw snapshot replay still underreported component health fie
   component record.
 
 <!-- Add new decisions below this line using the format above -->
+
+## ADL-025 — Missing serial numbers must remain absent in Reanimator export
+
+**Date:** 2026-03-15
+**Context:**
+LOGPile previously generated synthetic serial numbers for components that had no real serial in
+source data, especially CPUs and PCIe-class devices. This made the payload look richer, but the
+serials were not authoritative and could mislead downstream consumers. Reanimator can already
+accept missing serials and generate its own internal fallback identifiers when needed.
+
+**Decision:**
+- Do not synthesize fake serial numbers in LOGPile's Reanimator export.
+- If a component has no real serial in parsed source data, export the serial field as absent.
+- This applies to CPUs, PCIe devices, GPUs, NICs, and any other component class unless an
+  upstream contract explicitly requires a deterministic exporter-generated identifier.
+- Any fallback serial generation defined by the upstream contract is ingest-side Reanimator behavior,
+  not LOGPile exporter behavior.
+
+**Consequences:**
+- Exported payloads carry only source-backed serial numbers.
+- Fake identifiers such as `BOARD-...-CPU-...` or synthetic PCIe serials are no longer considered
+  acceptable exporter behavior.
+- Any future attempt to reintroduce generated serials requires an explicit contract review and a
+  new ADL entry.
+
+---
+
+## ADL-026 — Live Redfish collection uses explicit preflight host-power confirmation
+
+**Date:** 2026-03-15
+**Context:**
+Live Redfish inventory can be incomplete when the managed host is powered off. At the same time,
+LOGPile must not silently power on a host without explicit user choice. The collection workflow
+therefore needs a preflight step that verifies connectivity, shows current host power state to the
+user, and only powers on the host when the user explicitly chose that path.
+
+**Decision:**
+- Add a dedicated live preflight API step before collection starts.
+- UI first runs connectivity and power-state check, then offers:
+  - collect as-is
+  - power on and collect
+- if the host is off and the user does not answer within 5 seconds, default to collecting without
+  powering the host on
+- Redfish collection may power on the host only when the request explicitly sets
+  `power_on_if_host_off=true`
+- when LOGPile powers on the host for collection, it must try to power the host back off after
+  collection completes
+- if LOGPile did not power the host on itself, it must never power the host off
+- all preflight and power-control steps must be logged into the collection log and therefore into
+  the raw-export bundle
+
+**Consequences:**
+- Live collection becomes a two-step UX: probe first, collect second.
+- Raw bundles preserve operator-visible evidence of power-state decisions and power-control attempts.
+- Power-on failures do not block collection entirely; they only downgrade completeness expectations.
+
+---
+
+## ADL-027 — Sensors without numeric readings are not exported
+
+**Date:** 2026-03-15
+**Context:**
+Some parsed sensor records carry only a name, unit, or status, but no actual numeric reading. Such
+records are not useful as telemetry in Reanimator export and create noisy, low-value sensor lists.
+
+**Decision:**
+- Do not export temperature, power, fan, or other sensor records unless they carry a real numeric
+  measurement value.
+- Presence of a sensor name or health/status alone is not sufficient for export.
+
+**Consequences:**
+- Exported sensor groups contain only actionable telemetry.
+- Parsers and collectors may still keep non-numeric sensor artifacts internally for diagnostics, but
+  Reanimator export must filter them out.
+
+---
+
+## ADL-028 — Reanimator PCIe export excludes storage endpoints and synthetic serials
+
+**Date:** 2026-03-15
+**Context:**
+Some Redfish and archive sources expose NVMe drives both as storage inventory and as PCIe-visible
+endpoints. Exporting such drives in both `hardware.storage` and `hardware.pcie_devices` creates
+duplicates without adding useful topology value. At the same time, PCIe-class export still had old
+fallback behavior that generated synthetic serial numbers when source serials were absent.
+
+**Decision:**
+- Export disks and NVMe drives only through `hardware.storage`.
+- Do not export storage endpoints as `hardware.pcie_devices`, even if the source inventory exposes
+  them as PCIe/NVMe devices.
+- Keep real PCIe storage controllers such as RAID and HBA adapters in `hardware.pcie_devices`.
+- Do not synthesize PCIe/GPU/NIC serial numbers in LOGPile; missing serials stay absent.
+- Treat placeholder names such as `Network Device View` as non-authoritative and prefer resolved
+  device names when stronger data exists.
+
+**Consequences:**
+- Reanimator payloads no longer duplicate NVMe drives between storage and PCIe sections.
+- PCIe export remains topology-focused while storage export remains component-focused.
+- Missing PCIe-class serials no longer produce fake `BOARD-...-PCIE-...` identifiers.
+
+---
+
+## ADL-029 — Local exporter guidance tracks upstream contract v2.7 terminology
+
+**Date:** 2026-03-15
+**Context:**
+The upstream Reanimator hardware ingest contract moved to `v2.7` and clarified several points that
+matter for LOGPile documentation: ingest-side serial fallback rules, canonical PCIe addressing via
+`slot`, the optional `event_logs` section, and the shared `manufactured_year_week` field.
+
+**Decision:**
+- Keep the local mirrored contract file as an exact copy of the upstream `v2.7` document.
+- Describe CPU/PCIe serial fallback as Reanimator ingest behavior, not LOGPile exporter behavior.
+- Treat `pcie_devices.slot` as the canonical address on the LOGPile side as well; `bdf` may remain
+  an internal fallback/dedupe key but is not serialized in the payload.
+- Export `event_logs` only from normalized parser/collector events that can be mapped to contract
+  sources `host` / `bmc` / `redfish` without synthesizing message content.
+- Export `manufactured_year_week` only as a reliable passthrough when a parser/collector already
+  extracted a valid `YYYY-Www` value.
+
+**Consequences:**
+- Local bible wording no longer conflicts with upstream contract terminology.
+- Reanimator payloads use contract-native PCIe addressing and no longer expose `bdf` as a parallel
+  coordinate.
+- LOGPile event export remains strictly source-derived; internal warnings such as LOGPile analysis
+  notes do not leak into Reanimator `event_logs`.