> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repost.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Consistency model

> The live observe stream versus the indexed store, the blind spot between them, and why stale reads cause conflicts.

Repost exposes two data planes with different consistency guarantees. An agent that knows which plane answers which question avoids both wasted round-trips and false negatives — concluding an event "didn't arrive" when it simply wasn't indexed yet.

## Live stream versus indexed store

`expect` and `tail` read a **real-time observe stream**. `events search`, `forwards search`, and `events get` read an **indexed store** that trails arrival by a short interval.

|             | Observe stream (`expect`, `tail`)               | Indexed store (`events` / `forwards search`) |
| ----------- | ----------------------------------------------- | -------------------------------------------- |
| Latency     | Real-time                                       | Trails arrival by an indexing delay          |
| Time range  | **Only events after you connect** — no backfill | The full searchable history                  |
| Best for    | Confirming something happens *now*              | Investigating what *already* happened        |
| Consistency | Push, at-most-once while connected              | Eventually consistent                        |

<Warning>
  There is a blind spot between the planes: an event that just arrived is too recent to appear in `search`, and a stream you open *after* it arrived will never replay it. To observe the result of an action, **open `expect`/`tail` before you trigger the action**, not after.
</Warning>

### Pick the plane by question

```mermaid theme={null}
flowchart TD
    Q{What are you asking?}
    Q -->|Will this happen / did it just happen?| L[expect / tail<br/>open before triggering]
    Q -->|What happened earlier?| S[events / forwards search<br/>bounded query]
    Q -->|Exact detail of one known ID?| G[events get / forwards chain]
```

## Stale reads cause conflicts

The indexed store is eventually consistent, so a value you read can move before you act on it. When you cache a resource's state and then mutate it, a concurrent change makes the write fail with `conflict` (exit `1`) — your view was stale, not your command wrong. Re-read, recompute, and retry idempotently: [Safe mutations → Recover from conflict](/agents/safe-mutations#recover-from-conflict).

**Consistency rules**

* Confirm *now* → `expect`/`tail`, opened **before** triggering the action (the stream has no backfill).
* Investigate *past* → `events`/`forwards search` (indexed; trails arrival — absence of a just-sent event is not proof it failed).
* Exact record → `events get` / `forwards chain` by ID.
* `conflict` (exit 1) means a stale read → re-read state, recompute, retry with `--idempotency-key`.

## Continue

<Columns cols={3} className="gap-y-4">
  <Card title="Search & filters" icon="filter" href="/agents/search-and-filters" cta="Query the store" arrow="true">
    Field grammar and cursor pagination for the indexed store.
  </Card>

  <Card title="Wait for events" icon="timer" href="/agents/wait-for-events" cta="Use the stream" arrow="true">
    `expect` and `tail` against the live observe stream.
  </Card>

  <Card title="Caching & performance" icon="gauge" href="/agents/caching-performance" cta="Stay fast" arrow="true">
    What to cache, and how to back off when you must poll.
  </Card>
</Columns>