Documentation

State serialization

RFC 8785epoch-json/1

What state can be checkpointed, how it is encoded, and how schemas migrate.

Allowed values

JSON values only: null, booleans, strings, finite numbers, arrays and plain objects. Functions, symbols, undefined, bigint, Map, Set, Date, class instances, typed arrays and cycles are rejected with SERIALIZATION_FAILED, unless you register a serializer for them.

Envelope

The stateHash commits to the canonical bytes of { applicationVersion, schemaVersion, sdkVersion, serializerVersion, state }.

serializer.ts

import { StateSerializer, bigintSerializer } from "./sdk/src/index.ts";

const serializer = new StateSerializer({
  applicationVersion: "rebalancer/2",
  schemaVersion: 2,
  serializers: [bigintSerializer],          // opt in; bigint is rejected otherwise
  migrations: { 1: (s) => ({ ...s, fills: s.fills ?? [] }) },   // schema 1 -> 2
});

Migrations

migrations[n] turns a schema-n state into schema n+1. A state newer than the application, or one with no migration path, is refused with STATE_SCHEMA_INCOMPATIBLE; it is never loaded as-is.

Canonical JSON

RFC 8785: keys sorted by UTF-16 code units, no whitespace, ECMAScript number format, UTF-8. Strings must be Unicode NFC without lone surrogates. Manifests and encryption bindings use integers only, so the Python SDK produces identical bytes.