Telemetry Flow Contracts V2

The authoritative TypeScript and runtime contracts are exported by @sens-platform/contracts. Storage implementation lives behind repositories in @sens-platform/database; graph compilation and execution live in @sens-platform/flow-engine.

Contract	Version	Purpose
DeviceFieldDefinitionDto	HTTP v1	Authoritative Device-Type field contract
FlowGraphV2	flow-graph.v2	Device-bound editable DAG with two storage sinks
CompiledFlowPlanV2	compiled-flow-plan.v2	Executable nodes and pinned storage bindings
DeviceOutputFieldSnapshotV1	snapshot v1	Technical released field snapshot
FlowExecutionInputV2	input v2	Separates Netmore and local receipt timestamps
CurrentValueIntentV1	intent v1	Side-effect-free current-snapshot write
MeasurementIntentV2	intent v2	Field-bound Timeseries write
FlowExecutionResultV2	result v2	Current, Timeseries, E-mail Action, trace, and errors
FlowTemplateGraphV2	flow-template-graph.v2	UUID-free field requirements for reusable templates

Graph invariants

A graph contains its deviceTypeId, up to 100 executable blocks, exactly one current-output, exactly one timeseries-output, edges, and parameters. The system sinks have no outputs. Their fields are the target-specific projection of the Device-Type catalog.

Edges require exact schemaRef equality. Each target port accepts at most one edge. Both ports of a dual-target field are either unconnected or connected to the same source node and port. Deprecated fields cannot receive new edges. Unconnected fields produce warnings rather than release errors.

Raw Input exposes rawPayload, the complete connectionData, the optional Netmore messageType, and the normalized gateways array. Netmore Connection Data accepts connectionData and publishes the optional Number outputs batteryLevel, fcntup, snr, rssi, dr, spreadingFactor, and freq. They can connect directly to Number fields on the Current Values and Timeseries storage nodes. The retained connectionData passthrough remains compatible with existing graphs.

Release compares every technical snapshot with the current field catalog and persists flow_version_field_bindings. Display-name or description changes do not invalidate an otherwise identical technical snapshot. Key, schema, unit, measurement type, targets, and lifecycle status are compatibility boundaries.

Timestamp and write semantics

observedAt is the normalized Netmore timestamp and is copied unchanged to Current-Value and Measurement intents. rawReceivedAt is the local MQTT/Raw receipt time and is used only for provenance and deterministic tie-breaking.

The Flow worker commits Measurements, Current Values, E-mail Action jobs and their outbox rows, and successful execution state in one SQL transaction. No partial storage is valid. An absent optional block output produces no intent.

Every valid Measurement is written. Current Values advance only for newer observedAt; equal business timestamps use Raw receipt and execution identity. A replay of the same latest Raw row may replace its value with a correction.

Flow administration HTTP collections

Counted administration responses contain items, optional nextCursor, and totalCount; accepted page sizes are 25, 50, and 100. This applies to Custom blocks, Flow templates, E-mail templates, recipient bindings, test fixtures, and parameter values. Their q filter is evaluated inside the authorized tenant or platform scope before the count and page are produced.

Immutable Custom-block, Flow-template, and E-mail-template version histories contain items and optional nextCursor, never totalCount. The released Custom-block Studio selector has a fixed 50-item page and server-side q. Built-in manifests and their schemas remain a complete hard-bounded registry response. Cursors are opaque and bound to the actor, authorization scope, collection, parent, filter, and limit; clients must not reuse them across those boundaries.

The collection response change from bare arrays to cursor-page objects requires the Platform API and web console from this release to be deployed together. There is no database migration or new configuration. Rollback must restore both components to the preceding version; mixed old/new API and console versions are not compatible for these administration lists.

Compatibility

The MQTT ingestion and RawStoredEventV1 contracts are unchanged. Existing imported or legacy Measurements may have null Device-Type and field-definition references. V2 writes must set both. flow-graph.v1 remains parseable only for deprecated template history and is not an executable fallback.

The new Raw Input ports and Netmore Connection Data Number ports are additive to their existing builtin v1 manifests. Existing compiled plans keep their previous behavior; drafts may connect the additional outputs without a graph migration.