1# Mosaic23A Takuzu field an agent has to explore: tiles of mixed shape and size4(rectangles, L, T, plus, notched) scattered over a grid with holes,5overlapping each other by shared cells. Every tile is a binary puzzle on6its own lines (each maximal horizontal or vertical run of its cells:7balanced, no three in a row, no two equal lines of one orientation and8length); the only rule across tiles is that shared cells agree. Every tile9alone has 2-4 solutions; the field as a whole has one. This repo state is10a localhost referee and spectator for watching agents work it live, with11every step replayable. `PLAN.md` is the build order and the decisions12(manifest v3 is the current shape).1314## Layout1516```17engine/ Go: mosaic-engine gen | judge | pack (pure JSON in/out; the only place Takuzu rules exist)18site/ Deno 2 + Fresh 2: referee, append-only JSONL log, /mcp, SSE, canvas viewer19docs/ architecture page (fishbowl.html) and the reference renderer (mock-mosaic.py)20```2122The engine's only dependency is `github.com/crillab/gophersat` (pure Go23CDCL SAT solver) behind `engine/sat`: completion, feasibility and counting24of one tile window. `engine/rules` is the propagation solver that models25human technique (forced/guess attribution, difficulty ladder).2627## Run2829```30cd engine && go test ./... && go build -o bin/mosaic-engine .31cd site && deno install && deno task dev # prints the agent prompt, serves http://127.0.0.1:800032```3334Open `http://127.0.0.1:8000/`, paste the printed prompt into Claude Code or35Codex, and watch. Replay a finished game at `/?replay=<game_id>`; its log is36at `/log/<game_id>`. The hosted daily is at https://mosaic-daily.fly.dev/37(one field per UTC day, calendar and leaderboards; see `deploy.md`).3839Scripted client (also the protocol smoke test):4041```42cd site && deno task solve -- --seed a --G 27 --kind grid --n 14 # the phase-1 2x243cd site && deno task solve -- --seed a --G 60 --kind scatter # a scatter field44cd site && deno task solve -- --seed a --kind field --chunks 3 # a chunked field that grows45cd site && deno task solve -- --url https://mosaic-daily.fly.dev/mcp --join day-<date> --agent me --model my-model46```4748Boards are fields of shapes (manifest v3, see PLAN.md): `mosaic-engine49pack --kind scatter --G N` drops shapes at seeded random positions with50rectangular overlaps and small holes (`--coverage`, `--compound`,51`--max-hole`); `mosaic-engine gen --seed S --G N --kind scatter` fills52one. A daily-sized field is chunked: `mosaic-engine field --seed S --G531000 --chunks 3 --chunk-G 60 --rings all` generates the centre cluster54and every ring around it (checkerboard of chunks, each a process); the55site reveals rings during the day as `grow` events. `grid` (X-by-X56squares of side n, `--X --n`) is kept for the 2x2 standard and the X=1557envelope. Generation is a batch job cached under `site/data/cache/`,58keyed by generator version (`mosaic-engine version`), seed and59parameters; the nightly runs on slate (`.woodpecker/nightly.yaml`) and60pushes the next day's field to the hosted app. Measured timings are in61PLAN.md.6263## Tests6465- `engine`: `go test ./...` covers rules on shapes and lines (attribution,66 enumeration with rule masks, coupling on shared cells, flip rectangles67 on shared lines, the coupled-tile CSP, shape validity incl. the68 distinct-lines bound), the SAT encoding (completions valid and varied,69 joint completion keeps neighbours feasible, counts agree with the70 propagation solver, determinism under concurrency), the packer (shape71 validity, the overlap acceptance rule, hole statistics), the fill order,72 generator determinism and every per-tile assertion (re-verified from73 the JSON) on the 2x2 and X=15 fixtures and on scatter fields, and the74 judge (classification and the <50 ms budget). `MOSAIC_SLOW=1` also75 regenerates the 2x2 fixture from its seed and compares.76- `site`: `deno task test` covers geometry and hue assignment, colour77 mixing, delta coding, referee gating (frontier, territory, revision),78 agents and meets, region-scoped observe under fog, growth, the79 analyzer, live-fold == replay-fold at every revision, the daily loop80 (rollovers, archives, leaderboards, honours, restart), and that every81 finished game log on disk replays to a solved state with the right82 reward.8384## What the generator guarantees (per tile, asserted; see `gen.PolicyFor`)8586- 2..m solutions alone (m by cell count: 2 up to 64 cells, 3 up to 196, 487 above); every alternative differs from the truth inside an overlap88 region shared with a neighbour (so a solved neighbour can pin it).89- Blank floor 55% (<= 64 cells), 65% (<= 100), 70% above.90- From 144 cells: with all its shared cells fixed the tile is unique, needs91 at least one bifurcation (rules 1-3 stall), and needs the uniqueness92 constraint (it has a second solution without it).93- The whole field has exactly one coupled solution (CSP over the tiles'94 solution sets and their shared cells).9596Shared cells are given only where blank overlaps would leave more than m97solutions; the manifest records `rules.seam_clues: true` when any were98used. Holes (cells no tile covers) are void. Coupling depth `k` is99`unmeasured`.