Module robot 

The robot NDJSON contract — defined once, consumed three ways.

Agent users are the primary consumers of ftts (goal G5), so the event stream is a promised interface, not incidental logging. The catalogue below is the only place that definition lives:

1. ftts robot schema serialises it via schema_document, so the machine-readable self-description cannot drift from what the binary actually emits;
2. validate_event checks emitted objects against it, so an event that grew a field or lost one fails a test rather than silently changing an agent’s parse;
3. the frozen fixture in ftts-conformance pins it, so a schema change is a deliberate fixture update and never a silent one.

Validation is strict in both directions: a missing required field and an unknown field are both violations. A contract that only checks for absence lets the surface grow silently, which is the failure mode that breaks downstream parsers.

Bead: frankentts-p0-robot-82c.

Structs

EventSpec

FieldSpec

One field of one event.

RunContext

Run-scoped emitter state: the shared run_id and the run’s own clock.

Enums

EventType

A named event, as a constructor for a partially-filled object.

Kind

Stream events describe a run in progress; replies answer a one-shot query.

Stream

Which stream an object is written to.

Constants

COMMON_FIELDS

Present on every object, so the per-event lists below do not repeat them.

DOCUMENTED_ENVIRONMENT

Environment recognised by the CLI, as reported by robot schema.

EVENTS

SCHEMA_VERSION

Version carried by every emitted object. Bump deliberately; the frozen fixture will fail.

Functions

event_spec

Look up one event’s specification by name.

health_violation_event

The machine-readable self-description emitted by ftts robot schema. Render an engine health signal as its robot event.

schema_document

validate_event

Check one emitted object against the catalogue. An empty result means it conforms.

validate_ndjson

Validate a whole NDJSON stream, reporting the line number of each violation.