The vibration edge (`vibration-edge`) can post straight to OpexMX. Put OpexFlow in between and the same
windows gain a record of what arrived, a check against the contract, thinning that keeps one sensor under
the OpexMX rate limit, and a queue of what OpexMX refused or could not take. The edge needs no change: it
already lets you choose the URL it posts to.

The flow is the example **Vibration edge to OpexMX** (Examples, Plant). It runs with a mock OpexMX the moment
it is deployed.

## What the edge sends

| Edge output | Sent when | Goes to |
| --- | --- | --- |
| `POST {url}/inference`, camelCase JSON: `sensorId`, `probability`, `label`, `alert`, `rms`, `timestamp`, `modelVersion`; v2 (`--method multifault`) adds `schemaVersion`, `taxonomyVersion`, `featureVersion`, `faults[]`, `acquisition`, `severity` | every window with `--push-mode continuous`; with `gated` (default) on alert onset, every `--burst-secs` during an alert, on resolve and every `--heartbeat-secs`. `--method fft` sends it for a normal window unless `--fft-push always` | OpexMX `POST /api/vibration-monitoring/inference` |
| `POST {url}/spectrum`: `sensorId`, `sampleRate`, `windowSize`, `unit`, `rms`, `bins[]`, `alert`, `timestamp` | `--method fft`, for a fault window, or for every window with `--fft-push always` | OpexMX `POST /api/vibration-monitoring/spectrum` |
| MQTT `opexmx/ingest/<sensorId>`, the same data in snake_case | `--mqtt-host` set | the NATS MQTT gateway (see below) |

Every post carries `Authorization: Bearer <token>`. OpexMX binds one `mx_…` key to one sensor and answers `401`
for a window of another sensor. OpexMX allows 120 requests per minute per key, shared by `/inference` and
`/spectrum`, and answers `429` with `Retry-After` above that.

The edge appends `/inference` and `/spectrum` to `--opexmx-url` itself, so pointing it at OpexFlow is one flag:

```bash
vibration-edge --serve --method fft --csv data/9mei_50hz.csv --fft-channel 2 --fft-unit g \
  --sensor-id <sensor id> --rpm 3000 --line-freq 50 \
  --push-mode continuous --fft-push always \
  --opexmx-url http://<opexflow>:3600/api/ingest/vibration \
  --opexmx-token <an OpexFlow API token>
```

The two flow sources are `vibration:inference` and `vibration:spectrum` (`POST /api/ingest/vibration/inference`
and `.../spectrum`). The bearer token is OpexFlow's, not OpexMX's: the sensor's `mx_…` key stays in OpexFlow
as a [secret](/docs/security) and is added when the window is forwarded.

> **Caution**
>
> The edge also reads the sensor's server configuration (rpm, bearing, acquisition, active model) from
> `<url>/api/vibration-monitoring/sensors/<id>/status` with the same token. Pointed at OpexFlow that call
> answers 404 and the edge falls back to its command-line settings (`--rpm`, `--bearing-*`, `--iso-class`).
> Set them on the edge, or point only the status sync at OpexMX with `--config-sync-url` (it then sends the
> OpexFlow token, which OpexMX refuses, so the sync stays off).

## The flow

```text
vibration:inference -> Clean inference -> Contract v1/v2 -> Value rules ─┐
vibration:spectrum  -> Clean spectrum  -> Spectrum contract -> Value rules ┴-> Once per sensor + timestamp
   -> Alert or normal -> [alert] 1 per ALERT_EVERY s  -> Post alert  (retry 4x) ─ still down: park (held for redrive)
                  -> [else]  1 per NORMAL_EVERY s -> Post normal (retry 4x) ─ still down: shed
    a 4xx answer: dead-lettered by the http node for a person (it never takes the error wire)
   once ──────────────> inference windows -> event -> local history
schedule (optional)  -> every 15 s replay parked alerts
```

| Step | Node | What it does |
| --- | --- | --- |
| Clean | [`prep`](/docs/clean-data) | Casts numbers with decimal commas or as text (`"0,91"`, `rms.*`, `faults.*.probability`; a value that is not a number fails the record and names the field), the alert flag, and the timestamp to UTC with a `Z` (OpexMX refuses the edge's `+00:00` on `/spectrum`; an offset such as `+07:00` and nanoseconds are converted). Trims the label. Spectrum `bins` that are `null` (the edge writes NaN as null) or text are interpolated from their neighbours; a gap at either end stays `null` and the contract check refuses the window. Then it **moves the fields OpexMX knows into `request`**, so an unknown field is not forwarded, and sets `kind`. |
| Contract | [`validate`](/docs/business-events#validate-node) | The catalogue types `vibration.inference` (v1 passes, v2 requires `faults[]`) and `vibration.spectrum`. A broken window is quarantined in the [dead-letter queue](/docs/operations#dead-letters-correct-and-replay) with every rule it broke. |
| Value rules | [`quality`](/docs/data-quality) | `sensor_known` (a window of another sensor), `probability_0_1`, `label_present`, `rms` not negative, `sample_rate_positive`, `window_size_max` (65536, OpexMX's limit), `bins_present`, `timestamp_not_ahead` (a clock more than an hour ahead). Each is `fail`: the window is parked with the rule name. |
| Once | [`dedupe`](/docs/flows#dedupe-idempotency) | `sensorId@timestamp/kind`, one day. The edge resends the same body when OpexFlow answers late. The key is committed only after OpexMX took the window, so a failed delivery can be sent again. |
| Alert or normal | `branch` | An alert is `alert: true`, or an inference whose label is not `Mesin Normal` (v2: the label is the top flagged fault). |
| Anti-flood | `dedupe` with a short TTL | The first record per sensor and kind passes, the rest of that interval is dropped. Alerts: one per `ALERT_EVERY` s (default 2); normal windows and heartbeats: one per `NORMAL_EVERY` s (default 10). Two kinds and two lanes give at most 72 requests per minute per sensor, under the 120 limit, and an alert is never held back by a heartbeat that just passed. |
| Post | `http` with `retry` | `POST <OpexMX>/api/vibration-monitoring/{inference\|spectrum}`, `auth: bearer` (the sensor's secret), `body_from: request`. Four attempts with 0.5 s doubling back-off (capped at 4 s, `Retry-After` honoured) for network errors, timeouts, 408, 429 and 5xx. `error_on: transient`: only a call still failing after the attempts takes the error wire; a 4xx does not. |
| Hold / shed | `park` / `filter` | An alert that could not be delivered is **parked** with the reason `[redrive:<sensor>] held, OpexMX unavailable: …`; a normal window is shed (the next one is seconds away). |
| History | `event` + `storage` | Every de-duplicated inference window is stored as the event `vibration.inference` (idempotent on `sensorId@timestamp`, kept 90 days, `GET /api/events/log?type=vibration.inference&subject=<sensor>`), before the thinning, so history holds every window while OpexMX gets the thinned stream. |

### What was kept, and why

| Kept | Why a newer node does not replace it |
| --- | --- |
| `dedupe` as the per-sensor throttle | The only node with a hard guarantee of "at most one per N seconds". [`deadband`](/docs/time-series#deadband) passes any change at once (a flapping probability still floods; its `heartbeat` is a floor, not a ceiling), and [`window`](/docs/time-series#window) emits an aggregate, not the original window OpexMX expects. A `deadband` in front of the normal lane would only add noise. |
| The redrive tick (optional) | `park` replaces the JavaScript hold step and keeps the alert safe, but no node replays parked rows on a schedule; without the tick a person replays them (Dead letters, or one `POST /api/pipeline/dead-letters/replay`). The tick is that call on a clock. |
| `non_idempotent: true` on the post | OpexMX ignores an `Idempotency-Key`, so a retry after a lost answer can store a window twice. Accepting that is better than losing the alert. |

Not possible with the new nodes: checking that `bins` is `windowSize/2 + 1` long. `quality` has no array length and `validate` cannot compare two fields; OpexMX answers 400 and the window is dead-lettered with its message.

[`signal`](/docs/signal-features) is not used: the edge sends results, not raw windows. If you send raw waveforms to OpexFlow, a `signal` node computes the spectrum, ISO 20816 zone and bearing frequencies there (see the example *Vibration features*), and the edge's server-side sync of rpm and bearing settings is no longer needed.

## Delivery and failure

| OpexMX answers | What happens |
| --- | --- |
| `201` | Done. The key is committed. The edge gets `200`. |
| `400`, `401`, `403`, `404` | The http node fails the record for good: dead-lettered at `post_alert` / `post_normal` with OpexMX's answer. The edge gets `422` and does not resend. Fix the cause (register the sensor, correct the key secret, edit the record) and replay the row. |
| `429`, `5xx`, timeout, refused | Retried four times. If it still fails: an alert is parked (`[redrive:<sensor>]`), a normal window is shed. The edge gets `422`. |

The optional **Redrive tick** (enable it by giving the input *This connector's URL*) replays rows tagged
`[redrive:<sensor>]` every 15 seconds, 200 at a time, through the whole flow. A replay passes the de-duplication
because the first delivery never committed its key. It needs `OPEX_API_TOKEN` in the environment and in
`transform.executor.http_env_allowlist`.

Limits:

- OpexMX does not de-duplicate. If it stored a window but the answer was lost, the retry or the replay stores it again.
- A retry holds the sensor's lane for up to about 6 seconds, because records of one sensor run in order. During an outage the edge's 10 s timeout can fire first; the edge then resends and the duplicate is dropped.
- During an outage every alert that passed the throttle is parked; the dead-letter queue keeps 10 000 rows.
- A window delivered late is stored by OpexMX with its delivery time, not the edge timestamp.
- OpexMX turns a database failure into `400`, which is dead-lettered for a person; read the message (`D1_ERROR`) before correcting anything.

## Several sensors

A source name exists once per instance, so give each sensor its own instance: the example asks for the *Edge
source name* (`vibration`, `vibration-pump2`, …), the *Sensor id* and the *name of the secret* with that sensor's
key. The edge of that sensor posts to `/api/ingest/<source name>`. A window with another sensor id is refused, so a
mis-configured edge cannot write into a neighbour's record.

## Over MQTT instead

The edge can publish to the NATS MQTT gateway (`--mqtt-host`). MQTT carries snake_case keys in a machine record (`metadata.value`). Add a NATS or MQTT source and put `prep` steps in front
of the **Clean** node that `flatten`/`rename` it to the HTTP shape (`sensor_id` → `sensorId`, `latency_us` → `inferenceLatUs`,
`faults[].gate_reason` → `gateReason`); the flow has no such steps today (the earlier JavaScript version did), and MQTT carries no spectrum.