Studio telemetry contract

P5.8 freezes the progress-event and archive references that the P10 studio reads. Telemetry reports a run; it is not a second source of truth and does not carry private evaluator state.

The committed example is notes/reference/p5-telemetry.v1.json with archive notes/reference/p5-archive.v1.json.

Event stream

EventStream uses brushline.optimization-telemetry.v1 and carries:

  • the run id and instance id;

  • the vegetation-model and data versions;

  • an optional archive-relative pareto.json path;

  • an ordered event list.

Each TelemetryEvent uses brushline.optimization-event.v1 and carries a stable event id, zero-based sequence, type, timezone-aware time, run and instance ids, adapter, Fresh Solutions version, seed, budget, payload, and optional objective vector, feasibility, plan id, and evidence path.

Event types are:

Type

Meaning

start

Search mode, seed, budget, and adapter are available.

iteration

Optional progress record.

incumbent

Assignment, objective vector, feasibility, evaluations, and history.

archive

Archive path and the member records the studio may display.

checkpoint

Checkpoint path.

finish

Stop reason and evaluation count.

Validation checks consecutive sequences from zero, unique event ids, the start/finish boundaries, one run and instance id, and no event after finish. Named errors are TELEMETRY-SEQUENCE, TELEMETRY-ORDER, TELEMETRY-RUN, TELEMETRY-INSTANCE, and TELEMETRY-ARCHIVE.

Building a stream

from brushline.optimization.telemetry import (
    check_studio_compatibility,
    events_from_run,
    with_archive_event,
)

stream = events_from_run(
    run,
    run_id="tiny-run-1",
    model_version="brushline.low-vegetation.prototype.v0",
    data_version="synthetic-corridor.v1",
    archive_path="runs/tiny/pareto.json",
)
stream = with_archive_event(stream, archive, archive_path="runs/tiny/pareto.json")
assert check_studio_compatibility(stream, archive).ok

events_from_run creates start, incumbent, optional checkpoint, and finish events. It does not fabricate an archive event. with_archive_event inserts one archive event before finish and verifies the archive first.

Server-sent events

to_sse renders the validated stream with id, event, and JSON data fields. write_event_stream writes JSON; write_sse writes the event stream. Both writers validate first.

Studio compatibility

check_studio_compatibility reads only the stream and archive:

  • a missing archive is an explicit error;

  • exactly one archive event is required;

  • the stream and expected archive paths must match;

  • event and archive plan ids must match;

  • evidence paths and objective vectors must match.

It returns StudioCompatibility with ok, errors, warnings, archive path, member count, and event count. It does not inspect the evaluator, search internals, or unlisted files.

Schemas

  • brushline.optimization-event.v1: one progress event.

  • brushline.optimization-telemetry.v1: versioned event stream.

Limits

  • Telemetry is a report; the archive and plan artifacts remain authoritative.

  • The stream carries assignment and objective records but not a full evaluator state.

  • SSE is a rendering; a live event bus is a later deployment concern.

  • A missing archive is never inferred or silently recreated.