fabro/docs/internal/events-strategy.md

Fabro Run Stream Strategy

A run's history is two logs, and its public event API is one ordered stream over both:

• Petri's records. The engine writes every fact about execution: the run starting and finishing, each step's firing, progress, output and outcome, a question asked and answered, a scope acquired. Fabro stores them unchanged in petri_records through fabro-petri's SqliteRunStore, and reads them through Petri's event contract (RunEvent, with its derived view).
• Platform records. Facts Fabro knows and Petri does not: the lifecycle before and after the engine (run.created, run.lifecycle, run.title, run.parent, run.archived, run.superseded, run.notice), who answered a question (interview.answered), the branch and git identity a run works under, a checkpoint commit with its diff, a collected artifact (artifact.collected), the run's diff (run.diff), the pull request requests and outcomes, a notification sent, a pairing. They are PlatformRecord values in fabro-store::platform_records, stored in platform_records with a per-run seq.

The projector (fabro-petri::projection) folds both logs into the run's RunProjection, the view GET /runs/{id}/state serves, and assigns each record it consumes a stream_seq in petri_stream. That stream is what GET /runs/{id}/events and the attach stream serve, item by item, as RunStreamItem: {run_id, stream_seq, kind: petri|platform, id, recorded_at, item}. stream_seq is the cursor a client resumes from; id is the item's own identity (<log>/<seq>/<index> for a Petri event, the record's seq for a platform record) for deduplication.

Tracing logs are separate. Tracing is developer diagnostics; the stream is the product-facing record other systems consume. If something must be visible after a reattach, it has to be a record, not a log line.

Recording a fact

Petri's own facts need nothing from Fabro: the engine records them and the projector's fold reads them. Add Fabro code only for a fact Petri cannot know.

To record such a fact:

1. Add a variant to PlatformRecord and its kind to PlatformRecordKind in lib/components/fabro-store/src/platform_records.rs. The kind is the kind tag on the wire, lowercase dot notation (pull_request.created). A record that belongs to a stage names its execution and firing.
2. Append it through the server's run_records module (or the worker's client), which commits the record and wakes the projector. Never write platform_records from anywhere else.
3. Fold it in fabro-petri::projection when the projection should show it. A record nobody reads from the projection still reaches the stream.
4. Update the readers that match on record kinds: the CLI's pretty stream rendering (petri_stream.rs), the web app's stream handling, the Slack service, and the tests or fixtures that name kinds.

Do not add a platform record that restates a Petri record. The projection already carries what the engine knows; read it there.

Reading the stream

Servers and workers hold the stream through the projector: stream_after for a page, subscribe for live items, stream_head for the cursor to start from. The server's stream_follower reads every run's stream once and fans it out to the in-memory run map and the global broadcast that /attach and the Slack service take their items from.

Clients read GET /runs/{id}/events?after=<stream_seq> for a page and the attach stream for live items; fabro-client exposes list_run_stream, list_run_stream_until and attach_run_stream.

When matching items:

• A Petri event's name is item.record.body.event (run.started, step.started, step.progress.recorded, step.finished, run.finished); its parsed meaning is under item.derived (a pending question is derived.parsed.kind == "question").
• A platform record's kind is item.record.kind.
• The run has ended when a platform run.lifecycle record's transition is succeeded, failed or dead. Petri's run.finished precedes it and carries the engine's own status.

Never rebuild an item downstream: pass the RunStreamItem through as read.

Agent events

Pebble's CodingAgentEvent stream is the agent event contract. Petri stores each event a coding agent publishes for a step as that step's progress, and the projector folds them into StageProjection.agent with pebble's SessionProjection. Read StageProjection.agent, or the stored progress record itself, instead of folding the stream again. Fabro adds nothing of its own to this stream.

Ask Fabro sessions

Ask Fabro sessions are not runs. Their events (run.session.*) live in their own log, run_session_events, through RunSessionEventStore, numbered per session and served by the sessions API. They never enter a run's stream.

Persistence guarantees

A record is committed before it is visible: the projector reads only what the store has committed, and the stream's stream_seq is assigned in the same transaction as the projection that consumed the record. A client that resumes from its last stream_seq sees every item exactly once.

A worker cannot continue past a record it failed to append: the store's error reaches the engine and fails the run.