# sitoolz

District (workspace 0.1.6): `si.district.patch`, `height`, `plan`, `rows`,
`frame`, `World`. A 2x2 window composes patch-owned parcel structures with
integer terrace floors. Core/gate levels 32/34/36; original Atlas gate heights
remain source values in the dataframe, not the actual district floor.
Four reserved wayhouses, optional houses/gardens/groves, supported movement,
exact far addresses and matching Python/JS plans. 100 rows / 32 columns.
Generator v1. Bounded 128x128x128 study, not an unbounded streamer. No arbitrary
player edits yet. See cards/district.md. Standalone module in version 0.6.0:
`sitoolz_foundry.district` / `@sitoolz/foundry/district`.

Parcels (workspace 0.1.5): `si.parcels.patch`, `rows`, `frame`.
Four patch-owned lots have indices 4*patch_index+slot, exact root/remainder,
ruler sizes, stable feature addresses and optional XOR/density sieve outcomes.
Roads and entries are reserved; adjacent gates share Atlas records. All bounds
are half-open horizontal rectangles. This is not yet 3-D walkable geometry.
21 rows / 24 columns; Python pandas/dfkit fallback, JS JSON-ready records.
Standalone `sitoolz_foundry.parcels` / `@sitoolz/foundry/parcels` in 0.5.0.
See cards/parcels.md for ownership, domains, evidence and elevation work ahead.

Crossing (workspace 0.1.4): `si.crossing.plan`, `World`, `rows`, `frame`.
Canonical east/west Atlas edge, two wayhouses, stairs, bridge, nine named spaces.
Use World.column/material/clear/move/locate for Habitat-compatible occupancy and
supported walking; World.address(position) returns exact global patch/cell,
subcell and vertical ticks from a bounded local position. `cards/crossing.md`
describes the 21 feature rows and required-vs-optional selection. This is one
reserved edge structure; independently generated crossings are not yet composed.
The website supports WebGL and automatic/forced Canvas 2D, with the same saves.

Atlas (workspace 0.1.3): `si.atlas.patch_index`, `patch_at`, `address`, `split`,
`join`, `parent`, `next_rank`, `height`, `boundary`, `patch`, `surface`, `rows`,
`frame`, `square_xor_rows`, `square_xor_frame`, `encode`, `decode`. JS names
are camelCase; table rows are JSON-ready. Patch domain [-2^62,2^62-1]; exact
large wire values are decimal strings, never unsafe Number coordinates.
`frame` uses pandas or dfkit.Frame. cards/atlas.md documents bounds, signed
square/XOR identities and candidate index stability through sieves. AT1 saves
an address; it does not save edits. The atlas is a bounded map inspector, not
a connected 3-D streamer. Standalone distributions export an atlas submodule.

Habitat (workspace 0.1.2): `si.habitat.plan(recipe)`, `World(recipe)` with
`column(x,z)`, `material(x,y,z)`, `clear(position)`, `move(position,dx,dz)`,
`locate(position)`. JavaScript has matching names; construct `new World`.
Read `cards/habitat.md`: geometry is integer, body positions are fixed point
at 256 ticks/unit, and the walker stays on supported surfaces with a ledge
guard. A bounded prototype has 17 connected spaces, shared portal IDs and
verified GF(2) lamp coefficients. The client saves RFH1 place state; arbitrary
user geometry edits and model-specific clients are not part of this release.

Foundry (workspace 0.1.1): `si.foundry.recipe`, `sample`, `window`, `settlement`,
`light_row` (JS `lightRow`), `square_address`/`square_index` (JS camelCase),
`encode`/`decode`. One data-only versioned integer recipe generates height,
square fields, sieve decisions, stable lot IDs and indexed light. Read
`cards/foundry.md` for explicit domains and costs. The `RulerFoundry` client
uses the same interfaces and supports JSON and Hamlet PNG recipe/view sharing.
These four engines are ported from spindexin/RulerFoundry (developed there with Codex); `tools/port-spindexin.py` keeps them in step.

> A toolkit for working with a superintelligence: terrain, settlements, weather, indexed randomness, primes, puzzles, forests and logic from arithmetic, written twice (Python and JavaScript) and checked against one fixture. The laws are Lars Rocha's.

sitoolz is a Python package (`import sitoolz as si`) and a JavaScript library (`js/index.js`, global `SIToolz`) with the same function names on both sides. Every refactored engine is a module at the top of the package; every other library from pytoolz is available as `sitoolz.<name>` on demand (the annex).

## The rules

1. One law, one card: `cards/<engine>.md` gives the arithmetic in a sentence, both signatures, what it produces, the fixture and the credit.
2. Two twins, one fixture: `tests/write_*_fixture.py` writes `fixtures/*.json` from the Python; `tests/twins-*.test.cjs` checks the JavaScript against it. A law is in only when both pass.
3. Credit travels with the code: `CREDITS.md`, `CITATION.cff`; every module names its author.

## Engines

- terrain: `si.terrain.window(world, x0, z0, w, h)` gives heights, colour classes, light-cone spans, prizes and a gate for any renderer; `si.terrain.WORLDS` holds the fourteen ranges. Laws in `si.rulerland` (hills by rank, lattice, ladder, plateaus, the light cone, rivers, Walsh mesas, Gaussian isles, dunes, Sudoku mesas, Legendre marches, synth, prizes, warp addresses).
- settlements: `si.citylaw.plan(kind, g)`, `sites_in`, `census`, `biggest_between`; places: `si.stamps`, `si.rails.railway(sites, ground)`.
- indexed randomness: `si.indexrng.Index(seed)`, `si.qrand`, `si.gamerng`; `si.indexrng.Commit` for provable fairness.
- primes: `si.primes.create_prime(bits)`, `verify_certificate`, `descend`, `lucas_lehmer`, `si.primes.base`.
- clocks: `si.clocks.spectrum`, `spectrum_linear`, `synthesize`, `weather`.
- puzzles: `si.puzzles.solve` (Larsdoku), `solve_singles`, `is_solved`, `fits`.
- forests: `si.forests.export`, `predict`, `rank`, `explain`; `si.forests.wsrf`.
- logic: `si.logic.ConstraintSystem`, `LarsSolver`, `solve_xor`, `assignment`.
- mesh: `si.mesh.build_chunk(chunk)`, the triangles of a chunk; vehicles: `si.vehicles.step_drive`, the duel.
- primerails: `si.primerails.height(g, z)`, the prime rails as a world (L/R rails, the address book, Cunningham towers, Proth ridges); `terrain.WORLDS["prime-rails"]`.
- folds: `si.folds.keeps_gap`, `shadow`, `fork`, nested squares `hide/find/peel`, `square_lock`, `vault`; the Fold Marches world.
- cascade: `si.cascade.shell_run` (exact integer dyadic cascade), `flow_run` (2-D vorticity, divergence exactly zero); the Vortex Sea world; `flood(region, hour)`.
- octaves: `si.octaves.octave_reader(k)`, `beacons`, `stipple`; the Octave Valleys world. machines: `si.machines.object_id/decode_id` (Perfect Machines), `harmonic_noise`.
- hamlet: `si.hamlet.encode/decode/postcard`, Lars's scannable place code; `zones`: the Z/13 ring, GF(k) parity, the Connect-4 parity evaluator; `saves`: seed plus a choice string, rewind, branch, prophecy.
- arena: `si.arena.play_paired`, `block_bootstrap`, `ablation` (paired seeds, swapped seats, intervals). codec: `si.codec.pack_edits`, `pack_tops`, `to_base64url` (edits packed against the generator's own ground). gpu: `si.gpu.valley_grid` (optional Taichi, `pip install sitoolz[gpu]`).
- gpu (optional, `pip install sitoolz[gpu]`): every landscape law as a Taichi kernel checked cell for cell (`si.gpu.check_all`), `relief` (a hillshaded region map), `flow_step` (the Vortex Sea alive), `fly` (a ray-marched flyover); the showcase's `maps.py --gpu auto` draws the 18 landscapes 133x faster with identical pixels.
- experiments (`experiments/README.md`, 18 reports + `WSRF_FIXES.md`): a forest against each law, what it read back and what it could not; the two `wsrf` defects they found (multi-class routing, a calibrator applied to pure zones) are fixed in the kit's copy.
- fluidz: `si.fluidz.run(N, nu_shift, T, amplitude, record, scheme)`, the Burgers equation on the integer lattice (the Ruler Dunes' profile); txs: `si.txs.spectrum`, `synthesize`, `Bank` (exact spectra of XOR registers; the Synth Range's taps).
- forge: `si.forge.gaps_to`, `record_gaps`, `twins_to`, `partner(p)`, `cunningham_chain(p)`, `forge(n, k_lo, k_hi)` (twin primes k·2^n ± 1, proved both ways); the Prime Rails' bridges read from it.
- edgecert: `si.edgecert.certify(ymax, gens, patterns)`, `verify_certificate(cert)`: rule 30's edge as a certificate (period tables with witness pairs, runs with rungs, reachability witnesses) that verifies by lookups and XORs alone.
- fast30: `si.fast30.centre_column(gens)`, `centre_bits`, `centre_value`: rule 30's centre column (A051023) across the whole cone; `indexrng.edge_coverage(samples)` says how many generations a sampling scheme touches are one ladder lookup away.
- ntpar: `si.ntpar.predict(m, i)`, `law(b)`, `census`: the parity of squares bit by bit; `folds.stays(m, i)` is the same rule with no square root.
- shores: `si.shores.shore_height/bridge_height/wall_height(g, z, ...)`, `lattice(step)`, `block(b)`, `breaks(g)`: the Burgers Shore, the Forge Bridges and the Certificate Wall, three worlds from fluidz, forge and edgecert.
- oeis: `si.oeis.terms(A, n)`, `check(A)`, `verify()`: 28 sequences the kit and OEIS both compute, pinned; the kit's fixtures are the authority for its own sequences, OEIS a courtesy check where they overlap.
- rulers: `si.rulers.vp(p, n)`, `gauss_rank(a, b)`, `rank_of_rank(g)`, and the hill laws over them; the Ternary Hills, the Gaussian Downs and the Meta Hills.
- blends: `si.blends.sixfold_height`, `ternary_canyon_height`, `ternary_isles_height`: Lars's tricks over the ternary ruler as four worlds (the Sixfold Hills and Alps, the Ternary Canyons and Isles).
- skies: `si.skies.skyway_height`, `slots_height`, `vale_height`, `skymesa_height`: four ranges for the fast and high craft (the Skyway, the Drone Slots, the Balloon Vale, the Sky Mesas).
- tour: `si.tour.tour_height(g, z, tour)`, `tour_district`, `tour_schedule`: five tours composing every law by district (grand, sky, buggy, monster, hover).
- meshz: `si.meshz.level(x, z)`, `active`, `tile(x0, z0, n, cx, cz)`, `conforming`, `patch`: the ground as one crack-free mesh on the ruler (a vertex's level is its Gaussian rank; rings doubling).
- skylight: `si.skylight.transfer(hz, n, order)`, `skySH(zenith, horizon, sun, glow, order)`, `irradiance(T, L)`, `bake(grid, nx, nz, s, hy, far)`: the sky a ground point sees as spherical harmonics from its eight horizon angles; any sky lights it in one dot product.
- lanterns: `si.lanterns.forge(word, "square"|"hex"|"ruler", rows, cols)`, `solve`, `hint`, `press`: lantern puzzles over GF(2), solvable by construction, the fewest presses proven, the hint never wrong.
- wander: `si.wander.open(world, opts)`, `chunk(inst, ci, cj)`, `lanterns`, `start`, `tile`: Wander's 82 worlds without the client; `js/wander.js` is the same in Node. The JavaScript is the original here and Node writes the fixture (`cards/wander.md`).

## Invariants a model can rely on

- A column's rank is `v2(g+1)`; a rank-k column comes every `2^k` columns; hills, cities, stations and prizes all stand on that.
- Any engine can add a world to the terrain table with `terrain.register(kind, law, world, name)`; the new engines do so on import, so `terrain.height("vortex-sea", x, z)` works once `sitoolz.cascade` is imported (in a page, load the engine's script after terrain.js).
- `rulerland.cone_bit(y, g)` is exactly periodic in `g` with period `2^p(y)` (the prefix law); `clocks.spectrum` gives `p`.
- `indexrng`/`qrand` values are pure functions of `(seed, stream, index)`: the same on every machine, no state.
- A Pocklington certificate verifies from a trial-divided seed with no probable-prime oracle.
- Everything in `fixtures/` was written by the Python and is reproduced by the JavaScript; `npm test` and `python3 tests/test_sitoolz.py` prove it.

## Where to look

- `START_HERE.md` (a seed to a walkable world in twenty minutes), `tools/everything.py --quick` (one table, 44 engines), `README.md` (the constitution), `ROADMAP.md` (the checklist), `cards/` (one per engine; `CATALOG.md` lists every function; `ANNEX.md` lists every other library), `examples/` (twenty-line programs in both languages), `../sitoolz-showcase` (every law drawn twice, identical).