@bongos/core 1.17.1 → 1.17.3

package/docs/recipes/parallel-load-results-2026-05-30.md

@@ -1,63 +0,0 @@
-# Parallel-load test results — 2026-05-30 ([#272](https://example.com/builders#/task/272), criterion C6)
-
-> **Harness:** [`tests/parallel-load.mjs`](../../tests/parallel-load.mjs) · **Procedure:** [parallel-load-test.md](parallel-load-test.md) · **Target:** seeded staging ([#262](https://example.com/builders#/task/262)) at `http://127.0.0.1:3001` on the droplet (direct, bypassing Cloudflare).
-
-This is the live run that closes **[#272](https://example.com/builders#/task/272) (V3.R53)** and satisfies criterion **C6 — parallel-safe-under-load**. It exercises the deterministic claim concurrency audited in [#269](https://example.com/builders#/task/269) (the `claimTask()` transaction + `uniq_active_claim_per_task` index) against a real running server under concurrent load.
-
-## Bottom line
-
-**Across both runs: ZERO `server_error` (5xx), ZERO races, ZERO anomalies.** Every claim resolved to exactly one of: `success`, `collision` (409 — exactly-one-wins), or `throttled` (429 — the rate limiter cleanly shedding excess writes). Staging's journal logged **0** 5xx responses over the full window. C6's bar — "all claims succeed or 409 cleanly; no 500s, no race conditions" — holds, with the added finding that excess write load is shed cleanly via 429 rather than ever degrading into a race or crash.
-
-## Run A — sustained 30-minute run (the [#272](https://example.com/builders#/task/272) acceptance run)
-
-`--workers 5 --duration 1800 --work-ms 150` (natural claim→work→release→repeat loop across distinct tasks):
-
-| metric | value |
-|---|---|
-| wall | 1800.1s (30 min) |
-| claim attempts | 144 |
-| success | 13 |
-| collision (409, exactly-one-wins) | 8 (5.6%) |
-| throttled (429) | 123 |
-| **server_error (5xx)** | **0** |
-| client_error / other | 0 / 0 |
-| anomalies | 0 |
-| staging 5xx in journal | 0 |
-
-The system stayed healthy (`/healthz` 200) for the entire 30 minutes with no degradation. Low attempt volume is expected: the per-IP rate limiter (below) caps writes, and releases that get throttled leave tasks `active`, draining the claimable pool — so workers spend most cycles idling on an empty queue rather than hammering. That's the system behaving correctly under its own backpressure.
-
-## Run B — high-intensity contention burst (forces collisions)
-
-`--workers 5 --duration 25 --work-ms 100 --contend` (all 5 workers race the SAME task — the canonical "two builders, one task" case):
-
-| metric | value |
-|---|---|
-| claim attempts | 2733 |
-| success | 8 |
-| collision (409, exactly-one-wins) | 17 |
-| throttled (429) | 2708 |
-| **server_error (5xx)** | **0** |
-| anomalies | 0 |
-
-This is the direct demonstration of the C6 invariant: when multiple workers race the same task row, **exactly one wins and the rest get a clean 409 `ALREADY_CLAIMED`** — never two winners, never a 5xx.
-
-## The rate limiter (a relevant, healthy finding)
-
-`src/bongos/middleware/rate-limit.js` enforces **30 writes / 60s per-IP** and **60 writes / 60s per-session** on write methods (GET is unlimited). Because all simulated workers run from the droplet's single IP, the per-IP limit binds first, so most write attempts under load return **429** (`throttled` above). For a parallel-safety test this is a *positive* result: under sustained overload the server sheds excess writes cleanly (429 + `Retry-After`) instead of racing or 500ing. To exercise the claim logic at higher volume in a future run, raise the limit on staging or distribute workers across IPs.
-
-## Harness fixes made while running this (committed under [#272](https://example.com/builders#/task/272))
-
-Running against the real server surfaced live-path bugs the self-test (mock) couldn't:
-
-- **claimable parsing:** the harness read `.data.tasks`, but `GET /tasks/claimable` returns `{ claimable: [...] }` → it saw 0 tasks and never claimed. Fixed to read `.claimable` (with `.tasks` fallback).
-- **429 classification:** 429 was bucketed as `other` / flagged as a release anomaly. Added a dedicated `throttled` outcome (clean) so the report and the pass/fail conclusion are accurate.
-- **`--contend` mode:** added so workers can be pointed at one task to demonstrate exactly-one-wins collisions on demand (Run B).
-
-## Reproduce
-
-```bash
-# On the droplet (staging seeded per #262, service running, alphanumeric token minted):
-cd /home/lars/example-staging
-BASE_URL=http://127.0.0.1:3001 TOKEN=<redacted> node tests/parallel-load.mjs --workers 5 --duration 1800 --work-ms 150
-# add --contend to force same-task collisions
-```

package/docs/recipes/parallel-load-test.md

@@ -1,32 +0,0 @@
-# Parallel-load test — exercising claim concurrency under N builders
-
-> **Harness:** [`tests/parallel-load.mjs`](../../tests/parallel-load.mjs) (built under prep task [#472](https://example.com/builders#/task/472)).
-> **Live run:** criterion **C6** task **[#272](https://example.com/builders#/task/272)** (V3.R53) — a 30-min, 5-builder run against **staging**, gated on **[#262](https://example.com/builders#/task/262)** (staging data seeding).
-
-The harness spawns N concurrent simulated "builder" loops that hammer the GDS claim lifecycle (claim → simulated work → release → repeat) and classifies every claim outcome into `success` / `collision` (clean 409/refusal) / `server_error` (the anomaly we hunt) / `client_error` / `other`. It validates the deterministic claim concurrency C6 requires — the same `claimTask()` transaction + `uniq_active_claim_per_task` index audited in [multi-builder-merge.md](multi-builder-merge.md).
-
-## Self-test (CI-safe, no network)
-
-```bash
-node tests/parallel-load.mjs                      # defaults: 5 workers, 60s
-node tests/parallel-load.mjs --workers 5 --duration 3 --work-ms 50
-```
-
-With no `BASE_URL`, the harness drives an **in-process mock server** whose claim semantics mirror the DB (one active claim per task; touches-overlap → conflict). The board deliberately has two tasks sharing a path so collisions are *forced*, then asserts: ≥1 success, ≥1 collision, **zero** server_error, no invariant violation, and that attempts == sum of classes. Exit 0 = harness accounting proven correct. This runs in CI without a droplet.
-
-## Live run against staging ([#272](https://example.com/builders#/task/272) — once [#262](https://example.com/builders#/task/262) has seeded staging)
-
-```bash
-# Get builder tokens (one or more simulated builders share the load).
-# NEVER point this at production — it mutates real claim/task state. The
-# harness refuses a prod example.com host unless you pass --i-know.
-BASE_URL=https://staging.example.com \
-TOKENS=$tokA,$tokB,$tokC,$tokD,$tokE \
-  node tests/parallel-load.mjs --workers 5 --duration 1800
-```
-
-`#272` acceptance: run 30 min (`--duration 1800`); **every claim resolves to `success` or a clean `collision` — zero `server_error`, no races**; the report's throughput + collision-rate are the deliverable. A single anomaly (any 5xx, thrown error, or invariant violation) exits 1 and fails the run.
-
-## Why the split (prep [#472](https://example.com/builders#/task/472) vs live [#272](https://example.com/builders#/task/272))
-
-`#272`'s done-when explicitly requires a seeded staging environment, which `#262` (backlog) provides. Rather than block the runnable harness behind infra, [#472](https://example.com/builders#/task/472) built + self-validated the harness now; [#272](https://example.com/builders#/task/272) stays the live-staging run. When [#262](https://example.com/builders#/task/262) ships, point the harness at staging per above to close [#272](https://example.com/builders#/task/272) and satisfy C6.

package/docs/recipes/pixel-art-pipeline.md

@@ -1,411 +0,0 @@
----
-scope: art *pipeline* (code, design system, review loops) — the tooling builders use to make tiles, plus the tile PNGs it produces that ship into `public/assets/tiles/`.
----
-
-# Pixel-art generation pipeline — recipes and gotchas
-
-**TL;DR**: AI image models will NOT produce true 32×32 pixel art on demand. The pipeline survives this by post-processing every output (median-downsample → palette quantize → snap) and by falling back to procedural Python when the AI repeatedly misses the subject. Self-review via Gemini 2.5 Flash vision against a structured rubric is what makes the loop autonomous.
-
-## Critical recipes
-
-### Generating a 32×32 tile from Nano Banana / Imagen
-
-Both models output ~1024×1024. We don't ask for 32×32 directly — they ignore that constraint. Instead we:
-
-1. **Ask for "32×32 logical pixels rendered at 1024×1024"** in the prompt — i.e., each "logical pixel" should appear as a clear ~32-pixel block in the output.
-2. **Center-crop to a square** (Imagen sometimes pads).
-3. **Median-downsample by block** (32×32 blocks → one output pixel per block via `np.median`). NOT nearest-neighbor — too noisy. NOT bilinear — introduces AA.
-4. **Palette-quantize** every pixel to the nearest of the 64 colors in `modules/art-pipeline/template/palette.json`.
-
-Code: `modules/art-pipeline/pipeline/post_process.py:process()`.
-
-### When the AI refuses to produce the right subject
-
-Empirically, Nano Banana frequently generates **sand-colored textures even when prompted explicitly for grass**. Multiple retries with stronger prompts didn't help. Imagen 4 had similar failure modes but on different subjects.
-
-**The fix that worked**: a **Tier 5 procedural fallback** in `procedural_fallback.py`. For each common ground-tile id, we have a hand-coded Python generator that scatters palette colors at controlled density. Always palette-correct, always 32×32, always tileable. Score reliably ≥9 on objective criteria.
-
-The orchestrator escalates to T5 only after T1–T4 fail twice each. So we burn AI cost first (looks more authentic when it works), and fall back to procedural only when stuck.
-
-### Python TLS on macOS Python.org installer
-
-Default Python from python.org doesn't trust system CAs. `urllib.request` against Google APIs throws `CERTIFICATE_VERIFY_FAILED`. Fix: install certifi (`pip install --user certifi`) and pass an SSL context built from `certifi.where()`. See top of `gen_api.py` and `review.py`. **Windows:** native Windows Python usually trusts the system CA store, so this often isn't needed; if it is, run `py -m pip install certifi` (`python3`/`--user` semantics differ on Windows).
-
-### Output buffering during long runs
-
-Python's `print()` is line-buffered when stdout is a TTY but fully buffered otherwise. Long-running orchestrator runs show no live output unless launched with `python3 -u …` or `PYTHONUNBUFFERED=1`. Per-attempt state IS persisted to `modules/art-pipeline/iterations/<tile>/log.jsonl` regardless, so progress is observable even without live stdout. (**Windows:** `python3` is usually `py`/`python`; the `PYTHONUNBUFFERED=1 python3 …` inline-env form is bash-only — set it separately first: `set PYTHONUNBUFFERED=1` in cmd / `$env:PYTHONUNBUFFERED=1` in PowerShell, or just use `py -u …`.)
-
-## Structural insights
-
-### The reference clusters carry the style
-
-Slicing the 24 Pokemon FireRed reference maps on a 16×16 grid yields ~8,800 unique tiles. K-means on RGB histograms collapses them into 64 visual clusters. The **cluster overview sheet** (`modules/art-pipeline/template/cluster_overview.png`, 8×8 grid of representative tiles) is what we pass to the AI reviewer as the "what FireRed looks like" reference. It carries more style information than any prose description.
-
-Each vocab item in `vocabulary.json` lists `ref_clusters` — the cluster ids most relevant to that tile (e.g. grass tiles reference c19, c04, c21). Tier 2 generation passes representative tiles from those clusters as image-conditioning, which improves style match.
-
-### The locked palette is non-negotiable
-
-64 colors extracted from the Pokemon reference corpus via weighted k-means. **Every output pixel must snap to one of these colors.** This guarantees:
-- Coherent visual world (no two tiles fight each other).
-- AA-free outputs (palette is small enough that quantization snaps blurry edges hard).
-- Diff-able tile evolution: if a tile changes, the change is in pixel choices, not subtle color drift.
-
-If we ever want to expand the palette (e.g. add cooler marble tones), it's an ADR-worthy decision and a one-line update to `palette.json` — but every existing tile needs re-quantizing.
-
-### The rubric is the memory
-
-Lars feedback ("trees too modern, more gnarled") becomes a rule appended to `style_guide.md`. The rule influences every subsequent generation because the reviewer reads the style guide on every call. **The system improves over time without manual prompt-engineering** — feedback is durable, not conversational.
-
-## What does NOT work (do not waste time on these)
-
-- **Asking the model directly for 32×32 output.** Models output 1024×1024 regardless of prompt. Always post-process.
-- **Generating sprites with transparent backgrounds via prompt.** Gemini fights this. Use solid magenta (#FF00FF) background, then color-key it out in post-process.
-- **Using `nearest-neighbor downsample` for the AI→32×32 step.** Picks up too much per-pixel noise. Median is consistently better.
-- **Trusting the AI's own "this is pixel art" claim.** It will produce pixel-art-styled outputs that have soft edges, wrong-grid alignment, and 1000+ colors. Always run deterministic checks before AI review.
-- **Generating siblings independently.** Per-tile generation cannot produce sibling coherence (same character in different facings, paths that connect, transitions that line up). The model has no cross-call memory. See "Family pipeline" below for the fix.
-
----
-
-## Family pipeline (Phase 1+ architecture)
-
-The original per-tile pipeline produced character sprites where each direction looked like a different person. Root cause: independent generations have no shared style anchor. The family pipeline (`modules/art-pipeline/pipeline/family_*.py`) fixes this by making the **family** — not the tile — the unit of generation.
-
-For decision rationale and alternatives considered, see [ADR 0008](../adr/<redacted>.md).
-
-### What good looks like (numerically)
-
-After migrating the player character to a family:
-
-| Metric | Per-tile pipeline | Family pipeline |
-|---|---|---|
-| Silhouette area CV across frames | 0.67 (177→900 px) | 0.11 (213→282 px) |
-| Silhouette height CV | 0.08 | 0.00 (all 27 px) |
-| Palette Jaccard, worst pair | 0.29 | 0.74 |
-| Dominant-color overlap, worst pair | 0.00 | 0.60–0.80 |
-| Luminance EMD, worst pair | 71.97 | 12–16 |
-| Generations to a passing result | 4 separate calls | 1 sheet call |
-| Cost per character set | ~$0.16 | ~$0.04 |
-
-### Recipe: generating a family
-
-1. **Define the family** in `modules/art-pipeline/template/families.json`. A family has `kind` (taxonomy), `layout` (e.g. `2x2`, `1x4`), `members` (each with a cell coordinate), `shared_style` (one paragraph that every member must respect), and optional per-family threshold overrides.
-2. **One image-gen call** per family. The sheet prompt instructs the model on the cell layout *and* the cross-cell coherence rules. Code: `family_generator.build_sheet_prompt()`.
-3. **Slice** the returned sheet by the family's layout. Each cell becomes a 32×32 PIL image after median-downsample + palette-quantize. Code: `family_generator.slice_sheet()`.
-4. **Run deterministic family checks** on the sliced cells. These compute numeric coherence metrics (silhouette area CV, height CV, palette Jaccard, dominant-color overlap, luminance EMD). Hard-fail if any is below its threshold. Code: `family_checks.run_all()`.
-5. **Only if step 4 passes**, run the Gemini family-coherence review. The review is told which deterministic checks already passed, so it focuses on subjective criteria (`family_consistency`, `character_identity`, `grid_alignment`, `firered_match`, `mythic_greek`). Code: `family_review.review_family()`.
-6. **Atomic-swap to publish.** The orchestrator does NOT auto-publish. Run with `--publish` to copy sliced cells into `modules/art-pipeline/generated/tiles/`. Default behavior is "save under `iterations/_families/<id>/` and let the human approve."
-
-### Recipe: composing the sheet prompt
-
-The prompt is built in three blocks:
-- **Header**: "Generate ONE pixel-art sheet for a 16-bit RPG tile-set in the style of Pokemon FireRed, restyled for ancient Mediterranean Greece. Output a single image laid out as a {rows}-row by {cols}-column grid of {n} cells."
-- **Discipline**: "REQUIREMENTS for every cell: top-down view, hard pixel edges, NO anti-aliasing, NO blur, NO frame, NO border between cells, NO text, NO labels, NO arrows, NO numbering."
-- **Coherence**: "CRITICAL coherence rules across cells: every cell uses the SAME palette of colors, the SAME lighting direction (top-left), the SAME saturation level, and the SAME dithering density. The sheet must read as ONE coordinated set."
-
-Per-cell descriptions then go in. For character families, an additional rule: *"All cells depict the SAME individual: identical body shape, identical clothing colors, identical hair, identical proportions. Only the facing direction changes."*
-
-### Why deterministic-first ordering matters
-
-Putting deterministic checks **before** the Gemini review changes the cost shape entirely:
-
-- Old loop (per-tile): every retry burned a Gemini review call to discover failure.
-- New loop (family): a failing family fails the deterministic gate for free, and the failure produces a *numeric* fix-hint ("CV 0.67 > 0.35, make characters same height") that's far more actionable than prose critique.
-
-Gemini becomes a polish check, not a failure detector. On the player_character run, Gemini was called once. Old per-tile equivalent would have been 4–24 review calls.
-
-### Anchor refinement (failure recovery)
-
-The orchestrator's tier 5 (`t5_anchor_refine`) is the recovery move when the first attempt has *one* good cell but family coherence fails:
-
-1. After every attempt, `family_checks.find_anchor_member()` picks the member whose silhouette + palette is most representative of the family.
-2. That member's PNG is saved as `iterations/_families/<id>/_anchor.png`.
-3. On the next attempt, `t5_anchor_refine` passes the anchor as a reference image to nano-banana, with the prompt: *"The first attached image is the locked anchor. Every cell must match the anchor's clothing colors, hair, body proportions, and palette. Only the facing direction changes."*
-
-In the player run this never fired (first attempt passed). It exists as the recovery path for harder families.
-
-### Thresholds: per-family, not global
-
-`families.json` has a top-level `defaults` block (currently 9.0/7.0 with default deterministic thresholds) and per-family overrides. Why per-family:
-
-- A character family tolerates more palette variation than a ground-tile family (different shading per facing is expected).
-- A ground-tile family must self-seam tightly (column 0 ≈ column 31), but characters have no self-seam concept at all.
-- A path autotile must satisfy edge contracts that don't apply to characters.
-
-Override only what differs. Inherited keys flow from `defaults.deterministic_thresholds` to the family.
-
-### Phase 1 calibration: lower threshold to bootstrap, ramp later
-
-For player_character we set `pass_threshold: 7.0`, `min_individual: 5.0` to get to a first pass cheaply and validate the architecture. The actual run scored 8.6 then 9.0 — well above the 7.0 bar, suggesting the architecture had more headroom than the lowered bar required. **Operating rule: leave the threshold at 7.0 until enough families have run that we have data on real ceiling.** Ramping prematurely just creates noise.
-
-### Family-pipeline pitfalls observed
-
-- **`.env.local` does not propagate to git worktrees.** It's gitignored, lives only in the worktree where it was created. When working in a new worktree, copy it from a sibling worktree before running anything that touches the Google API.
-- **The Gemini reviewer can be flattering when the deterministic block tells it everything passed.** Stay vigilant: read at least one Gemini critique JSON per session to confirm the prose tracks the numbers.
-- **Cell magenta-keying still has occasional residue** at the seam between sprite and the cell's magenta border. Same fix as the per-tile pipeline: ensure the model's magenta is pure (no shading, no dithering on the magenta) and trust the post-process keying.
-- **Sheet aspect ratio matters.** A 2×2 layout produces a square output (good — both Imagen and Nano Banana prefer 1:1). A 1×4 layout produces 4:1, which Imagen's `aspect` parameter supports but Nano Banana's wrapper does not control. Prefer 2×2 over 1×4 for 4-member families until that's resolved.
-
-### When to migrate an existing tile into a family
-
-The old per-tile pipeline still works for the 22 non-character tiles. We migrate when:
-1. The existing per-tile output is unsatisfactory (e.g., the four player frames).
-2. The tile has natural siblings (transitions, autotiles, multi-tile objects, character spritesheets).
-3. We're rebuilding the area for some other reason and might as well do it right.
-
-Otherwise leave existing tiles alone — they're published and working.
-
----
-
-## Stress test (Phase 1.5) — 8 families, three generation patterns
-
-After the player_character family validated the architecture for one pattern, we ran a stress test against 8 families spanning every shape of family we could think of: characters, transitions, multi-tile objects, paths, cliffs, houses, boats, coastlines. Round 1 surfaced an architecture gap; Round 2 fixed the prompt strategy; Round 3 fixed the check dispatch. Final result: 7 of 8 families pass, with the 8th failing on a real subjective style judgment (not architecture).
-
-Total stress-test cost: **$1.44 of $80**. Three rounds, ~30 image-gen calls, ~20 Gemini reviews.
-
-### The three patterns (this is what we learned)
-
-What initially looked like one architecture is actually **three**. Each needs different prompt language and different check dispatch.
-
-#### Pattern A — coordinated variants
-Each cell is a different *view of one concept*. Cells never sit adjacent in-game — different cells get placed at different world locations. Coherence = identity (same character, same boundary style, same foam color).
-
-Examples: `player_character` (4 facings), `vendor_hyperion` (1 pose), `transition_grass_sand` (4 directional boundaries), `coastline_sand_sea` (4 directional shorelines), `small_boat` (1 sprite).
-
-- Prompt: describe each cell separately with strong cross-cell coherence rules ("identical clothing, identical hair, identical foam color across all cells").
-- Deterministic checks that apply: cross-cell color coherence (palette Jaccard, dominant overlap, luminance EMD) + sprite silhouette CV for character kinds.
-- Edge contracts: do NOT apply (cells aren't placed adjacent in-game).
-- Gemini family-review: judges identity coherence + style match.
-
-#### Pattern B — continuous illustration
-The family is **one object** drawn as a single illustration that we slice on a virtual grid afterward. The model is NOT told about cells at all. Cells are different *parts of one drawing*; their palettes are *naturally* different (a roof and a foundation are different colors, by design).
-
-Examples: `container` (one shipping container in 4 cells), `small_house` (one Mediterranean dwelling in 9 cells), `cliff_face` (one cliff in 3 cells, vertically).
-
-- Prompt: describe the whole subject as a single illustration filling the image edge-to-edge. Explicitly forbid "cell borders, panel separators, frames, grid lines." Tell the model: *"the image will be sliced afterward, but you do not need to think about that."*
-- Deterministic checks that apply: only per-cell post-processing (palette quantize, dimensions, AA). NO cross-cell coherence (false negatives — different parts have different palettes by design). NO edge contracts (tautological — the slicer guarantees adjacency by construction).
-- Gemini family-review: judges whether the assembled illustration reads as one coherent thing AND matches the project style.
-
-#### Pattern C — true autotile family (not yet validated)
-A set of tiles where each cell is a different *topology* (NW corner, straight, T-junction, cross, etc.) that must connect cleanly at specific edges. Pattern A doesn't work (the model can't keep the path width identical across separate variant generations). Pattern B doesn't work either — the path autotile we tried produced a "border tile set" (square frame with no interior cross) when the model drew it as one continuous loop, which is not the same as a 9-topology autotile.
-
-Best evidence: `path_autotile` under continuous_illustration produced usable tiles for paths-along-borders but lost the four-way cross that a full autotile needs.
-
-**Pattern C likely requires a third strategy not yet built**: cell-by-cell generation with the previously-generated cell's edge as an image-conditioning reference. This is the academic "Wang tile" / image-conditioning approach. We have not yet implemented it. **Open architectural question.**
-
-### How to set the strategy
-
-`families.json` field: `slice_strategy`. Values:
-
-```json
-"slice_strategy": "coordinated_variants"   // Pattern A (default if absent)
-"slice_strategy": "continuous_illustration" // Pattern B
-```
-
-Per-strategy required fields:
-- Pattern A: per-member `desc` describing each cell.
-- Pattern B: top-level `continuous_description` describing the whole subject as one illustration. Per-member `desc` becomes a label-only field used for the slice filename.
-
-### What was wrong with our first attempt
-
-Round 1 used Pattern A's prompt for everything. For continuous-object families this was wrong because:
-- The model interpreted "grid of cells" as a sprite-sheet brief and drew **black panel borders between every cell**, even when explicitly told "no border between cells."
-- Each cell was treated as an independent painting, so palette and lighting drifted dramatically (e.g. a 3×3 house had 3 different palettes, one per row, with luminance EMD = 84).
-- Edge contracts measured 0–50% match.
-
-Round 2 fixed the prompt strategy. Edge contracts immediately jumped (some hit 100%). Round 3 fixed the check dispatch (skip cross-cell + edge contracts for Pattern B). All four continuous-illustration families passed Gemini review.
-
-### Round-by-round measurements (durable record)
-
-| Family | Pattern | R1 result | R2 result | R3 result | Final Gemini |
-|---|---|---|---|---|---|
-| vendor_hyperion | A (singleton) | ✅ pass | — | — | 8.0 |
-| transition_grass_sand | A (variants) | ✅ pass | — | — | 9.0 |
-| small_boat | A (singleton) | ✅ pass | — | — | 9.25 |
-| coastline_sand_sea | A (variants) | ❌ palette/dominant fail | ✅ pass (tightened anchor) | — | 8.5 |
-| container | B (continuous) | ❌ edge 9–50% | partial (50–100%) | ✅ pass | 8.25 |
-| small_house | B (continuous) | ❌ all 15 checks fail | worse (luminance EMD 116) | ✅ pass | 8.5 |
-| cliff_face | B (continuous) | ❌ edge 0–25% | ❌ edge 0–60% | ⚠️ style fail (Gemini 6.25 — "too painterly, not FireRed enough") | 6.25 |
-| path_autotile | B (continuous) | ❌ edge 0–50% | partial (50–90%) | ✅ pass (as border tile set, not full autotile) | 8.0 |
-
-### Insights worth keeping
-
-1. **Different patterns need different prompt language AND different check dispatch.** Conflating them makes the architecture appear broken when only the prompt strategy is wrong.
-
-2. **The model can draw beautiful single illustrations** when not constrained to a "grid of cells" brief. Round 2's container, house, cliff, and path images were genuinely good art — the original problem was framing.
-
-3. **Edge contracts are a Pattern-A concept misapplied to Pattern B.** For continuous illustrations, the slicer guarantees adjacency by construction. Checking pixel-match at slice lines is meaningless and misleading.
-
-4. **Cross-cell color coherence is a Pattern-A concept.** For continuous illustrations, different parts naturally have different palettes (roof ≠ foundation, sky ≠ ground). The check correctly flagged this as "incoherent" but in fact it was a feature, not a bug.
-
-5. **Gemini's right role is subjective polish, not failure detection.** When the deterministic gate is appropriately scoped, Gemini reliably catches subjective style problems (cliff_face's "too painterly, blended transitions instead of hard pixel edges" was a real, useful critique). When the deterministic gate is wrongly scoped, Gemini calls get wasted on false positives.
-
-6. **The fix from 4/8 to 7/8 was small.** Two contained changes: (a) add a `slice_strategy` field with a new prompt builder branch; (b) skip cross-cell + edge-contract checks for `continuous_illustration` in `family_checks.run_all()`. About 60 lines of Python plus the schema field. The architecture core (family schema, generator pipeline, retry logic, Gemini review prompt) was unchanged.
-
-7. **Stress-testing surfaces gaps cheaply.** Each round was ~$0.50. The full 3-round stress test cost ~$1.44 to identify and validate fixes for an architectural assumption that would have shipped silently broken if we'd kept moving on player_character → vendor → next-family.
-
-### Open questions surfaced (not yet resolved)
-
-- **Pattern C strategy (true autotile families).** Path autotile under Pattern B produced a usable border-tile set but lost the topology variants a full autotile needs. Solution likely involves cell-by-cell generation with image-conditioning anchors. Defer until V1 actually needs an autotile path.
-- **Cliff style failure.** Gemini consistently scored cliff at 6.25 across attempts, citing "too painterly, soft transitions, blended dithering." The model produces beautiful illustrations but they don't match FireRed's hard-pixel-edge discipline. Possible fixes: (a) tighter style-specific prompt for vertical structures, (b) post-processing to flatten dithering, (c) accept that cliff is a V2 problem. Not yet decided.
-- **"Object-as-asset" vs "object-as-tile-set" question.** Pattern B continuous illustrations might be better used as a single sprite asset placed across multiple grid cells in-game, rather than as 4 / 9 independent tiles. Either model works visually; the choice is about the game-engine integration. **Defer to whenever we're ready to place a multi-tile object in the world map.**
-
-### Pattern B operational rule
-
-When adding a new continuous-illustration family:
-
-1. Set `slice_strategy: "continuous_illustration"`.
-2. Provide a top-level `continuous_description` describing the whole subject as ONE illustration. Use language like *"filling the entire image edge-to-edge,"* *"NO cell borders,"* *"the image will be sliced afterward."*
-3. Pick a layout that matches the natural orientation (e.g. 3×1 for a vertical cliff, 3×3 for a building front, 2×2 for a square object).
-4. Per-member `desc` becomes label-only — describe what each slice will contain post-hoc, but don't expect the model to read these.
-5. Don't define `edge_contracts` — they're skipped anyway.
-6. Trust the slicer + Gemini family-review.
-
----
-
-## Pattern C — autotile families (Phase A–D)
-
-For a region of one terrain surrounded by another (grass islands in sand, sand
-beaches against sea) and for line/path topology (marble flagstones threading
-through grass), neither Pattern A nor Pattern B works. We hit this in stress
-testing: the path autotile under Pattern B produced a usable border tile set
-but lost the topology variants a real autotile needs. The model is good at
-texture appearance; it is not good at producing all the topology variants of
-a tile set as one image.
-
-The fix: **AI generates 3–5 small primitive textures; a pure-Python compositor
-deterministically composes the 47 (or 16) tiles by per-quadrant masking.**
-Standards-compliant: 47-blob (RPG Maker A2 / Tiled / Cr31 / Godot blob) for
-region terrain, 16-path (4-cardinal) for line terrain. For decision rationale
-see [ADR 0009](../adr/0009-autotile-architecture.md).
-
-### Why this works
-
-**Edges match by construction.** Every tile that has the same edge configuration
-samples its boundary pixels from the same primitive at the same logical
-position. So when two such tiles sit next to each other in the world, the seam
-pixels are guaranteed identical to within bounded jitter. We didn't need a
-retry loop for seam alignment — the compositor produces correct seams on the
-first pass. Validated by 100% edge-match on the all-interior composition test.
-
-**The model only does what it's good at.** The AI generates 3–5 small texture
-chunks (interior, exterior, edge, concave-corner, convex-corner). These are
-within the model's competence — they're each a small piece of a coherent
-texture. The model is not asked to plan tile-set topology, which is what
-breaks down.
-
-**Cost is dramatically lower.** A 47-tile family from 5 primitive generations
-is ~$0.20–0.45 vs ~$1.88 if every tile were generated independently. Per
-final tile this is ~$0.005–0.010 vs ~$0.040 — about 4–8× cheaper.
-
-### Recipe: building a region autotile family (47-blob)
-
-1. **Define the family** in `modules/art-pipeline/template/families.json` with
-   `kind: "autotile_blob_47"`. Required fields: `interior_terrain`,
-   `exterior_terrain`, `interior_short`, `exterior_short`, `shared_style`,
-   and a `primitives` array of 5 entries with roles
-   `interior` / `exterior` / `patch_horiz_NW` / `patch_concave_NW` /
-   `patch_convex_NW`. Each primitive has its own `id`, `desc`, and `size_px`
-   (32 for interior/exterior textures, 16 for boundary patches).
-2. **Run the orchestrator**:
-   `python3 modules/art-pipeline/pipeline/autotile_orchestrator.py <family_id>`.
-3. The orchestrator generates each primitive with retries (up to 3 attempts
-   for texture-role primitives, 1 attempt for non-texture primitives), applies
-   seamless-enforcement to texture roles, calls
-   `autotile_compositor.compose_blob47()`, and saves all 47 tiles.
-4. The validation harness renders three test compositions (all-interior,
-   island, organic) and reports edge-match scores.
-
-### Recipe: building a path autotile family (16-path)
-
-Same as region but with `kind: "autotile_path_16"` and a 3-primitive bundle:
-`terrain` / `path_node` / `path_arm_N`. The path_arm_N primitive is anchored
-at the top edge with the path running vertically; the compositor rotates it
-for the other 3 cardinal directions.
-
-### Recipe: seamless texture enforcement (the trick that made it work)
-
-AI-generated textures don't naturally tile seamlessly — col 0 ≠ col 31 in the
-raw output. The seamless-enforcement step in
-`autotile_orchestrator._make_seamless()` averages the leftmost and rightmost
-columns of pixels, applies the average to both columns, repeats for top/bottom
-rows, then re-quantizes to the locked palette. Result: col 0 == col 31 and row
-0 == row 31 by construction. The visible cost: the 4 outermost pixels of every
-edge are slightly blended versions of opposite-edge content. For texture-style
-primitives (grass, sand, sea) this is invisible.
-
-Without this step, even a "seamless" prompt produces ~50–70% edge match in
-all-interior compositions. With the step, 100%.
-
-### Why we still split silhouette / color / luminance / edge-contracts
-
-The deterministic-checks framework (Pattern A/B) doesn't apply to autotiles:
-- Cross-cell color coherence: primitives are independent; we don't compare them.
-- Edge contracts: tautological for autotiles (the compositor produces matching
-  edges by construction).
-
-The autotile validation harness uses a different scoring metric: **edge-match
-score on rendered test compositions**. For each adjacent tile pair in a
-rendered composition, count how many seam pixels match within a perceptual
-tolerance. 100% means the composition is seamless when displayed.
-
-### Pattern C results — Phase B/C run
-
-| Family | Primitives | all_interior | island | organic / winding | cost |
-|---|---|---|---|---|---|
-| grass_on_sand | 5 | 100.0% | 85.7% | 77.2% | $0.47 |
-| sand_on_sea | 5 | 100.0% | 85.7% | 74.7% | $0.23 |
-| marble_path | 3 | n/a | n/a | winding 99.2% / cross 99.1% | $0.16 |
-| cliff_top | 5 | 100.0% | 86.2% | 74.7% | $0.27 |
-
-**100% match on all-interior compositions** validates the seamless-tile
-approach. The 75–86% scores on boundary compositions (island, organic) reflect
-the boundary primitives being independently generated — they're stylistically
-coherent but not pixel-identical at every transition. Acceptable for V1;
-generating boundary primitives in pairs with image conditioning would close
-this gap and is a V2 candidate.
-
-The marble_path 99% score is dramatically higher because path tiles are stamps
-on a uniform background — most seams are terrain-to-terrain (perfectly
-tileable), only a few are path-to-terrain.
-
-### Pattern C pitfalls observed
-
-- **Direction-asymmetric terrain breaks 47-blob.** Cliffs need different tiles
-  for north-facing vs south-facing edges (the south edge shows a stone face;
-  the north edge is just grass). 47-blob produces the same edge tile on all
-  four sides of a cliff region. Result: cliff_top is topologically correct
-  but stylistically weak. **For real cliffs, V1+ needs a direction-aware
-  cliff scheme** (per-edge tile selection or a 4-orientation autotile
-  variant). Document and defer.
-- **Per-tile interior repetition.** Without per-tile sample-offset jitter,
-  every interior tile looks identical. Visible in large interior fields.
-  Phase A–D ships without jitter; V2 candidate.
-- **Triple junctions are unrepresentable.** Where 3 terrains meet at one
-  tile, the 47-blob convention can't pick a tile. Forbid triple junctions
-  in level design (this is the standard solution in the industry).
-- **Two-way terrain pairs need two families.** `grass_on_sand` does not
-  serve `sand_on_grass` — the boundary direction matters. For V1, declare
-  the families you need.
-
-### Runtime architecture
-
-The autotile picker is split-implementation:
-- `modules/art-pipeline/pipeline/autotile_mapping.py` — Python source of truth, used by the
-  compositor at build time.
-- `public/game/world/autotile.js` — JavaScript mirror, used by the in-game
-  renderer. Cross-verified against the Python table at build time (a
-  smoke-test compares all 256 inputs).
-
-When the runtime data-model refactor lands (Phase D, deferred for review):
-the world map stores terrain ids per cell; the renderer iterates cells and
-calls `selectBlob47(myTerrain, neighbors)` or `selectPath16(neighbors)` to
-pick the tile index, then loads the corresponding PNG from the family's
-tile set.
-
-### Open question
-
-**Cliffs deserve a direction-aware scheme.** The 47-blob approach gives a
-stylized "shelf" look on all four edges of a cliff region. Real cliff
-autotiles in RPG Maker (A4 layer) and similar systems use a strip-based
-scheme where the south-facing edge is drawn as a vertical wall while other
-edges are flat transitions. If V1 ships cliffs, this needs to be built.
-Otherwise defer to V2. Decision pending Lars.

package/docs/recipes/staging-data.md

@@ -1,50 +0,0 @@
-# Staging data — what's real, what's faked
-
-> **Seeded by** [`scripts/gds/seed-staging.sh`](../../scripts/gds/seed-staging.sh) (V3.R41 / [#262](https://example.com/builders#/task/262)).
-> Staging DB: `example_staging` on the droplet. Staging is the controlled mirror used for red-team ([#272](https://example.com/builders#/task/272) parallel-load, future C9 work) — **never** a place to trust as a record of truth.
-
-## How seeding works
-
-`seed-staging.sh` runs **on the droplet** (both databases are local, peer auth as `lars`). It takes a **full `pg_dump` of production (schema + data)**, drops and recreates the staging `public` schema, restores the dump, then anonymizes.
-
-Why a full dump (not data-only): prod has a circular / self-referential FK (`tasks.parent_task_id`). A full dump adds all FK constraints **after** loading the rows, so that restores cleanly — and staging inherits prod's **exact schema**, so **no separate `migrate.sh` step is needed**. (A fresh `migrate.sh` from an empty DB would also fail: migration 021 is a *data* migration that assumes prod state.)
-
-```bash
-# On the droplet:
-bash scripts/gds/seed-staging.sh
-
-# Or from a laptop in one shot:
-ssh lars@<droplet> 'bash -s' < scripts/gds/seed-staging.sh
-```
-
-Re-runnable any time; each run replaces staging's data wholesale.
-
-## What's REAL (copied verbatim from prod)
-
-The structure and content of the work-tracking graph, so staging behaves like the real system:
-
-- **tasks, claims, versions, dependencies, done_when_criteria, task_criteria** — real titles, descriptions, statuses, ranks, links.
-- **cost_log, credit_log, learnings, idea_inbox, grades, achievements** — real rows.
-- **builder_memory** — real per-builder memory content (builder-authored project notes; internal, not personal data).
-
-These are *project* data (what the team built), not end-user data. Staging lives on the same access-controlled droplet as prod.
-
-## What's FAKED / removed (the anonymization step)
-
-- **Builder identity is anonymized.** Every `builders` row gets `github_login = builder-<id>`, `display_name = Builder <id>`, `github_id = 900000<id>`, `avatar_url = NULL`. No real GitHub handle survives on staging.
-- **All sessions are purged.** After the restore, the script nulls every column that references `builder_sessions` and then `DELETE`s every session row, so the seeded DB ends with **zero** sessions and **no real bearer token**. Mint a staging-only token directly (insert a row into `example_staging.builder_sessions`) when a test needs to authenticate — note the auth regex only accepts `[A-Za-z0-9]+`, so the token must be alphanumeric (no hyphens).
-
-### Honest note on the restore window (not a zero-trust guarantee)
-
-Because it's a *full* dump, real session rows **are** loaded during the restore and only deleted a moment later in the anonymize step — so for the brief restore→purge window (~1s) real bearer tokens transiently exist in the staging DB, and the temporary dump file under `/tmp` (mode `0600`, shredded on normal exit) holds real `github_login` values until cleanup. This is acceptable because staging is the **same trust domain** as prod (one access-controlled droplet, peer auth) — but it is **not** a "real tokens never touch staging" guarantee. If you need that guarantee (e.g. seeding onto a less-trusted host), revoke prod sessions first or seed during a maintenance window. The end state after a successful run is always zero sessions.
-
-## Reseeding cadence
-
-Re-run on demand (before a red-team / load-test session) or on a weekly cron. To install the weekly cron on the droplet:
-
-```bash
-# 03:30 every Monday — refresh staging from prod.
-( crontab -l 2>/dev/null; echo "30 3 * * 1 bash /home/lars/example-staging/scripts/gds/seed-staging.sh >> /home/lars/seed-staging.log 2>&1" ) | crontab -
-```
-
-(On-demand is the common case; the cron is optional convenience. The staging checkout must be on current `main` so it has the latest schema — `git pull` it before a manual seed if prod's schema has moved. Until the cron is installed, treat staging data as a point-in-time snapshot from the last manual seed.)