Skip to main content

Module serialize

Module serialize 

Source
Expand description

The ONE canonical serialization of a decision request (pinned per S6b1).

This module is a frozen contract: meaning-preserving format changes swing model accuracy by up to 76 pp (Sclar et al., ICLR 2024), so the byte-level layout below does not change without a new schema version. The question encoder (P1.1) trains on exactly this form and the serving path emits exactly this form.

§Layout

<|state|>\n{state}\n
<|question|>\n{instructions}\n            (instructions line omitted when absent)
    noul:   <|rubric|>\ntrue\n{true criteria}\n     (each rubric block only if present)
            <|rubric|>\nfalse\n{false criteria}\n
            <|anchor|>\n
    choice: <|option|>\n{name}\n{rubric}\n<|anchor|>\n   (rubric line omitted when null)
            ... one block per option, in canonical (authoring) order
    score:  <|level|>\n{rubric}\n<|anchor|>\n            (one per level; the level's
            ...                                                    NUMBER is never emitted)
  • The anchor placeholder comes immediately AFTER each option’s rubric text (<|anchor|> stands in for the learned special token whose id the tokenizer assigns in P1.1/P1.2). Never a trailing anchor section: the shared scorer reads the hidden state at each anchor position, and option-adjacent placement keeps every option’s local readout structurally identical through the backbone’s causal linear-attention layers (S6b1).
  • Noul has exactly ONE anchor, not one per outcome: the noul statement has no per-option rubric blocks, so its single anchor follows the (optional) true/false criteria blocks and is the position where the sigmoid readout (P1.1) is taken — the same adjacent-after principle, applied to the statement’s rubric blocks.
  • Score levels carry no index and no neighbour context — each level is judged independently against the state (upstream behavioral contract, S6a §2.2).
  • Question ids are caller-facing only and never appear in the serialization.
  • Non-string entries (objects/arrays) serialize as compact canonical JSON (crate::entry::Entry::canonical_text).

§Token budget (acceptance criterion)

A serialized request must fit MAX_SERIALIZED_SPEC_TOKENS at the 2k-token serving context. When a choice question cannot fit its options within the budget — the canonical case being cardinality above the 255-option profile limit — the two-stage recipe (score candidates in parallel, then choose among the top scorers) is mandatory, not optional (S6a §2.4: both stages are client-side patterns, not wire features). Token counting is tokenizer-bound and lands with the P1.1 encoder; this module exposes serialized_bytes as the pre-tokenizer proxy.

Constants§

ANCHOR_PLACEHOLDER
Placeholder for the learned special anchor token. The concrete token (and its id) is assigned when the tokenizer is extended in P1.1/P1.2; the serialization contract fixes only the position: immediately after each option’s rubric text.
MAX_SERIALIZED_SPEC_TOKENS
The serialized-spec token budget at the 2k-token serving context. Exceeding it makes the two-stage >255 recipe mandatory. Enforced with the real tokenizer in P1.1; this constant is the contract.

Functions§

serialize_question
Serialize one question to its canonical block (without the state header).
serialize_request
Serialize a full request: the state header followed by every question block in canonical (authoring) order.
serialized_bytes
Byte length of the canonical serialization — the pre-tokenizer proxy for the MAX_SERIALIZED_SPEC_TOKENS budget (token counting is tokenizer-bound, P1.1).