---
title: Registration lifecycle
---

Clients register their projections on every connect — the full set of definitions the client's code
declares. Chronicle compares each incoming definition against the registered one and only acts on
what changed, so a re-registration from an unchanged client is near-free.

## When a definition changes

A changed definition — including one that *removes* a child collection — is stored, pushed to the
engine on every silo, and the projection's observer keeps running against the new definition. The
change also raises a **replay recommendation** ("Projection definition has changed"), because read
models already written with the old definition may no longer match; performing the recommendation
rebuilds them. With `ReplayOnDefinitionChange` enabled, the replay happens automatically instead.

## When a registration partially fails

Definitions are isolated from each other: a definition the engine rejects fails *alone*. Every other
definition in the registration still lands — in the engine, in its projection grain, and in the
registered state — and the failure is reported back to the client naming exactly the projections that
did not register. A failed definition is not marked registered, so the next registration retries it.

## When a projection is no longer registered — retirement

A projection the client stops declaring — its read model was deleted, or renamed and thereby given a
new identity — is **retired** when the client next registers its full set:

- Its observer is unsubscribed in every namespace, so it stops consuming events.
- Its jobs are deleted and its failed partitions are cleared.
- Its definition is removed from the engine and from storage.
- Its **sink container is left untouched** — data is never deleted implicitly. Drop or clean the
  container yourself if the data is no longer wanted.

Retirement only happens for a **full-set** registration: the client SDK marks the registration as the
complete set for its owner, and only when every discovered artifact produced a definition. Partial
registrations — such as saving a single projection from the Workbench — never retire anything, and a
client-owned full set never retires server-owned projections (or the other way around).

### Renamed read models and shared containers

A renamed read model keeps its type name and thus its **container name**. Without retirement, the old
projection and its successor would keep writing the same container with different definitions and
overwrite each other's documents. With retirement the old projection stops, and because another
registered projection targets the same container, Chronicle raises a replay recommendation for the
successor so the container can be rebuilt cleanly from its definition alone.