# hamlet · the place code

**Lars Rocha's Hamlet code** · `js/hamlet.js` (the editions site's `hamlet/layout.js`, `rs.js` and `hamlet.js`, byte for byte inside one module; the original) ↔ `sitoolz/hamlet.py` · fixture `fixtures/hamlet.json` (Node writes, Python checks)

## The arithmetic

A scannable square built on the settlement lattice, with no corner finders and no timing rows. Its landmarks sit where both
coordinates have rank four or more, `rank(i) = v2(i+1)`, the settlement rank, sized 3, 5 or 7 modules by the smaller rank
(hamlet, village, town), the largest at the centre. Around every anchor of rank exactly 4 (the centres of the 32-blocks) the
same 24-byte codeword repeats: the place, 16 bytes (size, world, x, z, moment, a seed of up to ten letters and digits, a
check byte) in RS(24,16), 192 cells in a fixed spiral. At N = 128 the four anchors of rank exactly 5 carry a 21 × 21 village
(the first 24 bytes of the town in RS(46,24)). Everything else is the town, the build, cut into one independently decodable
shard per 32 × 32 district (a 3-byte header, data, a quarter parity) under an outer code across districts, RS(4,3) at 64 and
RS(16,12) at 128. The mask is `at(0, x mod 32, y mod 32, streamOf("hamlet"))`, relative to the 32-block, so a scrap unmasks
without knowing where it lies.

**The window lemma.** In any window of positions the maximum rank `m` occurs once (two positions of rank `m` differ by an
odd multiple of `2^m`, and a position of rank at least `m+1` lies between them); if it sits at offset `i*` in a window
starting at `n`, then `n ≡ 2^m − 1 − i* (mod 2^(m+1))`, and nothing more is determined. Layer `k` is replicated with period
`2^(k+1)`, the translation the lemma cannot see, so a torn scrap decodes its layer using only what the ruler gives it: any
scrap of side 46 or more contains a whole hamlet and reads the place; every quarter reads its districts; the quarters
gathered complete the town; a lost district is rebuilt by the outer code.

## Both signatures

| JavaScript (`SIHamlet`) | Python (`sitoolz.hamlet`) |
|---|---|
| `layoutFor(N)`, `layout.rank`, `layout.anchorCells(d)`, `HAMLET_OFFSETS`, `VILLAGE_OFFSETS` | `layout(N)`, `anchors(N)`, `mask(N)`, `rank`, `anchor_cells(d)`, `HAMLET_OFFSETS`, `VILLAGE_OFFSETS` |
| `phaseFromWindow(n0, L)` → `{m, at, phase, mod}` | `phase_from_window(n0, L)` |
| `rs.encode(data, nsym)`, `rs.decode(codeword, nsym, erasePos)` | `rs_encode`, `rs_decode` |
| `encode({N, place, town})` → `{grid, place, capacity}`; `decode(cells, w, h, {gathered, N})`; `scrap(grid, N, ox, oy, w, h)`; `rotate` | `encode`, `decode`, `decode_scrap`, `scrap`, `rotate`, `find_anchors` |
| `packSeed`, `unpackSeed`, `crc16`, `readPlace`, `placeBytes` | `pack_seed`, `unpack_seed`, `crc8`, `crc16`, `read_place`, `place_bytes` |
| `postcard(text)` | `postcard(text)`, `rows(grid, N)`, `pbm(grid, N)` |

Grids are `N*N` values, 1 dark; scraps carry −1 for unknown cells. Reed–Solomon is GF(256) with the QR conventions
(0x11D, generator 2, first root α⁰), checked against the QR reference vector.

## The fixture

The three layouts (anchors, hamlets, villages, districts, shard counts, capacities 68 / 203 / 644 bytes, the mask), the QR
reference parity and 60 RS trials with injected errors and erasures, 10,672 windows of the lemma, 32 codes at the three sizes
for four places and four towns: every grid cell for cell, the whole decode, three rotations, damage within the budget,
46-, 60- and half-side scraps with their places and districts, the four quarters gathered to the town, a torn card with its
last district rebuilt; and three postcards (warp addresses as codes). 11,009 checks identical between the two.

## In the kit

Any warp address or build code can be printed as a postcard code that a phone reads from a torn corner; the showcase
draws the three postcards. The editions site keeps its camera and canvas (`hamlet/vision.js`, `render.js`, `page.js`).

## Provenance

The Hamlet code, its window lemma and its layout are Lars Rocha's (`range-arcade-editions/hamlet/README.md`,
`mywork/hamlet-code-recommendation.md`).