fabro/docs/internal
Bryan Helmkamp 3e8b2ebfcc
Run the server's lifecycle over platform records instead of run_events
Step 4 of the legacy executor deletion, first commit of several: step 4
spans commits because the legacy event log and its consumers cannot go
in one compiling change. This commit moves every writer off `run_events`;
the reducer, `EventBody`, the Slate bridge and the API's event types
still exist for the readers the next commits port or delete.

Writers:
- The server records a run's lifecycle (submitted, runnable, starting,
  running, blocked, paused, control requests and effects, the terminal
  status), its title, parent link, archive state, notices and pull
  request state as platform records (`fabro_store::platform_records`),
  through the new `server::run_records` module. Every append wakes the
  projector and waits for its pass, so the read that follows a write
  holds the record.
- Pull request creation is recorded as `pull_request.requested`,
  `pull_request.created`, `pull_request.failed`, `pull_request.linked`
  and `pull_request.unlinked`; the projection folds them into the run's
  pull request and creation state.
- Answers to questions are recorded as `interview.answered` with the
  answering principal and the answer text; the interview adapter no
  longer posts legacy `interview.*` events (`QuestionSink` is now an
  optional observer).
- The worker (`fabro run __run-worker`) records its lifecycle, notices
  and pause state over `HttpPlatformRecords`; `HttpRunStore` for the
  legacy event log and the worker's `run_store` are gone.
- `persist_created_run` appends `run.created` and `run.submitted`.

Readers:
- A stream follower (`server::stream_follower`) follows each live run's
  stream (Petri events and platform records), folds lifecycle records
  into the in-memory run state, forwards items to the global attach
  broadcast, and syncs blocked and paused from the projection.
- Slack posts questions from the projection's pending interviews,
  finishes them on `interview.answered` or `question_expired`, and sends
  lifecycle notifications with `notification.sent` dedupe.
- `GET /runs/{id}/events` and the attach endpoints serve only the run
  stream; the per-event, per-stage and `POST /runs/{id}/events`
  endpoints and their tests are deleted.
- `Database::load_run_projection` reads the Petri projection only.

Deleted with the writers:
- The SQLite blob and run-history activation migrations and their
  legacy Slate imports (`legacy_blob_import`, `legacy_run_history_import`,
  the activation backup): a greenfield server has no Slate history to
  import, and the run-history verification refused to start a server
  whose runs have no legacy events.
- `fabro-workflow`'s `operations::archive` and `operations::run_store`.
- The server's legacy-event unit tests and the CLI's `HttpRunStore` tests.

The in-process answer transport is now set after the starting and
running records land, not gated on the live status still being
`Starting` (the records already moved it).

The manifest validation test for a `run.agent.mcps.<name>` catalog
reference now expects `unsupported.workflow_toml.run.agent.mcps.reference`:
Petri's Fabro frontend has no server catalog to resolve it against.

Legacy readers still fail their tests until the next commits: the
reducer and Slate tests in fabro-store, the fabro-workflow create tests
that read the run back through the legacy store, the CLI tests seeded
through `POST /runs/{id}/events`, the CLI's legacy attach and render
paths, the sessions API, the OpenAPI conformance test, and the web
fixtures.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-18 12:32:06 -04:00
..
assets/brand docs: move published docs under docs/public 2026-04-26 21:19:46 -04:00
demo Shared-checkout parallel execution (recovered from run 01KY7YH7RYCJ1BDVTTP96ZA4HV) 2026-07-24 06:19:11 -04:00
licenses docs: move published docs under docs/public 2026-04-26 21:19:46 -04:00
product docs(secrets): document settings-declared credentials, fix stale local-run guidance 2026-07-25 09:04:59 -04:00
cargo-target-apfs-churn-plan.md docs: commit plan 2026-04-28 09:46:52 -07:00
cli-workflow-coupling-audit.md refactor: organize crates into three layers 2026-07-23 17:59:34 -04:00
error-handling-strategy.md docs: clarify chain-rendering boundary in error strategy 2026-05-04 11:28:28 -04:00
event-schema-competitive-analysis.md Run agent stages, Ask Fabro, and fabro exec on pebble's CodingAgent 2026-09-11 14:19:15 -06:00
events-strategy.md State the agent event contract in the docs 2026-09-13 08:36:37 -06:00
events.md Delete fabro's own pricing: lithos-llm prices every response once 2026-09-14 14:46:44 -06:00
fabro-event-schema-v2-concrete-shape.md State the agent event contract in the docs 2026-09-13 08:36:37 -06:00
fabro-event-schema-v2-proposal.md feat(events): make inference in-flight state observable 2026-07-24 21:47:51 -04:00
llm-client-resolution.md Implement the lithos CredentialProvider trait directly 2026-09-10 09:16:39 -06:00
logging-strategy.md Move fabro-mcp's pebble mapping and test client into fabro-cli 2026-09-18 10:57:07 -04:00
mcp-server-qa-test-plan.md Simplify run creation to registered workflow versions 2026-09-12 11:04:15 -06:00
migrations-strategy.md Run the server's lifecycle over platform records instead of run_events 2026-09-18 12:32:06 -04:00
panic-policy.md chore: add panic policy 2026-05-26 22:04:04 -04:00
parallel-strategy.md Retire the fabro Sandbox trait for one concrete RunSandbox 2026-09-10 00:14:42 -06:00
plan-events-as-source-of-truth-follow-ups.md refactor: organize crates into three layers 2026-07-23 17:59:34 -04:00
plan-events-as-source-of-truth.md Make git metadata sandbox-native 2026-04-27 21:43:15 -07:00
react-effects-policy.md docs: add React effects policy (#419) 2026-05-26 19:30:02 -04:00
run-directory-keys.md Remove Git run metadata branches 2026-09-05 12:31:03 -04:00
server-secrets-strategy.md Resolve provider secrets through lithos conventional credentials 2026-09-09 23:00:08 -06:00
slow-test-opportunities-2026-04-07.md refactor: organize crates into three layers 2026-07-23 17:59:34 -04:00
testing-strategy.md refactor: organize crates into three layers 2026-07-23 17:59:34 -04:00
updating-web-screenshots.md refactor(workflow): remove retro stage (#230) 2026-05-09 10:18:20 -04:00