Caching and content versions on tenant sites

Tenant sites are rendered, not deployed. That single fact is why this page exists: there is a cache in front of your pages, a version counter behind them, and a publish step joining the two. Understanding the order of those three things explains almost every "my change did not appear" report we get.

Two states, and only one is public

Every row in a collection — and the page structure itself — carries a status: draft, staged_draft, or live. The public read side filters on live and nothing else. A staged row does not exist as far as a visitor is concerned.

That is the whole staging contract. Edits from the dashboard, from the engine, and from the site's API all land as staged by default; live is reachable through publish and through nothing else. A row you meant to hide but never retired stays live, because publish promotes — it does not retire.

What publish actually does

In this order:

1. Copy the staged page structure onto the live document.
2. Promote every staged row of the site to live.
3. Bump the site's content version.
4. Purge the site's cache, by tag.

The first three are one database batch. Either all of them happen or none do, because a version that names content which is not live would be a claim the cache could act on. The purge is a separate call and it can fail; when it does, the content is already live and the cache may be stale. That is why the failure is surfaced instead of swallowed: publish again. A second publish promotes nothing and purges again, so it is always the recovery path.

A publish with zero staged rows is legitimate, and it still bumps the version and purges. There is no such thing as "nothing to publish" from the platform's point of view.

What the version is, and what it is not

The content version is a per-site counter, incremented once per publish, and it is the number the dashboard shows you as v1, v2, v3. It names a generation of your content, and it never advances ahead of the rows it names.

It is worth being precise about the other half, because it is easy to overstate. What actually invalidates a cached page is the purge by tag in step four. Every page response carries the site's tag alongside its own page tag (and a collection tag when the page renders collection data), so one purge call invalidates the whole site at once. The version is the record that says "this is a new generation"; the tags are what let the cache be told about it. If you are debugging, watch the version and remember the purge did the work.

Two consequences follow from the promotion rule:

• Existing live rows stay live. Publish is additive. Retiring a row is an

edit you make deliberately, not a side effect of publishing something else.

• An unpublished row is a 404. To a route asking for live rows, "staged" and

"does not exist" are the same answer.

What is cached, and for how long

A tenant page response carries a shared-cache policy: fresh for a short window, then served stale while a fresh copy is rebuilt in the background. Stale is not wrong — it is last publish's render, and it is better than making a visitor wait.

A cache hit is a cached render. A cache miss is a real render: the page is built, the rows are read from the database, and the HTML is produced before anything is sent. That costs work on our side, on the first request to each page after a publish, and on a cold node anywhere in the world. It is the honest reason a site feels briefly slower straight after you publish.

Working with it

Save freely — draft and staged states exist precisely so that saving is not a public act. Publish when the set of changes is one you want the world to see, and expect the site to be briefly cold immediately afterwards.

If a change does not appear, check the row's status before you check anything else. Most reports that arrive as "your cache is serving me stale content" turn out to be a row that was staged and never published, which is the same thing to a visitor and a very different fix.