Concepts
Object Model
The durable records isplay uses to represent projects, runs, traces, branches, replay, experiments, and analysis.
The object model is the contract between capture code, the server, replay, experiments, adapters, and analyst agents. Most records are Zod schemas in @isplay/core and are persisted through the API and Postgres store.
Prop
Type
Ownership Graph
A project owns all evidence for one app, service, customer boundary, or investigation boundary.
A run owns the observed execution trace: events, model calls, tool proposals, tool executions, checkpoints, artifacts, and context inventory.
A branch belongs to a base run and one checkpoint. It does not copy all records; it describes the controlled change to apply during replay.
A replay belongs to a base run and optionally to an experiment arm with a
trialIndex. It records whether the comparison completed, paused, or failed.An experiment owns hypotheses and arms. Arms usually materialize branches, and repeated trial indexes materialize as replays.
An analysis run references the base run and optional replay or experiment evidence, then stores the final evidence-bounded report data.
Why Model Intent And Tool Execution Are Separate
Agents often propose tool calls before a runtime executes them. isplay records both sides because bugs can occur in either place:
| Failure location | Evidence record |
|---|---|
| The model chose the wrong tool or wrong args | ToolProposal and tool.proposed |
| The runtime rewrote args or selected another implementation | Difference between ToolProposal and ToolExecution |
| The tool returned bad data | ToolExecution.resultArtifactId, resultHash, fixture requirements, and replay diffs |
| The tool mutated the outside world | sideEffectClass, replay policy, and fixture provenance |
Practical Advice
- Treat IDs as durable. Store
projectId,runId,checkpointId,branchId,replayId, andexperimentIdfrom JSON output. - Use project boundaries deliberately. Mixing unrelated services in one project makes catalog and context search noisy.
- Keep model and tool artifacts available. Replays and reports are much weaker when only event summaries remain.
- Put important state into checkpoints, not only events. Branching needs a restartable state snapshot.