# Server source of “A site made of blocks”

Everything the browser talks to. Secrets (platform token, model key) come from the server environment; none are in these files.

| file | role |
|---|---|
| `proxy.py` | the only server process (port 18451 behind Caddy). Serves `/api/blocks/*`: state, render with a cache, re-registration of a handler version on a device, block generation through a model, the visitors' library (platform KV), export bundles. |
| `block_core.py` | the block language: seven block types with text-only fields, escaping of every string, two renderers (v1 editorial, v2 compact dark), the laws `vat` and `ru`. |
| `handler_tail.py` | the device-side entry point of the HTML handlers v1 and v2: one renderer, two looks, chosen by the constant `VERSION`. |
| `handler_text.py` | handler v3, written separately. It shares only the grammar (`validate`) with the others and renders the same documents as plain text for a terminal or a messenger. |
| `build_registrar.py` | builds `demo_register_block_v1.fython` and `_v2` from the core and the tail, computes `HANDLER_SHA`, saves both experts in the agent scope. |
| `demo_register_block_v*.fython` | the registrars as deployed: run once on a device, they register the handler for the language `block` there. |

## Device and handler are two axes

A language handler is a registration on a device. `proxy.py` keeps which version each device holds (`STATE["handler_on"]`). When a render asks for the other version, `ensure_handler()` runs the matching registrar on that device first (one platform call, about 10 s), under a per-device lock, and only then renders. The device's answer carries `handler_version` and `handler_sha`; the page shows those, not the request.

## Check the two claims

1. **Handler hash.** Take the registrar file, cut the text between the triple quotes, drop the line that starts with `HANDLER_SHA = `, sha256 the rest. It must equal `handler_sha` in any render answer from a device holding that version.
2. **Model calls.** `generate_block()` is the only function that reaches a model provider; `calls_count()` is incremented there and returned as `model_calls_measured` with every answer. A render returns 0; a block generation returns 1 or 2 (one retry allowed).

## Cache

The first view of the site is a stored result of an earlier live render; every stored block carries `rendered_at`, and the page labels the whole site as stored when all blocks are. “Render again, live” sends `force: true` and runs every block on the device now.

## The site with a brand book (the page at /blocks/)

| file | role |
|---|---|
| `block2_rules.py` | the brand book of the coffee site: title length, button words, banned words, currency, plan features, quote author; appended to `block_core.py` |
| `handler_tail_b2.py` | the device-side entry point: `check` (grammar and brand book), `render`, `site` (every block of the site rendered by this handler in one call) |
| `build_block2.py` | builds the handler in three versions — prices as written, prices with 20% VAT, the VAT law with a mistake (VAT added twice) — their registrars and the guard |
| `block2_handler_*.py` | the three handler texts as deployed |
| `demo_block2_guard.fython` | the guard: renders every saved block under a candidate handler and checks every price against its own calculation; registers the candidate only if nothing is wrong |
| `blocks2_api.py` | the page's endpoints `/api/blocks/site/*`: state, render, teach (model writes, the device checks, its words go back, at most three attempts), law |
| `setup_block2.py` | saves the registrars, guard and the site probe in the account and registers the plain handler on a device |

The page that used to live at /blocks/ is closed; /blocks/classic/ forwards here. Its server files are the ones listed above this section.
