kestrel.markets/src/blotter/serialize.ts

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

/**
 * # blotter/serialize — the Blotter's one canonical serialization (ADR-0011)
 *
 * The projector emits **one canonical serialization: deterministic machine-JSON** — ordered keys, no
 * wall clock — exactly as the Bus is canonical JSONL. This is what Certification byte-compares (the
 * determinism leg re-projects and diffs these bytes) and what an archive stores. Human/legible rendering
 * is the viewer's job (a57.13), NEVER the projector's — this file chooses no glyphs, only a stable byte
 * order.
 *
 * Canonicalization sorts every object's keys lexicographically, recursively, so the bytes depend only on
 * the DATA and never on construction/insertion order — the strongest form of "ordered keys". Numbers
 * serialize via the platform's shortest round-trippable form (`JSON.stringify`), which is deterministic;
 * `undefined` keys are dropped (the Blotter never carries `undefined` values — optional fields are simply
 * absent). Output is compact (machine-JSON) with a single trailing newline.
 */

import type { Blotter } from "./types.ts";
import { canonicalizeJson } from "../canonical/json.ts";

/**
 * Serialize a Blotter to its canonical bytes: deterministic machine-JSON (lexicographically ordered
 * keys, compact, one trailing newline). Pure and total — the same Blotter always produces byte-identical
 * text, which is the substrate the determinism certification leg byte-compares. The key order and
 * `undefined`-drop are the one {@link canonicalizeJson canonical byte order} (canonical/json); the single
 * trailing newline is this artifact's canon.
 */
export function serialize(blotter: Blotter): string {
  return canonicalizeJson(blotter) + "\n";
}