# Wait for readiness, always

## Why

Index creation is a queued job across separate subsystems. The create call succeeding means the job was accepted, not that the index exists. Writing or querying immediately can fail on an index that is still provisioning.

## The pattern

```
import time

def wait_until_ready(name, timeout_s=300):
    start = time.time()
    while True:
        desc = pc.describe_index(name)
        if desc.status.ready:
            return desc
        if time.time() - start > timeout_s:
            raise TimeoutError("index %s not ready after %ss" % (name, timeout_s))
        time.sleep(5)
```

## Rules for agents

1. Put this in every script that creates an index: setup scripts, seed scripts, tests, migration scripts. No exceptions.
2. Always include the timeout. An infinite poll turns a stuck provisioning into a hung CI job that burns minutes silently.
3. Log state transitions while polling. "Still provisioning after 4 minutes" is actionable information for support; a silent hang is not.
4. Readiness is per index. A fresh index in a migration needs its own wait even when the old index is long ready.

## Trap

Checking `name in pc.list_indexes()` as a readiness signal. Listing shows the control-plane record, which appears before the data plane is ready. Only `status.ready` means ready.