Learn from play: design v2.4 (current policy)

Learn from play: design v2.4 (current policy)

This is the single current policy for learning from play. It replaces v2, the v2.1 working copy, v2.2 and v2.3. Older text and review provenance are in Appendix A ("Revision history"); they are history, not policy.

Requested by the operator on 2026-10-19 ("how can we use ANN to learn from the output of these games and be smarter over time"). Binding operator decisions: D48–D52 and D54 (maneet-games/master-mind/review-2026-10-15-platform/FINAL-PLATFORM-AND-IMPROVEMENTS.md, rows 48–52 and 54). Where this file and a decision row disagree, the decision row wins and this file is wrong.

0. Status (as of 2026-10-19)

Approved: Phases 1–2, shadow only (D50). Not approved: anything child-visible. Going live (Phase 3) needs a new operator decision plus the §6.1 evaluation protocol.

Built in the pilot (per the pilot report; in maneet-games/master-mind):

• games/_factory/learn.js, a standalone module. Whetstone is wired to it in shadow mode: the fixed ladder still picks every question.
• ci/l2-spotter.mjs and ci/l2-replay-sim.mjs (L2, builder-only). On replay the spotter flagged Whetstone identity 5/5, CMA std-form 5/5, CMA long float 5/5 and CMA prime parity 4/5, with 0 false flags. These are replays of known bugs with small counts, not a general detection rate.
• ci/learn-gates-test.mjs: 45/45 checks across G-L1..G-L8, against the test's own contract, which its header gives as "design v2.1 §8 + §12". It has no G-L7b. Its G-L1 passes on a realistic Whetstone payload and only logs the admitted-cap worst case without failing on it, so G-L1 as defined in v2.4 (§8) is not established.
• The shadow-equivalence digest (the child-visible run) is identical in all arms.
• The operator switch lives in device-only localStorage key mm-learn-op, bound to the player id and the player generation nonce. Operator identity comes from the hub owner check.
• The sealed holdout manifest is ci/learn-holdout-manifest.json (seal dcf9ddf9…b888).
• The built L1 state is per skill [rating×100, attempts, correct], with only the per-session bound (G-L7). The §4 mastery history and G-L7b are specified, not built.

Known gaps (open; none is hidden by this document):
1. The switch cannot be enabled from a child's own claude.ai account. That needs a hub-side or db-backed operator grant, which is a future decision (§10).
2. Storage-integrity limitation of Phase 2 shadow capture (§2.3, D49, D52). The privileged APIs (operatorEnable, operatorWipe) do check the hub owner. But routine start() trusts the mm-learn-op localStorage record once it is present, and any same-origin script can forge that record. A forged switch can start bounded shadow recording, and the recorded learn key then syncs to the hub cloud copy (§2.2). There is no child-visible effect. Resolving this is an operator choice (§2.3, §10).
3. Wipe is implemented for Whetstone only. Per the pilot report, Whetstone is also the only game wired to learn.js, so no other game holds learning state yet; this has not been independently re-verified. §2.3 makes it a precondition: no further game records until its namespace is in the wipe scope and passes G-L5.
4. Whetstone's pre-existing save caps (its own migrate caps: 200 skills, 400 facts, 200 pb) can produce a progress + .bak payload over 100,000 bytes. That is not caused by learning: such a save already falls back to device-only today. It does mean the v2.4 G-L1 gate, measured at the admitted caps, can fail for Whetstone until those caps are lowered or the claim is narrowed (§8).
5. The §4 mastery history, G-L7b and the §6.1 protocol do not exist yet. All three are Phase 3 entry conditions.
6. The built claims above come from the pilot report. The ANN reviews (seq 8495, 8504) did not audit code or run tests, and neither did this revision.
7. Test-contract drift. ci/learn-gates-test.mjs still identifies its contract as design v2.1, and it implements G-L1..G-L8 only. G-L7b is not counted as implemented until a test exists. The decision row D50 says "G-L1..G-L8 before any live step". This design adds G-L7b as a further condition and does not edit the D50 row.
8. Code TODO (not edited here): the operatorWipe comment in games/_factory/learn.js (:307) cites "§2.3 wipe" from v2.1. It should cite design v2.4 §2.3.

1. Goal

Each game should get better the more children play. The goal is not "more data"; it is three measurable things:

• children learn more, as measured on independent, held-out checks;
• bad content is caught earlier;
• AI judging is honest about uncertainty.

2. Ground rules

2.1 The model suggests; trusted code decides

• A learner returns only an opaque candidate ID or a bounded parameter.
• The caller checks that the ID is in an eligible set it built itself, then gets the content and the answer through the verified-maths module.
• Bot outputs are clamped to bounded ranges.
• The judge learner may only add abstention ("not sure"); it never changes a verdict or a score.
• Saved statistics and imported priors are untrusted input: they are schema-validated, and a failure means the default behaviour.

2.2 Where data lives (D48, D52)

• Sync is newest write per key wins, with no merge, within the 8 KB learning budget (§3).
• Same-origin boundary (D52). The first-party game iframe is same-origin with the hub and unsandboxed, so any game can read origin-wide localStorage, exactly like today's game saves. Key prefixes are a naming convention, not isolation. This design makes no per-game privacy claim. Mitigation is data minimisation: coarse skill ratings, counts and bounded session ages only, with no timestamps, no free text and no per-answer history beyond the bounded last-four outcomes per level in §4. Real isolation (an opaque-origin game sandbox plus a hub-owned storage broker) is planned separately in proposals/storage-isolation.md.
• Cross-game read test: it documents, it does not deny. A regression test reads one game's learn key from another game and is expected to succeed today. It flips to a denial test only if isolation ships.
• Behaviour data without names can still identify a child: timing, items, rare combinations. Nothing is called "non-identifying" just because names are left out.

2.3 Authority and wipe (D49)

• Switch (D49): only the operator may switch learning on and wipe it; GOAT accounts cannot. Absent, corrupt or newer settings mean OFF. The setting is bound to the player id and the current MM.player generation nonce, and it lives outside the learning store (device-only mm-learn-op), so it never rides the learning cloud path.
• What is enforced today, and what is not. The privileged APIs operatorEnable and operatorWipe check the hub owner, so a non-owner cannot use them. Routine start() then trusts the stored mm-learn-op record. Under D52, any same-origin script can forge that record. A forged switch can start bounded shadow recording (coarse ratings and counts, ≤ 8,000 bytes, no child-visible effect), and that state syncs to the hub cloud copy. This is a storage-integrity limitation of Phase 2 shadow capture, not a missing owner check on the privileged APIs. So this design does not claim that D49 is an enforced boundary against same-origin code.
• Operator choice (open, §10):
• (A) UI authority. "Operator-only" means only the operator can turn learning on through the product UI and APIs, under the assumption that all first-party game code on the hub is trusted (D52). A forged switch remains a known residual, limited to bounded shadow recording.
• (B) Unforgeable grant (recommended). Before any collection, start() requires an operator grant that same-origin script cannot forge: a hub-side or db-backed grant, checked by the hub, bound to the player id and generation. This also closes §0 gap 1, since a hub-side grant can cover a child's own claude.ai account.
• Until the operator chooses, what is built is (A). It is described as (A), never as (B).
• Known limits: §0, gaps 1–2.
• Wipe scope: wipe covers every game namespace that holds learning state for that child, local and cloud copies. It cancels pending writes, and a durable readback confirms success. A game may not start recording until its namespace is in the wipe scope and passes G-L5. (Today only Whetstone records and is in scope; §0 gap 3.)
• Priors: population priors (if they ever exist) are a separate artifact with their own expiry. A child wipe doesn't reach into them, which is why priors may only be built from aggregates (§7.3), and aggregates are OFF.

2.4 Fail safe

Missing, corrupt or newer state, a new game, too little data, or learning switched off all give exactly today's behaviour: the fixed ladder and the default bot.

2.5 Saves

• Learning uses a dedicated store key, so it never shares a key with game progress.
• Unknown fields are preserved (D42).
• Newer-version state is quarantined and kept, never deleted or overwritten (SB1).
• Preserved unknown fields are never read as trusted policy.

2.6 Measured against a frozen comparator

Nothing reaches children until it is authorised by a new operator decision (D50), and general release needs G-L9 (§8). Otherwise it stays off.

3. What is recorded

Prefer compact sufficient statistics over raw events. For example, keep per-skill counts and a rating plus per-item counts, not an event log. Per learner:

Only IDs and enums cross the learner boundary. Display text is always resolved from trusted templates and passes through the D45 ingest and the D40 fail-closed display sink at final render.

Size. The 100,000-byte cloud cap covers the game's whole payload. The learning namespace gets a measured budget of at most 8,000 bytes, including its .bak copy, JSON/key overhead and per-key timestamps (the built learn.js measures it as stored), with:

• trim and overflow rules;
• a test that fails if the combined per-game payload (progress + its .bak + learning + its .bak), measured at the admitted caps, reaches 100,000 bytes, with explicit headroom for progress (G-L1, §8);
• a recovery path when the budget is hit.

No "N events" promise stands in for a byte guarantee.

Multiple devices. Sync is newest write per key wins, with no merge, so two devices can overwrite each other's learning state. This is an accepted risk, not a recoverability guarantee: the local .bak restores only the last good state on that device, and there is no cross-device restore contract. A stale device's write can erase another device's mastery history, so the §4 floor is a per-device continuity guarantee (G-L7b scope). A merge protocol would be a separate design with its own tests.

4. Learners (separate objectives, separate promotion tests)

Player mastery, the opponent policy and any shared representation are different learned objects. Each gets its own labels, objective and promotion gate.

L2. Bad-question spotter: builder-only, advisory (Phase 1, built)

• Runs offline on synthetic and replayed historical play.
• Flags items whose behaviour is odd for their rating.
• Output is a Build Board report with provenance. It never changes content automatically and is never shown to children.
• Check: it must flag the old Whetstone identity bug and the old Color Monster Academy parity and long-float bugs when replayed (results in §0).

L1. Right-level question picker: SHADOW (Phase 2, wired in Whetstone)

• State: an Elo-style rating per skill or BKT, per child, plus the mastery history below.
• Shadow mode: the fixed ladder still chooses every question. L1 only logs what it would have chosen and what it predicted, so there is no child-visible effect.
• Live mode (only after a new operator decision and the Phase 3 entry conditions in §9):
• target a predicted success of about 0.70–0.85;
• per-session bound: difficulty can't drop more than one step within a session;
• cumulative floor (below);
• a guaranteed floor of mixed review;
• spaced review.
• Accessibility: timing never penalises a child; L1 has no timing input.
• Why band occupancy is not the measure: choosing items predicted at 70–85% satisfies a "band occupancy" metric by construction. Occupancy is a diagnostic only.

Cumulative anti-gaming floor

The per-session bound alone lets repeated failures ratchet difficulty down one step per session. So, for each skill:

• Invariant: the suggested level is never below max(ladder floor, M − K), where M is the child's demonstrated mastery level for that skill over the rolling window.
• Parameters: K = 2, W = 10 are proposed defaults, not operator decisions. Both are versioned config, fixed in the §6.1 protocol before Phase 3, and changed only by a recorded decision.
• Scope of the guarantee: bounded, not indefinite. Failures can never lower M; only window expiry can. So a child who deliberately fails every attempt can lower the floor, but only after W skill-sessions with no mastery shown at that level. That is intended: genuine forgetting must eventually be allowed to lower difficulty.

Mastery history (state per skill). One stored maximum cannot work. Example (levels illustrative, W = 10): history A = [(level 10, session 1), (level 7, session 2)] and history B = [(level 10, session 1), (level 9, session 2)] both have current maximum (10, 1). When session 1 expires, the correct M is 7 for A and 9 for B, which a single maximum cannot tell apart. So each skill keeps:

A skill-session is a game session in which the skill was played at least once.

No absolute session counter is stored (bounded rebasing). v2.3 stored an absolute per-skill counter s in two base-36 characters, which covers only 0–1,295 and would wrap or overflow at 1,296. v2.4 stores ages relative to the current skill-session instead. Each new skill-session rebases all retained entries together: every age goes up by 1, and entries reaching W are dropped. Ages, window membership and order are all preserved, and every stored value is bounded by W − 1 however long a child plays. Constraint: W ≤ 36, so an age fits one base-36 character. A W above 36 needs a new encoding and a migration. There is no silent wrap: a stored age outside 0 … W − 1 fails validation (below). An implementation may keep an absolute counter in memory only; if one is ever persisted, it must use variable-width encoding with a measured worst-case cap inside the budget.

Mastery criterion: at least 3 correct of the last 4 attempts at a level, within one skill-session. Fewer than 4 attempts at a level never counts as mastery. Because ro resets each skill-session, old outcomes cannot combine with a single new attempt to credit mastery.

Expiry boundary. The window is the current skill-session and the W − 1 before it, i.e. ages 0 … W − 1. Mastery shown at skill-session s0 has age W − 1 at s0 + W − 1 (still in the window) and age W at s0 + W (expired).

Update order (per attempt at skill k, level ℓ):
1. If this is the first attempt at k in this game session: add 1 to every deque age; drop entries whose age is now ≥ W; reset ro.
2. M = the level at the deque front, or none if the deque is empty.
3. Floor = max(ladder floor, M − K) if M exists, else the fixed ladder's own placement. The suggestion (logged only, in shadow) is computed now, so expiry happens before the suggestion.
4. Record the outcome in ro[ℓ].
5. If ro[ℓ] has 4 outcomes and at least 3 are correct, credit mastery (age 0, ℓ):
- if the deque tail is (0, ℓ') with ℓ' ≥ ℓ, do nothing;
- otherwise pop tail entries whose level is ≤ ℓ (equal levels: the newer entry wins, since it expires later), then append (0, ℓ).
6. Persist, subject to the budget. Mastery credited mid-session raises the floor for later attempts at once; it never lowers it.

Validation on load (untrusted input, §2.1): ages are integers in 0 … W − 1 and strictly decrease from front to back; levels strictly decrease and lie in the ladder range; the deque is no longer than its bound; ro counts are 0–4. If any check fails, that skill's mastery history is dropped and the floor falls back to the fixed ladder's placement (§2.4); it never falls below it.

Multi-device scope: per-device continuity (recommended for Phases 2–3). Sync is whole-key newest write wins (§3). A stale device that reconnects and writes can overwrite a newer mastery history and erase its high-water mark, and the overwriting record may be internally valid. So the guarantee is scoped:

• Per device (adopted for Phases 2–3): on a device whose own stored history has not been overwritten, the invariant holds exactly. After an overwrite, the floor follows the surviving record and is never below the fixed ladder's placement (the safe ladder fallback). The high-water mark can be lost; that is disclosed, and it is part of the accepted multi-device risk.
• Player-wide (not adopted): this would need a monotonic merge, e.g. a union of both deques keeping the higher mastery per window position, instead of last write wins. That needs an alignment rule for ages counted on different devices, plus its own design and tests. It is listed as a future option, not a requirement.

Serialised size. Proposed compact encoding per skill: each deque entry as 2 base-36 characters (1 for the age, 1 for the level); each level's ro as 1 base-36 character (count plus outcome bits form 31 states). No session counter is stored. For Whetstone (7 levels) the worst case is about 14 + 7 characters plus separators and quoting, so ≈ 26 bytes per skill per copy. At 60 skills, with the .bak, that adds about 3.1 KB to the existing per-skill state. This is an estimate, not a measurement. G-L1 must re-measure the worst case of the whole learn key + .bak as stored, with the mastery history included, against the same 8,000 bytes. If it does not fit, the number of skills that carry a mastery history is lowered (skills without one fall back to the ladder placement). The budget is not raised.

L3. Judge "not sure": DEFERRED (Phase 4)

• Blocked until the base …or Die judge contract is candidate-tested (malformed replies, valid zero, fallback, provenance; pl21).
• Then:
• friend overrules are a noisy signal, not ground truth;
• evaluate on an operator-labelled held-out set with a risk-versus-coverage curve, false-accept and false-reject rates, and calibration;
• no cap on the "not sure" rate.
• The three-vote judge's votes are correlated, so they don't count as independent.

L4. Opponents: two separate objects (D51, D54)

L5. Factory risk hints: CI only

• Gate and review statistics live in CI, outside child saves.

5. Relation to the modular ANN research

R1/R2 (the selective-training study) is proposed future research under review. Its results do not automatically qualify game transfer or child personalisation.

A shared trunk with per-game heads is an experimental arm against the simple per-game baseline, not the target architecture. Log-loss is lower-is-better, and the two quantities are defined with that direction:

• new-game gain G = loss_baseline − loss_candidate (positive = the shared-trunk head beats the per-game learner);
• old-game degradation D_g = loss_after − loss_before for each existing game g (positive = worse).

Adoption rule (predeclared, Phase 5):

• Gain: the one-sided lower confidence bound of G is above 0.
• Non-inferiority on every old game (intersection–union): for every existing game g, the one-sided upper confidence bound of D_g is ≤ τ. Adoption needs all of them. Because adoption requires every game to pass, each test runs at the predeclared level with no multiplicity adjustment, and no subset of favourable games may be selected. A small point estimate is not enough: an estimate D = 0.01 with τ = 0.02 fails if its upper bound is 0.20. Scope: this intersection–union argument covers only the fixed, predeclared comparison, i.e. one candidate model, the predeclared set of existing games and one analysis. It does not waive controls for later model selection (trying several candidates or configurations), adding or dropping games, or repeated peeking at accumulating data. Each of those needs its own predeclared correction or a fresh, untouched evaluation set.
• Dependence: the same children play several games, so the CI method must account for that, e.g. by resampling whole children (a cluster bootstrap). The method is named in the Phase 5 plan.
• No zero-degradation requirement: τ is an absolute log-loss tolerance greater than 0.
• Always reported: signed G and every D_g, each with its confidence interval, whether or not adoption passes. A gain on the new game with a loss on an old one is still reported as transfer evidence; the product decision is separate.

τ, the confidence level and the other exact numbers are fixed in the Phase 5 plan before any data is looked at.

6. Evaluation design

• Held-out checks:
• a sealed manifest of check items from item/template families disjoint from training, with lineage by child, item, template and version;
• minimum N and freshness rules, fixed in §6.1;
• exposure tracked, since repeated checks become familiar;
• no tuning against the holdout.
• Comparator: a frozen fixed-ladder baseline, in a within-child design with carryover handled as §6.1 requires.
• Outcomes: exactly one primary, named in the §6.1 protocol. The default primary is gain on held-out checks; retention on delayed checks is then a key secondary. The protocol may instead name retention as the primary, but never both.
• Secondary outcomes:
• observed calibration by skill bucket, with uncertainty;
• quit and stall rates. Human quits stay in the denominators and are reported. Only harness/automation stalls are excluded, and they are classified separately;
• human play only, with automated play excluded.
• Scope honesty: one child over two weeks is a single-child result and is reported that way.

6.1 Evaluation protocol: required before Phase 3 data

Phase 3 collects no data until a written evaluation protocol exists. It must be:

• dated, and committed before the first Phase 3 session;
• version-pinned: the sha256 of learn.js, the game build version, the gate-test commit, and the protocol file's own sha256, recorded in the operator decision that authorises Phase 3;
• immutable once data collection starts. A change means a new protocol version, a new decision, and the data already collected is reported under the old protocol.

It must state, at minimum:

The confirmatory protocol (Phase 3C) is a separate document with the same rules plus: the intended population (the children a general release would reach), the independent unit (the child, not the session or the item), a power calculation giving N in children, and a randomised design from the carryover options above.

7. Architecture

1. Module learn.js in the factory kit (games/_factory/learn.js, standalone):
- learn.observe(id, enumOutcome) records an outcome, schema-validated;
- learn.suggest(eligibleIds) returns an ID that must be one of eligibleIds; the caller re-checks;
- learn.flag() is builder-only;
- learn.botLevel() is clamped and starts at the player's chosen level (D54). It adapts from child outcomes only if L4b is approved (§4, §10);
- learn.wipe() follows the §2.3 scope.
2. Storage: MM.store("<game>-learn-v1", {v:1,…}, migrate), a dedicated key with in-place migration (D42) and the ≤ 8,000-byte budget (§3). The §4 mastery history is a schema addition, so it needs a migration and the G-L6 checks. MM.store syncs to the hub cloud copy for signed-in children; that is the D48-approved path. The operator switch (mm-learn-op) is device-only and is not stored here.
3. Aggregates: OFF (D48). Not built. If ever proposed, they need:
- a closed aggregate-only export schema: no UID, no per-child rating, no rows, no arbitrary keys;
- bounded contribution per child;
- minimum cohort and rare-cell suppression;
- release cadence and query controls;
- revocable opt-in that cancels queued uploads;
- a new operator decision.
With one family the cohort is too small, so the answer today is no export.
4. Compute: in the browser, simple statistics only. Training experimental neural or shared-trunk arms offline is part of the Phase 5 research that produces the §5 evidence. Shipping fixed, versioned weights to children happens only after that evidence meets §5. L4a self-play runs on oldisgold with bot-only data (D51).

8. Release gates (executable, evidence retained, rollback = fixed default)

9. Rollout (simplest first)

10. Decisions

Decided (operator, 19 Oct 2026):

• D48 device + hub cloud copy; no export.
• D49 operator only switches and wipes; GOAT accounts cannot. What this means against same-origin code is open; see item 1 below and §2.3.
• D50 Phases 1–2 approved, shadow only; going live needs a new decision. The row requires G-L1..G-L8 before any live step; this design also requires G-L7b, and does not edit the row.
• D51 L4 opponent track runs in parallel, bot-only data (L4a here).
• D52 proceed with the documented same-origin boundary; plan isolation in proposals/storage-isolation.md.
• D54 the adaptive bot starts at the player's chosen level.

Open (for a future operator decision):
1. D49 meaning and the operator grant (§2.3). Either (A) "operator-only" is UI authority under the trusted-first-party-code assumption, with forged-switch shadow recording accepted as a residual; or (B, recommended) require an unforgeable hub-side or db-backed operator grant before any collection. (B) also lets the switch be enabled on a child's own claude.ai account (§0 gap 1).
2. G-L1 for Whetstone (§8): lower Whetstone's own save caps so the admitted-cap gate can pass, or accept a narrowed "realistic payload" claim.
3. Phase 3 go-live: authorise the bounded live pilot, with the §6.1 protocol attached.
4. Phase 3C: whether and how to run a confirmatory evaluation (population, cross-child data handling), with its own protocol.
5. L4b: whether a per-child bot controller may consume that child's match outcomes on device (§4).
6. Storage isolation: adopt the proposals/storage-isolation.md design (a separate platform project).
7. Numbers: K and W (§4; W ≤ 36 under the current encoding), and τ and the confidence levels (§5), each fixed before the data they govern.
8. Player-wide floor: whether the §4 floor should later become player-wide through a monotonic merge (not required for Phases 2–3).

Appendix A. Revision history