Protocol reference

Documentation Index

Fetch the complete documentation index at: https://docs.fluxamerica.io/llms.txt

Use this file to discover all available pages before exploring further.

​

1. Overview

• An op — a single typed request/response. The client opens a new bidirectional op stream, writes the envelope and the request body, reads the response, closes the stream.
• A subscription — a long-lived op that receives server-pushed events on a dedicated subscription stream (a unidirectional server-to-client stream parented by an op stream) until the client cancels.
• Bulk data movement — Avro Object Container Files transferred on one or more data streams (unidirectional, parented by an op stream).
• Datagrams — fire-and-forget client telemetry; not used for product traffic.

​

2. Session lifecycle

​

2.1 QUIC and WebTransport handshake

​

2.2 Control stream

​

2.3 Auth handshake

struct ClientHello {
    supported_protocol_versions: Vec<u32>,   // descending preference
    client_capabilities: CapabilitySet,
    auth: AuthToken,                          // WorkOS-signed JWT
    client_metadata: ClientMetadata,          // product, version, OS
}

struct CapabilitySet(pub BitFlags<Capability>);

enum Capability {
    // v1.0 starter set
    SubscriptionResume,
    BulkRecordImport,
    BulkRecordExport,
    AuditTailSubscription,
    // ...
}

struct ClientMetadata {
    client_name: String,                      // "platform-cli", "web-leptos"
    client_version: String,                   // semver
    user_agent: Option<String>,               // web only
    locale: Option<String>,
}

struct ServerHello {
    selected_protocol_version: u32,
    server_capabilities: CapabilitySet,       // intersection of client ∩ server
    session_id: SessionId,                    // for log correlation; opaque to client
    server_metadata: ServerMetadata,
    auth_expires_at: Timestamp,               // when the bound token expires
}

​

2.4 Heartbeat

​

2.5 Server-pushed events

​

2.6 Graceful shutdown

​

2.7 Token expiry

​

3. Wire format and framing

​

3.1 Framing on a stream

+--------+------------------+
| varint |    payload       |
+--------+------------------+
  N bytes    N-decoded bytes

• Control stream, position 0 (client→server): ClientHello.
• Control stream, position 0 (server→client): ServerHello.
• Control stream, position ≥1: ClientControlFrame or ServerControlFrame (enum dispatched per direction).
• Op stream, position 0 (client→server): OpEnvelope.
• Op stream, position 1 (client→server): Op (enum).
• Op stream, position 0 (server→client): Result<OpResponse, OpError>.
• Op stream, position ≥1 (server→client): typed continuation frames for ops that produce multiple frames (rare; see § 6 for subscriptions, which use dedicated subscription streams instead).
• Data stream: a single Avro Object Container File (not Postcard).

​

3.2 The op envelope

struct OpEnvelope {
    protocol_version: u32,                    // must equal ServerHello.selected_protocol_version
    capabilities_used: CapabilitySet,         // must be ⊆ ServerHello.server_capabilities
    trace_context: Option<TraceContext>,      // W3C Trace Context (traceparent + tracestate)
    idempotency_key: Option<IdempotencyKey>,  // 128-bit; required for mutating ops
    deadline: Option<DurationMillis>,         // client-imposed soft deadline
}

• protocol_version mismatch closes the stream with OpError::PreconditionFailed(VersionMismatch). The client should treat this as a session-level error and reconnect.
• capabilities_used not a subset of the negotiated set: OpError::PreconditionFailed(CapabilityNotNegotiated { missing }).
• trace_context follows W3C Trace Context: traceparent + optional tracestate. Generated by the client; the server propagates it to internal spans and to audit events as correlation_id (per ADR-0007).
• idempotency_key is a 128-bit value supplied by the client. The server stores (idempotency_key, principal, op_kind) → response for 24 hours. Re-submitting an op with the same key returns the cached response without re-executing. Required on every mutating op; optional on reads. Storage of the cache and its eviction policy live in docs/OPERATIONS.md once Phase 3 lands.
• deadline is advisory: the server may abort the op when the deadline passes (OpError::PreconditionFailed(DeadlineExceeded)); it is not a guarantee.

​

3.3 Stream cancellation

​

3.4 Maximum frame size

​

4. Op model

​

4.1 The Op enum

enum Op {
    // Models and fields
    CreateModel(CreateModel),
    GetModel(GetModel),
    ListModels(ListModels),
    UpdateModel(UpdateModel),
    TombstoneModel(TombstoneModel),
    PublishModelVersion(PublishModelVersion),
    ListModelVersions(ListModelVersions),
    GetModelVersion(GetModelVersion),
    AddField(AddField),
    UpdateField(UpdateField),
    TombstoneField(TombstoneField),

    // Records
    CreateRecord(CreateRecord),
    GetRecord(GetRecord),
    UpdateRecord(UpdateRecord),
    DeleteRecord(DeleteRecord),
    ListRecords(ListRecords),

    // Bulk
    QueryRecords(QueryRecords),               // server returns data stream
    ImportRecords(ImportRecords),             // client sends data stream
    ExportModel(ExportModel),                 // server returns multi-stream bundle

    // Subscriptions
    SubscribeRecords(SubscribeRecords),
    SubscribeModels(SubscribeModels),
    SubscribeAuditTail(SubscribeAuditTail),

    // Attachments
    InitiateAttachmentUpload(InitiateAttachmentUpload),
    CompleteAttachmentUpload(CompleteAttachmentUpload),
    RequestAttachmentDownload(RequestAttachmentDownload),

    // Audit
    GetAuditEvent(GetAuditEvent),
    ListAuditEvents(ListAuditEvents),

    // Introspection
    DescribeProtocol(DescribeProtocol),       // returns server schema digest
    DescribeAvroSchema(DescribeAvroSchema),   // returns Avro schema for a given target
}

​

4.2 The OpResponse enum

enum OpResponse {
    Empty,                                    // for ops with no return body
    Model(Model),
    ModelList { items: Vec<Model>, next_cursor: Option<Cursor> },
    Record(Record),
    RecordList { items: Vec<Record>, next_cursor: Option<Cursor> },
    DataStreamRef {
        stream_id: DataStreamId,
        schema_fingerprint: SchemaFingerprint,
        expected_record_count: Option<u64>,
    },
    DataStreamAccepted { stream_id: DataStreamId },
    SubscriptionAccepted {
        subscription_id: SubscriptionId,
        resume_token: ResumeToken,
        event_stream_id: StreamId,
    },
    AttachmentUploadInitiated(AttachmentUploadInitiation),
    AttachmentDownloadGranted(AttachmentDownloadGrant),
    AuditEvent(AuditEvent),
    AuditEventList { items: Vec<AuditEvent>, next_cursor: Option<Cursor> },
    ProtocolDescription(ProtocolDescription),
    AvroSchema(AvroSchemaDocument),
}

​

4.3 Cursor pagination

​

4.4 Idempotency

​

5. V1 op catalogue

​

5.1 Model and field ops

​

5.2 Record ops

​

5.3 Bulk ops

​

5.4 Subscription ops

​

5.5 Attachment ops

​

5.6 Audit ops

​

5.7 Introspection

​

6. Subscriptions and live updates

1. Client sends a Subscribe* op on an op stream.
2. Server returns SubscriptionAccepted { subscription_id, resume_token, event_stream_id } and opens a unidirectional server→client stream identified by event_stream_id.
3. The op stream remains open. The server may push subscription-control messages (lease renewal, server-side cancellation) on the op stream.
4. Events flow on the event stream as length-prefixed Postcard SubscriptionFrame values.
5. The client cancels by closing the op stream’s write side. The server observes, closes the event stream, and the subscription is gone.

​

6.1 SubscriptionFrame

enum SubscriptionFrame {
    Accepted { subscription_id: SubscriptionId, resume_token: ResumeToken },
    Event {
        sequence: u64,                        // monotonically increasing per subscription
        correlation_id: CorrelationId,        // matches the originating audit event
        occurred_at: Timestamp,
        body: SubscriptionEvent,
    },
    EventChunk {
        sequence: u64,
        chunk_index: u32,
        chunk_count: u32,
        partial_body: Bytes,                  // raw Postcard chunk of SubscriptionEvent
    },
    Heartbeat { server_now: Timestamp },      // every 30s in idle subscriptions
    LeaseRenewed { expires_at: Timestamp },
    EndOfStream { reason: EndOfStreamReason },
}

​

6.2 Resume semantics

1. Validates the token (HMAC-signed per tenant; tamper detection identical to cursors).
2. Locates the position in the audit log.
3. Replays events from position + 1 until caught up, then transitions to live tailing.

​

6.3 Deduplication

​

6.4 Filtering

​

6.5 Subscription leases

​

6.6 Backpressure

​

6.7 Server-pushed lifecycle

​

7. Bulk data: Avro

​

7.1 Object Container Files

[magic 'Obj\x01']
[header: { meta: { 'avro.schema': <writer schema JSON>,
                   'avro.codec': <codec>,
                   'platform.model_slug': <slug>,
                   'platform.model_version': <u32>,
                   'platform.tenant_id': <tenant id>,
                   'platform.trace_id': <trace id> },
           sync_marker: <16 bytes> }]
[block]*

• The writer schema is the canonical Avro representation of the target model version (records) or the relevant audit-event variant (audit exports).
• The codec is null (uncompressed) in v1. Zstd codec is a capability-gated future addition.
• Platform-specific metadata is embedded under the platform.* prefix. Avro readers ignore unknown metadata; platform readers use it for verification.

​

7.2 Avro schema derivation

• single → the inner type.
• list → array<inner> with platform.cardinality: list, platform.ordered: true|false in field metadata.
• set → array<inner> with platform.cardinality: set (Avro lacks a native set; uniqueness is a platform invariant).

​

7.3 Schema evolution

• Every Record carries the model_version it was written under (platform.model_version metadata in the Avro file).
• The server publishes Avro schemas for every model version via DescribeAvroSchema. Clients cache these by (model_slug, model_version) pair.
• When a client deserializes a record at a version newer than its cached schema, it fetches the new schema before proceeding. Avro reader/writer schema resolution handles the deserialization.

​

7.4 Codec policy

​

7.5 Conversion coverage and deferred primitives

​

Decimal { precision, scale }

• Domain shape. serde_json::Value::String containing the decimal literal (e.g. "123.45"). JSON numbers lose precision past f64 so the string form is canonical; the integer-and-scale form is also acceptable on input. Per ADR-0014.
• Avro target. Value::Decimal(apache_avro::Decimal::from(bytes)) where bytes is the big-endian two’s-complement representation of the unscaled integer, with redundant sign-extension bytes trimmed (Avro spec § “Decimal logical type”).
• Implementation requirements.
  1. Parse the JSON string via rust_decimal::Decimal::from_str (the crate is already a pinned dep for Fx; reuse).
  2. Validate that the parsed scale matches the field schema’s declared scale; mismatch → Validation error.
  3. Validate that the unscaled magnitude fits in precision digits; overflow → Validation error.
  4. Convert the i128 mantissa to a Vec<u8> of big-endian bytes, stripping leading 0x00 (for positives) or 0xFF (for negatives) bytes that don’t change the value but bloat the payload. Avro’s canonical encoding requires the minimal-bytes form.
  5. Reverse direction: reconstruct i128 from the byte slice (sign-extend if shorter than 16 bytes), format with the schema’s scale, return as JSON string.
• Target phase. C.2.3 or C.2.5 — whichever bulk op first carries a decimal-typed field through. Self-contained; can also land opportunistically as a small commit.

​

Duration

• Domain shape. Glossary: “ISO 8601 duration; stored as nanoseconds.” So the canonical domain value is an i64 nanosecond count, surfaced as serde_json::Value::Number(i64) or as the ISO string form for human readability.
• Avro target. Value::Duration(apache_avro::Duration::new(months, days, millis)) where each component is a u32 little-endian. Total wire size 12 bytes.
• Implementation requirements.
  1. Decide canonical input form: number-of-nanoseconds (precise) vs ISO 8601 string (round-trip-able with calendar units). Avro’s duration cannot represent both nanoseconds AND months — the month component is calendar-aware and ambiguous in milliseconds. The platform’s domain stores nanoseconds, so the conversion is lossy on the calendar dimension: we set months = 0, days = 0, compute millis = nanoseconds / 1_000_000, and truncate sub-ms precision. Document the loss in the wire spec.
  2. Reverse direction: months × ~30.44 days + days + millis as nanoseconds. Months > 0 from a non-platform writer would produce a precision-incompatible value; flag as a Validation error on decode if encountered (platform never writes months > 0).
• Target phase. C.2.3 or later. Lower priority than decimal — duration fields are rare in practice.

​

Geopoint

• Domain shape. serde_json::Value::Object with lat: f64 and lon: f64.
• Avro target. Value::Record([("lat", Double(lat)), ("lon", Double(lon))]). Schema-side already renders correctly (§ 7.2).
• Implementation requirements.
  1. Extract lat and lon as as_f64(); missing or non-numeric → TypeMismatch.
  2. Reverse direction: pairs into JSON object.
• Target phase. C.2.3. Trivial; the only reason it’s deferred is that the C.2.2 substrate didn’t need it. Add when first geopoint field appears in an e2e test.

​

Geoshape

• Domain shape. serde_json::Value::String containing WKT (Well-Known Text).
• Avro target. Value::String(wkt). Schema-side renders as bare string.
• Implementation requirements. One match arm. The only reason it was deferred in C.2.2 is that this list of “complex types not shipped” originally included geoshape by mistake — it’s actually trivial. Lift in C.2.3 as a one-line addition.
• Target phase. C.2.3.

​

Address

• Domain shape. serde_json::Value::Object with optional fields per the address sub-shape (line1, line2, locality, region, postcode, country).
• Avro target. Value::Record([(name, Value::Union(0|1, …))*]) where each field is ["null", "string"]. Schema-side already renders this (§ 7.2).
• Implementation requirements.
  1. For each known sub-field, look up in JSON object; convert present strings to Union(1, String(s)) and missing or null to Union(0, Null).
  2. Unknown sub-fields in the JSON should be ignored or surface as a Validation warning (open question; default: ignore).
  3. Reverse direction: walk the Avro Record pairs and rebuild the JSON object, omitting fields that decoded as null (matches the glossary’s “optional address sub-fields” semantics).
• Target phase. C.2.3 or C.2.5. Address fields are real workloads but not on the critical path for the first end-to-end QueryRecords.

​

Attachment

• Domain shape. serde_json::Value::Object with the full AttachmentHandle per the glossary entry: object_key, sha256, byte_size, mime_type, original_filename, scan_state, scan_at, scanner_version, uploaded_by, uploaded_at.
• Avro target. A 10-field Value::Record(...). Schema-side already renders the type.
• Implementation requirements.
  1. Type-mapping table: strings for textual fields, Long for byte_size, TimestampMicros for uploaded_at, and a nullable union for scan_at + scanner_version. The scan_state enum could remain a string (the platform’s enum is pending | clean | infected | expired, all valid Avro symbols) or upgrade to an Avro enum in a follow-up.
  2. Reverse direction: pairs → JSON object; map missing optionals to absent JSON keys (consistent with the existing HTTP wire form produced by crate::attachments).
• Target phase. C.2.5 (ImportRecords) or Phase E (attachment ops), whichever first ships records carrying an attachment field through bulk transport.

​

Lookup { via_field_slug, project_field_slug }

• Domain shape. Computed at read time from a referenced record. The stored record has no value of its own for a lookup field; the API materialises it during projection. So on the wire, the lookup field’s value is whatever the projected source field’s value is.
• Avro target. “As the projected primitive” (design doc § 7.2). Requires knowing the target model’s field type for project_field_slug, which lives in a different ModelVersion.
• Implementation requirements.
  1. Schema-side: schema_for_model_version currently emits string for lookup with a // TODO comment. The proper form requires: a. Looking up the referenced model (via the via_field_slug’s Reference { model_slug }). b. Fetching its current published version. c. Finding project_field_slug in that version’s field_specs. d. Emitting the projected field’s primitive schema in place of the lookup.
  2. This requires the derivation function to take a &dyn ModelStore (or equivalent) so it can resolve the reference. That’s a signature change to schema_for_model_version — the caller becomes async, and the function becomes recursive (lookups pointing at lookups would loop; guard with a depth limit).
  3. Cycle detection: (model_slug, version) → field_slug visits; loop → Validation error at publish time, not at read time.
  4. Value-side conversion uses whatever the projected primitive resolves to at materialisation time (which the existing crate::records code already handles for HTTP).
• Target phase. Future ADR. Lookups are a v1.x concern; the v1.0 protocol can ship without them by emitting string for the schema and an UnsupportedPrimitive error for the value. The recursive derivation deserves its own ADR (signature change, async derivation, cycle detection policy).

​

Summary table

​

8. Versioning and evolution

​

8.1 Major version

• Are ADR-gated. A new ADR justifies the bump, supersedes ADR-0023, and documents what changed.
• Are reserved for wire-framing changes, breaking semantic redefinitions, or removals that the capability system cannot express.
• Are rare. The platform commits to at most one major bump every 18 months, except in response to a security or correctness issue.

​

8.2 Deprecation window

• A minimum 6-month notice before removal, signaled via ServerNotice { version_deprecation: { version, sunset_at } } on the control stream of every session that handshakes onto the deprecated version.
• A Warning header equivalent in ServerHello.server_metadata.warnings for the deprecated version.
• Public communication via the same channel as ADR publication (release notes; downstream client repos).

​

8.3 Capabilities

• Is NOT ADR-gated. It is a code change with a glossary update if the capability introduces a new concept.
• Is recorded in src/protocol/capabilities.rs with a doc comment explaining its semantics, the op or behavior it gates, and the date it was added.
• Triggers a contract test snapshot update (new capability in the digest).

• Requires a deprecation window of 3 months during which the capability is advertised but server-side enforcement is “ignored, with warning.”
• After removal, clients still requesting it get a ServerNotice { capability_removed: { name } } and the capability is intersected out of the negotiated set.

​

8.4 Field-level evolution within Postcard variants

• DO NOT add fields to existing variants. Instead, add a new variant (e.g., ForceDeleteRecord) gated by a capability.
• DO NOT rename fields. Postcard’s wire format depends on struct layout, not field names, but the discipline holds for clarity.
• DO add new variants to existing enums freely; capability-gate them.

​

8.5 The capability inventory (v1.0)

​

9. Error model

enum OpError {
    Auth(AuthError),
    Validation { errors: Vec<FieldError>, trace_id: TraceId },
    NotFound { kind: ResourceKind, slug: SlugRef },
    RateLimited { retry_after_ms: u32, scope: RateScope },
    PreconditionFailed(PreconditionDetail),
    Conflict(ConflictKind),
    Internal { trace_id: TraceId, kind: InternalErrorKind },
}

​

9.1 Variant semantics

enum AuthError {
    TokenInvalid,
    TokenExpired,
    PrincipalLacksPermission { required: PermissionName },
    HandshakeTimeout,
    ProtocolVersionUnsupported,
}

struct FieldError {
    field_slug: SlugRef,
    rule_name: Option<String>,                // None if structural (cardinality, primitive)
    message: String,
}

enum PreconditionDetail {
    DeadlineExceeded,
    VersionMismatch { client_sent: u32, server_active: u32 },
    CapabilityNotNegotiated { missing: CapabilityName },
    InvalidCursor,
    InvalidResumeToken,
    ResumeGapExceeded,
    PayloadTooLarge,
    SessionDraining,
    AttachmentNotClean,                       // ADR-0015
    SchemaIncompatible { details: String },
}

enum ConflictKind {
    IdempotencyKeyMismatch,
    SlugAlreadyExists { slug: SlugRef },
    ModelVersionInUse,
    DuplicateControlStream,
}

​

9.2 Audit correlation

• Validation and Internal carry trace_id, which is the correlation_id of an audit event emitted at the time of the failure.
• NotFound, Conflict, PreconditionFailed, RateLimited carry the resource slug or scope, plus an implicit trace_id available in the spans for the op (the operations runbook documents how to find it).
• Auth errors emit an auth.* audit event before the error is written; the trace is correlatable via the op envelope’s trace_context.

​

9.3 Client retry guidance

• Retry-able errors: RateLimited (with the supplied delay), Internal { kind: Storage } (exponential backoff, capped at 30 s, max 3 attempts).
• Not retry-able: Auth, Validation, NotFound, PreconditionFailed, Conflict, Internal { kind: WireFormat }.

​

10. Observability

​

10.1 Spans

• protocol.op.kind — the Op variant name.
• protocol.session.id — opaque session id.
• protocol.principal.id — principal slug.
• protocol.tenant.id — tenant slug.
• protocol.idempotency.key — present when the envelope supplies one.
• protocol.cursor.present — boolean.
• protocol.error.variant — set when the op fails; the OpError variant name.
• protocol.bytes_in / protocol.bytes_out — frame sizes.

​

10.2 Metrics

​

10.3 Client telemetry datagrams

struct ClientTelemetryDatagram {
    session_id: SessionId,
    trace_context: Option<TraceContext>,
    kind: ClientTelemetryKind,
    payload: Bytes,                           // bounded at 1 KiB
}

enum ClientTelemetryKind {
    UiPerfMark,                               // payload: Postcard(UiPerfMark)
    UiError,                                  // payload: Postcard(UiError)
}

​

10.4 Logging policy

​

11. Rate limiting

​

11.1 Per-session

• Max concurrent op streams: 32 (configurable per principal class).
• Max concurrent data streams: 4 (configurable).
• Bandwidth: governed by QUIC stream flow control naturally; no application-layer cap in v1.

​

11.2 Per-principal

• Ops/sec: 100 (configurable).
• Bulk-data bytes/sec: 10 MiB/s (configurable).

​

11.3 Per-tenant

• Aggregate ops/sec: 1 000 (configurable per tenant tier).
• Monthly op quota: per-tenant, enforced via the projection store; resets monthly.

​

11.4 The retry-hint contract

• retry_after_ms: the smallest valid retry delay. Clients SHOULD wait at least this long; the server MAY further reject retries that arrive earlier.
• scope: identifies which layer triggered the rejection. Clients use this to surface meaningful errors to users (e.g., “your tenant has reached its monthly quota”).

​

12. Security

​

12.1 Transport security

• QUIC’s TLS 1.3 is mandatory. The server presents a certificate from the tenant’s CA bundle (browser PKI by default; pinned roots for native clients).
• Forward secrecy is on by default in QUIC; no configuration knob.
• 0-RTT is disabled in v1 — the security/replay-protection tradeoff is not worth the latency savings for our op shape.

​

12.2 Authentication

• WorkOS-issued JWTs, signed by the tenant’s WorkOS organization’s signing key.
• The platform validates against the WorkOS JWKS endpoint (per ADR-0009’s .well-known bootstrap pattern).
• JWKS keys are cached per existing auth module policy; rotation is handled out-of-band.
• The JWT carries: sub (principal id), org_id (WorkOS org id, mapped to tenant), exp (expiry), iat, aud (the platform’s audience identifier), plus claims for permissions.

​

12.3 Authorization

​

12.4 Tenant isolation

​

12.5 Replay protection

​

12.6 Threat model summary

​

13. Audit-log integration

​

13.1 Op-to-event mapping

​

13.2 Protocol-layer audit events

​

13.3 Subscription-as-projection

​

15. Client library shape

• One async type per op variant, returning Future<Output = Result<OpResponse, OpError>>.
• A subscription type with recv() -> Future<Output = Option<Result<SubscriptionEvent, OpError>>> and cancel().
• A session type owning the WebTransport session and the control stream; ops and subscriptions are created on the session.
• Capability checks at session-construction time; clients can ask “is FxPredicateFilter available?” without trying an op.