Telemetry Flow Contracts V1
Status
Section titled “Status”Deprecated. flow-graph.v1 is retained only to read historical deprecated
template versions. It cannot be executed, copied, newly created, released, or
activated. New behavior is defined by Telemetry Flow Contracts V2.
The authoritative TypeScript and runtime contracts are exported by
@sens-platform/contracts; JSON Schema 2020-12 schema IDs are owned by
@sens-platform/flow-engine.
| Contract | Version or subject | Purpose |
|---|---|---|
BlockManifestV1 | manifest v1 | Immutable named ports and execution kind |
FlowBlockLibraryResponseDto | HTTP v1 | Executable references plus visible JSON Schemas |
FlowGraphV1 | flow-graph.v1 | Editable DAG with concrete port edges |
CompiledFlowPlanV1 | compiled-flow-plan.v1 | Plan with custom dependency and schema checksums |
RawStoredEventV1 | sens.ingestion.raw-stored.v1 | Reference to a committed raw row |
FlowReplayRequestedEventV1 | sens.flow.replay.requested.v1 | Reference to one queued, pinned replay |
MeasurementIntentV1 | v1 | Side-effect-free normalized measurement intent |
FlowActionIntentV1 | v1 | Side-effect-free email or attribute intent |
| flow action event | sens.flow.actions.v1 | Reference to a committed Action job |
FlowDeadLetterEventV1 | sens.flow.dead-letter.v1 | Safe IDs and retry classification for persistence |
ScriptLoadRequestV1 | sens.flow.sandbox.execute.v1 | Compile artifact initialization release gate |
ScriptExecutionRequestV1 | sens.flow.sandbox.execute.v1 | Bounded QuickJS execution request/reply |
Internal events carry event ID, schema version, source, occurrence time, tenant, correlation context, and idempotency identity. Payloads, script source, recipients, and rendered email bodies are excluded from logs.
The file-backed control-stream budgets are 1 GiB for Raw Stored, 128 MiB for Actions, and 32 MiB each for Replay and Dead Letters. Together with the 2-GiB Raw Ingestion stream, all declared maxima total 3,422,552,064 bytes and remain below the NATS server’s 3.8-GB file-store ceiling and the chart’s 4-GiB default PVC request.
SENS_RAW_STORED_V1 uses work-queue retention with a 7-day MaxAge, 1-GiB
MaxBytes, and the single logical consumer group flow-worker-v1. A confirmed
Flow acknowledgement removes the reference immediately. Unacknowledged
references remain only until a stream limit is reached. Replay remains on the
separate SENS_FLOW_REPLAYS_V1 stream. A future independent Raw Stored reader
must use a separate stream or explicit fan-out contract instead of competing
for this work queue.
Direct edges require exact schemaRef equality. Structural similarity is not
compatibility; conversion requires an explicit adapter node. Released flow and
script contents are immutable.
Custom outputs may either reuse a visible existing schema reference, which keeps them directly connectable to standard blocks, or publish an inline schema. IDs for inline schemas are allocated by the server and cannot be selected by the caller:
sens://schemas/custom-flow-block/{blockId}/versions/{version}/outputs/{port}/v1sens://schemas/custom-flow-block/{blockId}/versions/{version}/parameters/v1Each compiled custom dependency pins block version ID, artifact checksum, manifest checksum and all schema checksums. Release and runtime both reject a status, scope or checksum mismatch. Required outputs must exist; absent optional outputs remain valid.
Replay and Dead Letter events intentionally contain no Raw payload, script
source, recipient list, rendered mail content or device-attribute value. Replay
requests require an HTTP Idempotency-Key; mutable resources use numeric ETags
through If-Match as documented in the OpenAPI contract.