@@ -8,7 +8,7 @@
 meta:
   id: eggs
   status: design
-  built: []
+  built: [band_code, egg_renderer, egg_reader, measured_band_height]
   not_built: [egg_object, menu_tree_compile, selection_accumulator, hatch_semantics, resume_point, recall]
   see_also: [OPTICAL-CHANNEL.yml, ANGEL-EVENT-BUS.yml, RECORDER.yml, modules/soul-angel/OUT-OF-GAME-JOBS.yml, modules/soul-angel/UNIVERSAL-JOBS.yml]
   upstream: "moollm skills/soul-city/GLOSSARY.md (Egg, Errand) and skills/soul-city/SOUL-BRIDGES.md (The errand)"
@@ -224,6 +224,14 @@ the_blip_editor:
   legible_to_both_readers: "A player learns 'gold cap band means news' in one session, and the reader decodes the same stripes numerically. One artifact, two audiences, which is the property the whole optical channel rests on (OPTICAL-CHANNEL.yml, the_player_reads_it_too)."
   authored_once: "Shape, bands, caps, palettes, states and the DGRP table are emitted by the same compile that emits the menu tree and the verb registry (compiled_from_one_source)."
 
+  the_numbers_are_measured_now:
+    where: "packages/optical-codec — egg-render.ts draws them, egg-read.ts reads them, scripts/measure-eggs.ts sweeps band height against the degradation suite, and ../RECOGNIZER.yml, the_egg_reader has the full grid."
+    a_band_is_six_pixels: "Six device pixels a band reads twelve colours through everything in the suite: a window at a third scale, soft focus, a warm noisy phone grab, a tilted one. Five is enough for all but the smallest window. That is the number the art has to hit at the zoom where a code is meant to be read, and it is a drawing requirement, not a hope."
+    the_caps_earn_their_place: "Everything the section above claimed for them holds up under measurement, and two of the three turned out to be load-bearing in a way that was easy to underrate. A cap is exactly one band tall, so the reader derives the band height from the picture instead of being told it — an egg is self-describing at any zoom or capture scale. And correcting the bands by the sampled cap colours means an evening-light frame reads exactly as well as a clean one, which is the single best cell in the grid."
+    what_the_bands_may_not_be: "A colour whose luma is near either cap's gets read AS a cap, and then the egg is not misread, it is invisible. So the palette is bounded away from both — luma 72 to 188 — and the palettes are packed by a script that maximises the smallest gap under that bound rather than chosen by eye (src/egg-code.ts)."
+    twelve_is_legible_and_eight_is_shipped: "The measurement says twelve colours a band survives the suite. The default is octal anyway: the suite is synthetic and the game's own rendering is not in it, and an octal band is the same symbol as a dialled compass point (cracking_it_like_a_safe). The version band is the second thing on the stack precisely so this can change later."
+    what_is_still_not_known: "Whether any of it survives the game actually drawing an egg. Nothing here has been checked against a frame the game produced, because there is no egg in the game yet."
+
 # WHAT AN EGG IS, IN OTHER PEOPLE'S VOCABULARIES
 #
 # Several fields already named this object. Each name is worth having because each one carries an
 
@@ -8,8 +8,8 @@
 # MOBILE-CAMERA.yml (the hard optical path) · RECORDER.yml (where frames come from)
 
 status:
-  built: [codec_package, qr_path, synthetic_scene_renderer, egg_renderer, abuse_suite_minus_jpeg, recognize_scan_verb]
-  not_built: [frame_source, gpu_prefilter, egg_path, worker_pool, overlay_debug_view]
+  built: [codec_package, qr_path, synthetic_scene_renderer, egg_renderer, egg_reader, band_alphabets, abuse_suite_minus_jpeg, recognize_scan_verb, coverage_font_reader, anchor_matcher]
+  not_built: [frame_source, egg_path_in_the_verb, gpu_prefilter, worker_pool, overlay_debug_view, verification_against_a_real_frame]
   decided: [zxing_for_qr, local_only_no_remote_model, codec_first_in_node]
   where: "packages/optical-codec (codec, renderer, fixtures, tests) · src/main/recognize/service.ts (the verb)"
 
@@ -130,11 +130,33 @@ measured_legibility:
   what_it_decides: "How big the About dialog draws its code, and what to say to anyone who wants it smaller."
 
 the_eggs_are_drawn_before_the_game_draws_them:
-  what: "packages/optical-codec renders eggs into synthetic frames — caps, calibration swatches, bands, segments, levitation, glow — and reports the ground-truth box and digits for each one."
+  what: "packages/optical-codec renders eggs into synthetic frames — caps, bands, segments, levitation, glow — and reports the ground-truth box and digits for each one."
   why_not_wait_for_screenshots: "There are no eggs in The Sims yet, so there is nothing to photograph. Generating the frame gives the reader targets today and stays useful afterwards: a real capture tells you whether it works, a synthetic frame tells you which pixel broke it."
   the_test_that_matters: "The bands are pixel-identical lit and dark. The glow draws behind the body, so the cosmetic layer cannot reach the pixels the reader samples — which is the rule above, enforced rather than asserted."
 
+the_egg_reader:
+  where: "packages/optical-codec/src/egg-read.ts, swept by scripts/measure-eggs.ts."
+  how_it_finds_one: "Column by column: the brightest and darkest runs in a column are candidate caps, and a candidate survives only if the distance between their centres divides evenly by a band height that also explains the colour changes between them. Then adjacent columns that agree are grouped, and a group narrower than a band is tall is thrown away."
+  the_caps_do_three_jobs: "They delimit the stack, they set the scale — a cap is exactly one band tall, so the metric comes out of the picture rather than out of a config file — and they are the white and black reference for an affine colour correction. A sunset shifts the bands and the caps by the same amount, and correcting by the caps removes it before a single digit is decided."
+  it_refuses_rather_than_guesses: "Every band reports the distance to the runner-up colour. The smallest of those is the reading's confidence, and a reading below the floor is returned as refused WITH its digits, so a caller can see what was nearly there. A failed check digit is refused the same way."
+  the_measured_floor: "SIX PIXELS A BAND reads twelve colours through every degradation in the suite. Five reads twelve through all but a window at a third scale. Below four, only a clean or evenly-dimmed grab reads at all."
+  the_grid:
+    clean_screen_grab: "2px and up, twelve colours."
+    evening_light: "2px and up. A global dim costs nothing, because the caps dim with the bands and the correction is affine."
+    window_at_50_percent: "4px and up."
+    window_at_33_percent: "6px and up."
+    soft_focus: "5px and up."
+    phone_noise_and_warm_cast: "2px and up, once the frame is median-filtered across the width."
+    phone_noisy_and_soft: "5px and up."
+    phone_tilted: "4px and up."
+  two_findings_worth_keeping:
+    noise_invents_boundaries: "Finding the band count from colour changes works and then stops working the moment there is grain, because every row becomes a change. A band is one colour all the way across, so a median of five neighbours across the width removes it and cannot move a horizontal boundary. Without that filter every noisy cell in the sweep read nothing at all."
+    a_band_can_be_mistaken_for_a_cap: "The reader looks for the caps as the extremes of a column's range and claims the top and bottom 15% of it, so a dark band inside that claim becomes a black cap and the whole egg vanishes — not misread, not refused, invisible. Seven of sixteen codes were being lost this way. The fix is a bound on the palette, not on the reader: bands live between luma 72 and 188 (src/egg-code.ts)."
+  what_the_alphabet_is_set_to: "Octal, with twelve measured as legible. The headroom is spent on margin rather than on digits: the sweep is synthetic, the game's own rendering is not in it, and an octal band is the same symbol as a dialled compass digit (EGGS.yml, cracking_it_like_a_safe)."
+  still_only_pixels_we_drew: "Same caveat as the QR numbers. tools/verify-frame.ts is the thing that turns this from a floor into a fact, and it needs one real frame."
+
 open_items:
   packaging_the_wasm: "The Node path finds the wasm inside node_modules by walking up from an exported entry point. A packaged app needs those two files unpacked from the asar and resolved from resources instead."
   jpeg_in_the_abuse_suite: "Needs a real DCT and quantisation table. Standing in for it with blur plus noise would let us claim a pass we had not earned."
-  the_palette_is_provisional: "Ten separated RGB values, chosen against theory. The spec requires choosing them against the game's rendered output, and that has not happened."
+  the_palette_is_provisional: "The palettes are packed rather than picked — scripts/pick-palettes.ts maximises the smallest gap between colours, under a distance from the caps and a luma window. What is settled is HOW MANY colours a band can hold and how far apart they have to be. Choosing them against the game's own rendered output has not happened, and the sweep cannot do it."
+  the_egg_field_is_still_empty: "The reader exists in the codec and the verb still returns an empty array. Wiring is small; doing it before there is a frame to verify against would mean shipping a path nobody has seen work."
@@ -0,0 +1,103 @@
+/**
+ * How many colours can a band carry, and how few pixels tall can a band be?
+ *
+ * The spec said "ten to twelve maximally separated colours, chosen against the game's actual rendered
+ * output rather than against theory". This is the theory-free half: sweep every alphabet against every
+ * band height under every degradation, and let the grid say which pairs survive. The remaining half
+ * needs a real screenshot of the real sprites, and no amount of this substitutes for it.
+ *
+ * A cell passes only if EVERY code in the sample decodes exactly. One misread in twenty is not a
+ * legible cell — it is a cell that will be wrong in front of a player.
+ *
+ *   pnpm --filter @micropolis/optical-codec tsx scripts/measure-eggs.ts
+ */
+
+import { blur, noise, perspective, roundTrip, tint } from '../src/degrade';
+import { ALPHABETS, fieldLimits, separation, type BandAlphabet, type EggCode } from '../src/egg-code';
+import { readEggs } from '../src/egg-read';
+import { drawEgg } from '../src/egg-render';
+import { createRaster, fillRect, type Raster } from '../src/raster';
+
+const BAND_HEIGHTS = [2, 3, 4, 5, 6, 8];
+const SAMPLE = 16;
+
+const conditions: { name: string; apply: (r: Raster) => Raster }[] = [
+	{ name: 'clean screen grab', apply: (r) => r },
+	{ name: 'window at 50%', apply: (r) => roundTrip(r, 0.5) },
+	{ name: 'window at 33%', apply: (r) => roundTrip(r, 0.34) },
+	{ name: 'soft focus', apply: (r) => blur(r, 1) },
+	{ name: 'evening light', apply: (r) => tint(r, [0.62, 0.7, 1.05]) },
+	{ name: 'phone: noise + warm cast', apply: (r) => noise(tint(r, [1.1, 1, 0.82]), 18) },
+	{ name: 'phone: noisy and soft', apply: (r) => noise(blur(r, 1), 12) },
+	{
+		name: 'phone: tilted',
+		apply: (r) =>
+			perspective(r, {
+				tl: [8, 4],
+				tr: [r.width - 3, 13],
+				br: [r.width - 10, r.height - 6],
+				bl: [3, r.height - 12]
+			})
+	}
+];
+
+/** A deterministic spread of codes, so a failing cell can be reproduced exactly. */
+function codes(alphabet: BandAlphabet): EggCode[] {
+	const base = alphabet.colours.length;
+	const limits = fieldLimits(alphabet);
+	const out: EggCode[] = [];
+	let state = 20260917;
+	// High bits, not low. An LCG's low bits barely move, and `state % base` on a small base returned
+	// the same digit sixteen times — a sample of one code wearing a sample of sixteen's clothes.
+	const next = (n: number): number => {
+		state = (state * 1103515245 + 12345) & 0x7fffffff;
+		return Math.floor((state / 0x80000000) * n);
+	};
+	for (let i = 0; i < SAMPLE; i++) {
+		out.push({ kind: next(base), version: 1 % base, id: next(limits.id + 1), value: next(limits.value + 1) });
+	}
+	return out;
+}
+
+/** One egg on a floor, with the room furniture the reader has to ignore. */
+function scene(code: EggCode, alphabet: BandAlphabet, bandHeight: number): Raster {
+	const radius = Math.max(4, Math.round(bandHeight * 1.6));
+	const width = radius * 6;
+	const height = bandHeight * 12 + 24;
+	const frame = createRaster(width, height, [92, 84, 72]);
+	fillRect(frame, 0, 0, width, Math.round(height * 0.35), [64, 72, 96]);
+	drawEgg(frame, code, { x: Math.round(width / 2), y: height - 8 }, { alphabet, bandHeight, radius, lit: 'steady' });
+	return frame;
+}
+
+function passes(alphabet: BandAlphabet, bandHeight: number, apply: (r: Raster) => Raster): boolean {
+	for (const code of codes(alphabet)) {
+		const frame = apply(scene(code, alphabet, bandHeight));
+		const readings = readEggs(frame, { alphabet });
+		const got = readings.find((r) => r.code !== null)?.code;
+		if (got === undefined) return false;
+		if (got.kind !== code.kind || got.version !== code.version || got.id !== code.id || got.value !== code.value) return false;
+	}
+	return true;
+}
+
+console.log(`${SAMPLE} codes a cell, all of which must decode exactly. Cell shows the largest alphabet that did.`);
+console.log('');
+console.log(`${'band height, pixels'.padEnd(28)}${BAND_HEIGHTS.map((h) => String(h).padStart(6)).join('')}`);
+
+for (const condition of conditions) {
+	const cells = BAND_HEIGHTS.map((bandHeight) => {
+		let largest = 0;
+		for (const alphabet of ALPHABETS) {
+			if (passes(alphabet, bandHeight, condition.apply)) largest = Math.max(largest, alphabet.colours.length);
+		}
+		return (largest === 0 ? '--' : String(largest)).padStart(6);
+	});
+	console.log(`${condition.name.padEnd(28)}${cells.join('')}`);
+}
+
+console.log('');
+console.log('closest pair in each alphabet, which is the noise budget a band lives inside:');
+for (const alphabet of ALPHABETS) {
+	console.log(`  ${alphabet.name.padEnd(12)} ${alphabet.colours.length} colours  ${separation(alphabet).toFixed(1)}`);
+}
@@ -0,0 +1,128 @@
+/**
+ * Choosing the band palettes, instead of picking colours that sound well separated.
+ *
+ * Hand-picked palettes had a defect the sweep exposed: octal and decimal came out with the SAME
+ * closest pair, because orange sits between red and yellow and both palettes held all three. An
+ * alphabet that buys two more digits per band for no loss in separation is not a trade-off, it is a
+ * sign the smaller alphabet was badly chosen — so the smaller ones are now farthest-point selections
+ * from a pool, and the ladder means something.
+ *
+ * The pool is constrained by what the READER needs, not by taste:
+ *
+ *   away from the caps    Nothing within 60 of white or black, which are the delimiters and the
+ *                         colour references. A band that looks like a cap destroys the structure the
+ *                         check digit is computed over.
+ *   inside the thresholds Luma between 72 and 188. The cap finder claims the top and bottom 15% of a
+ *                         column's range, so a band has to stay clear of both with margin to spare.
+ *                         Measured, not guessed: at 46 a dark blue band sat at 15.1% of the range and
+ *                         was read as a black cap, and seven of sixteen codes then failed to be found
+ *                         at all under blur plus noise.
+ *   saturated or grey     A colour has to be far from its neighbours after a colour cast, and the
+ *                         chromatic ones survive that best. One grey is allowed and is useful: it is
+ *                         far from every hue.
+ *
+ *   pnpm --filter @micropolis/optical-codec tsx scripts/pick-palettes.ts
+ */
+
+type RGB = [number, number, number];
+
+const CAP_MARGIN = 60;
+const LUMA_LOW = 72;
+const LUMA_HIGH = 188;
+
+const luma = (c: RGB): number => 0.299 * c[0] + 0.587 * c[1] + 0.114 * c[2];
+const dist = (a: RGB, b: RGB): number => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+
+/** Every colour on a coarse RGB lattice that a band is allowed to be. */
+function pool(): RGB[] {
+	const out: RGB[] = [];
+	for (let r = 0; r <= 255; r += 8) {
+		for (let g = 0; g <= 255; g += 8) {
+			for (let b = 0; b <= 255; b += 8) {
+				const c: RGB = [r, g, b];
+				const l = luma(c);
+				if (l < LUMA_LOW || l > LUMA_HIGH) continue;
+				if (dist(c, [255, 255, 255]) < CAP_MARGIN || dist(c, [0, 0, 0]) < CAP_MARGIN) continue;
+				out.push(c);
+			}
+		}
+	}
+	return out;
+}
+
+function minPair(set: RGB[]): number {
+	let worst = Number.POSITIVE_INFINITY;
+	for (let i = 0; i < set.length; i++) {
+		for (let j = i + 1; j < set.length; j++) worst = Math.min(worst, dist(set[i], set[j]));
+	}
+	return worst;
+}
+
+/**
+ * Farthest-point insertion, then hill-climb by swapping the member of the closest pair.
+ *
+ * Maximising the smallest gap in a set is a packing problem nobody solves exactly for this size. The
+ * greedy start plus swaps gets within a few units of the best known packings, and the number it
+ * reports is measured either way — which is all the sweep needs from it.
+ */
+function pick(candidates: RGB[], k: number, seed: RGB): RGB[] {
+	const chosen: RGB[] = [seed];
+	while (chosen.length < k) {
+		let best: RGB = candidates[0];
+		let bestGap = -1;
+		for (const c of candidates) {
+			const gap = Math.min(...chosen.map((s) => dist(c, s)));
+			if (gap > bestGap) {
+				bestGap = gap;
+				best = c;
+			}
+		}
+		chosen.push(best);
+	}
+
+	for (let round = 0; round < 400; round++) {
+		let improved = false;
+		for (let i = 0; i < chosen.length; i++) {
+			const without = chosen.filter((_, j) => j !== i);
+			let best = chosen[i];
+			let bestGap = Math.min(...without.map((s) => dist(chosen[i], s)));
+			for (const c of candidates) {
+				const gap = Math.min(...without.map((s) => dist(c, s)));
+				if (gap > bestGap) {
+					bestGap = gap;
+					best = c;
+				}
+			}
+			if (best !== chosen[i]) {
+				chosen[i] = best;
+				improved = true;
+			}
+		}
+		if (!improved) break;
+	}
+	return chosen;
+}
+
+/** Top to bottom by hue, so a person reading a stack sees a wheel rather than a scramble. */
+function byHue(set: RGB[]): RGB[] {
+	const hue = (c: RGB): number => {
+		const max = Math.max(...c);
+		const min = Math.min(...c);
+		if (max === min) return -1; // grey first, since it has no hue to sort by
+		const d = max - min;
+		const h = max === c[0] ? ((c[1] - c[2]) / d + 6) % 6 : max === c[1] ? (c[2] - c[0]) / d + 2 : (c[0] - c[1]) / d + 4;
+		return h * 60;
+	};
+	return [...set].sort((a, b) => hue(a) - hue(b));
+}
+
+const candidates = pool();
+console.log(`${candidates.length} colours in the pool: luma ${LUMA_LOW}-${LUMA_HIGH}, at least ${CAP_MARGIN} from either cap.`);
+console.log('');
+
+for (const k of [4, 6, 8, 10, 12]) {
+	const set = byHue(pick(candidates, k, [208, 48, 48]));
+	console.log(`${k} colours, closest pair ${minPair(set).toFixed(1)}:`);
+	for (const c of set) console.log(`\t\t[${c[0]}, ${c[1]}, ${c[2]}], // luma ${luma(c).toFixed(0)}`);
+	console.log('');
+}