Reverse Cross Roadmap¶
Status: Active game-specific implementation roadmap and migration history.
Audience: Product and engineering contributors sequencing Reverse Cross work.
Documentation snapshot: Branch jm/string-repetition at a12ff3b. Current compact puzzle and
play schemas are summarized in Data Layout and Persistence.
Production feature state must be verified operationally.
This is the living implementation roadmap for taking Reverse Cross from its hardcoded prototype to a generated, persistent, timed game on the shared MiniGames platform. It is a companion to the platform roadmap, which remains authoritative for suite-wide identity, storage, content governance, infrastructure, and operational policy. Product behavior is summarized in the Reverse Cross specification.
The durable shared lexical/game design is maintained in Lexical and Game Architecture; this roadmap records execution order, decisions, and migration history.
Update the status table and phase checklists as decisions land. Each phase should remain independently reviewable and releasable. Branch names are intent, not a mandate to preserve a long-running branch.
Phase 3 implementation commits: 7b2b803 (3A), 824b2c5 (3B), 5d95bbf (3C), and
4f56007 (3D).
| Phase | Suggested branch | Status | Exit outcome |
|---|---|---|---|
| 0. Discovery, boundaries, and plan | jm/reversex-poc-puzzlegen |
Complete | Current behavior and target boundaries are documented; generation remains deliberately open. |
| 1. Shared lexical catalog foundation | jm/phase1-refactor-complete |
Complete | Letter Golf runs on one versioned in-memory catalog; deterministic integration proves a Reverse Cross view can share that snapshot without adding generation. |
| 2. Reverse Cross hardcoded vertical slice | jm/phase2-integration |
Complete | Validated fixtures use the shared catalog and forward-compatible contracts, with no generated puzzles. |
| 3. Basic on-demand puzzle generation | feat/reverse-cross-generator |
Implementation complete through 3D; production-container validation pending | A bounded, reproducible, solution-first generator emits valid unthemed puzzles in seconds. |
| 4. Daily, Practice, play persistence, and timing | phase-4/tests-complete |
Complete | Daily, Practice, 14-day pregeneration, puzzle storage, play lifecycle, authoritative timing, ownership integrity, current competition/spoiler exclusions, endpoint integration coverage, and the full backend regression gate are complete. See Phase 4 Pool Measurement Plan. |
| 5. Production player UI and accessibility | feat/reverse-cross-gameplay-ui |
Complete | The timed board works across input modes, screen sizes, arbitrary supported dimensions, and resume states. |
| 6. Stats, streaks, groups, and competitive timing | feat/revx-group-standings |
Complete | Daily pause, duration statistics, streaks, deterministic replay, personal presentation, and comparable group competition are complete. |
| 7. Difficulty, quality, and fun calibration | feat/reverse-cross-quality |
Evaluator and structural-quality foundations complete; calibration pending | Versioned presets are based on measured structural, lexical, aesthetic, and playtest signals. |
| 8. Rich entries, themes, and editorial workflow | feat/reverse-cross-content |
Not started | Approved proper nouns, abbreviations, phrases, idioms, topical packs, and themes can be opted into safely. |
| 9. Language and grapheme expansion | feat/reverse-cross-languages |
Not started | Generation, validation, UI, and competition are correct for each supported language. |
| 10. Generation operations and staged release | feat/reverse-cross-operations |
Foundations underway; Daily generation gating implemented; staged enablement pending | On-demand generation is observable and reproducible, with pre-generation/pools available when justified. |
Decisions already made¶
- Reverse Cross is not golf-themed. Its primary score is server-calculated completion duration; lower is better.
- The game reuses the suite's identity, visual language, Daily/Practice model, puzzle persistence, telemetry pipeline, statistics/streak infrastructure, and group platform where their contracts are genuinely game-neutral.
- Duplicating the word corpus per game or per generator is unacceptable. One immutable catalog snapshot should own normalized entries; per-game policies and indexes should reference it.
- Letter Golf and Reverse Cross can use different eligibility rules. Proper nouns, abbreviations, phrases, idioms, or themed entries may be valid for Reverse Cross without becoming valid Letter Golf submissions.
- Future grids are not limited to 9x9 or even to squares. Supported row and column ranges are configuration and product decisions.
- The first generated-puzzle milestone is unthemed and solution-first. A puzzle is never emitted without an internal construction proof and full validation.
- Production selection and generated Practice policy: engine/configuration limits support
square sizes 5x5–9x9, but production fallback fixtures and automatic production selection
remain the validated odd-only presets (5x5, 7x7, 9x9). The explicit
GeneratedPractice override is enabled for targeted validation/playtesting and accepts 5–9 squares; it is opt-in and runs against pinned production catalog snapshots. Early deterministic cohorts (3 seeds/size) for 6x6 and 8x8 returned 3/3 successes and the summarized timing/metrics are recorded in the Reverse Cross spec. Do NOT expand automatic production selection beyond the fixture-backed 5/7/9 presets until a larger corroborating cohort validates success, latency, uniqueness, and fallback compatibility. - The construction solution is a private witness, not an exclusive answer key. Any arrangement that uses the public bank exactly once, fills all maximal slots, and agrees at crossings is valid.
- Phase 3 does not prove uniqueness. Alternate-solution discovery is deferred to spoiler-protected God View/editorial tooling and may later inform quality ranking.
- Raw valid-board counts include structurally inevitable Across/Down transposes when the public puzzle is transpose-invariant. Before alternate reconstructions affect ranking, rejection, or a difficulty preset, retain the concrete count but score distinct equivalence classes modulo valid transposition; a transpose-only alternate must not lower puzzle quality.
- On-demand generation must be bounded and normally complete in seconds, not minutes. A later pool of pre-generated puzzles is an operational optimization, not a prerequisite for designing a responsive generator.
- Generated Daily rollout uses one stable synthetic system targeting identity,
system:reverse-cross-daily. A missing Daily date uses production-default generation only whenReverseCrossDailyGenerationandReverseCrossGenerationevaluate true for that identity; otherwise the missing date is persisted from fixtures.ReverseCrossStructuralQualityis also evaluated with the synthetic Daily identity. Existing persisted Daily puzzles are immutable cache hits and are not rewritten by flag changes. User-targeted allowlists do not enable Daily generation; operators should use global All On/Off for Daily rollout. - The two historical mask-generator design exports are the seed material for the generation discussion, not a selected algorithm. ADR 0001 closes the Phase 3A design gate; their mask ideas remain inputs to the bounded Phase 3C evaluation.
- Another publisher's crossword clues, answers, or daily archive are not an ingestion source. Every source needs verified rights, provenance, and an explicit update policy.
Release-safety gate for Letter Golf¶
Phase 1 began while Verbolus was awaiting AdSense review, and Letter Golf remains the mature production game. Shared-code work must therefore treat current Letter Golf behavior as a protected compatibility contract even though the player cohort is still small. No architectural preference is sufficient reason to risk the deployed game.
- Capture a green baseline from
mainbefore Phase 1 implementation: backend tests, frontend tests, lint/type-check/build, focused Letter Golf browser journeys, and relevant Docker smoke tests. - Introduce the catalog behind compatibility adapters. Keep existing Letter Golf endpoints and DTOs stable, and avoid mixing file moves with behavioral changes.
- Characterize generation and validation with deterministic seeds/fixtures and invariant tests. Preserve Daily/Practice puzzle retrieval, authoritative submit, autosave/resume, stats/streaks, groups, identity cookies, feature flags, telemetry, and admin/debug spoiler behavior.
- Run focused checks after each small commit, then the complete affected suite before merge. Test the synced WSL Docker images while continuing to edit and run browser verification from Windows.
- Compare OpenAPI and representative serialized puzzles/plays so a shared-model refactor cannot silently break the deployed frontend or persisted Cosmos documents.
- Measure catalog/index cold start, warm-up, generation, and validation so sharing memory does not regress Letter Golf latency or readiness.
- Keep Reverse Cross changes independently feature-flagged or fixture-backed. A failed rollout must be reversible without changing Letter Golf content, storage, or endpoints.
- Phase 3 may be merged and deployed with
ReverseCrossGenerationabsent or disabled, preserving fixture serving. Do not enable generated serving until the production-container/load evidence and staged-rollout gate in Phase 10 have been reviewed. No documentation milestone authorizes an Azure configuration change by itself.
Architectural target¶
The current IWords abstraction combines source loading, catalog storage, random selection,
membership testing, dictionary style, language, and theme parameters. MultiDict then hardcodes
source composition and retains a separate process-local set per dictionary style. That was useful
for a prototype but cannot express source provenance, rich entry forms, reliable language rules,
or game-specific eligibility without duplication and accidental coupling.
The target separates five responsibilities:
- Sources acquire raw records and report identity, version, license/provenance, and source quality metadata. Network loading is injected, cancellable, observable, and cannot silently turn a failed download into a valid empty catalog.
- Normalization and content governance produce canonical entries, segment graphemes, apply suite-wide moderation, and preserve display form separately from grid form.
- Catalog snapshots expose an immutable, versioned, language-scoped set of entries. Snapshot initialization and refresh are single-flight and atomic; the last known good version remains usable if a refresh fails.
- Game eligibility profiles decide which catalog entries a game/mode/configuration can use. Letter Golf and Reverse Cross policies are composable views, not independent dictionaries.
- Game indexes and generators own algorithms. Letter Golf retains its count-signature trie; Reverse Cross uses a length-bucketed positional index over the same entry identities.
Provisional names such as LexicalEntry, IWordSource, IWordCatalogProvider,
WordCatalogSnapshot, and IWordEligibilityPolicy describe roles, not locked APIs. Public
contracts should emerge from characterization tests and the smallest coherent migration.
An entry should be able to carry:
- stable entry ID, language, normalization version, display form, grid form, and graphemes;
- source ID/version, retrieval or build timestamp, license/provenance, and source-native score;
- form tags including word, inflection, proper noun, abbreviation, phrase, idiom, and other;
- optional frequency/familiarity, part-of-speech, theme/topic, editorial score, and expiry;
- suite-wide and game-scoped allow/deny decisions with a content-policy version.
The catalog owns entry/string memory. Derived indexes may store compact entry IDs, signatures, grapheme lengths, or search links; they should not materialize another million independent strings.
Phase 0 - Discovery, boundaries, and plan¶
Branch: docs/reverse-cross-roadmap
Findings¶
AbstractWordsprovides useful lazy single-flight initialization and retry behavior, but its selection method ignores dictionary style, theme, and language and filters with UTF-16string.Lengthrather than grapheme count.- One
IWords.GetWordsAsyncoverload discards its caller-supplied theme and language. DictionaryDownloaderis static, rejects only spaces/hyphens, and converts every failure into an empty result. It has no cancellation, pinned content version, source health, or provenance contract.MultiDictshares a cached set within a process and dictionary style, but source registration is string-keyed and hardcoded.StandardandCrosswordare separate unions rather than policy views over one catalog.IWordListProviderandInMemoryWordListProviderare good future seams, but the current deny and curated sets are empty scaffolding; themes and per-game content policy are not implemented.IGraphemeSegmenteris shared in name, but the English implementation iterates UTF-16charvalues. Backend length checks and the Reverse Cross frontend also use code-unit indexing.- Letter Golf's
LetterSignature,WordSignatureIndex, and seed/alternative-solution selection are appropriately game-specific concepts. Their placement and naming should make that boundary explicit.LetterFrequencyTablecan depend on shared grapheme/catalog primitives without becoming a Reverse Cross algorithm. - The then-named
TestLetterGolfGeneratorwas production-capable code under a prototype name and has since been renamedLetterGolfGenerator; it still injects an unused Cosmos client. Its count trie and frequency data are independently cached from the validation dictionaries rather than built as derived views of one catalog snapshot. - Reverse Cross now uses an asynchronous, cancellable
IReverseCrossPuzzleProvider; its Phase 2ReverseCrossFixtureProviderresolves validator-approved fixtures through the shared catalog, enforces configured dimension limits, and supports deterministic selection seeds. Current Daily, Practice, and keyed puzzle endpoints return the typed public mask and entry contract. - The original 9x9 fixture's copied 7x7 Down suffix could not satisfy the exact-slot-length rule. Its canonical replacement keeps the deployed mask and Across entries while deriving the twelve valid Down entries from the complete private solution.
- The client validates placement locally, identifies entries by text, starts its timer on page load, and has no persisted or authoritative completion path.
- Existing play/stat storage was designed with game discriminators, but payloads and calculators still contain Letter Golf fields and scoring assumptions. They need additive game-specific payloads or strategies, not parallel infrastructure.
Historical mask-generator notes¶
Two old design/technical exports explored random square masks, rotational or diagonal symmetry, minimum three-cell runs, row/column coverage, target black-cell density, and bounded retries. Those are useful experiment candidates only. Mask validity does not prove lexical fillability, connectedness, checked cells, reconstruction uniqueness, or player-facing quality, and the sample algorithm was incomplete. None of those constants or strategies is locked for Phase 3.
Exit checklist¶
- Document current behavior and platform reuse goals.
- Identify shared lexical responsibilities and game-specific algorithm boundaries.
- Record generation as an explicit pending design decision.
- Review the roadmap with the project owner and mark Phase 0 complete. A follow-up review with the other creator can refine later phases without reopening this discovery gate.
Phase 1 - Shared lexical catalog foundation¶
Branch: jm/phase1-refactor-complete
Status: Complete (2026-08-28)
This is a compatibility-preserving extraction, not a rewrite of Letter Golf behavior and not the platform roadmap's full Content Governance phase. It creates the seams that Content Governance and both games will use; database-backed editorial tools, ingestion jobs, and content administration remain in platform Phase 6.
Execution progress¶
- Step 1 - protected baseline (2026-08-27). The project owner confirmed the deployed
Letter Golf flows are working. A fresh Windows-native baseline passed 471/471 backend tests
after excluding the one test explicitly categorized
Flaky, and passed 429/429 frontend tests across 48 files, ESLint, TypeScript checking, and the Next.js production build. - Step 2 - focused characterization tests (2026-08-27). Eight deterministic tests now protect overload defaults/overrides, dictionary-style isolation, aggregate refresh behavior, content-provider null contracts, current English segmentation, and Letter Golf solution lookup. Together with the existing initialization, retry, refresh, membership, signature/index, and generator tests, they establish the compatibility boundary without fixing random output. An optional generation seed made the sole categorized flaky test reproducible and added a replay check, so the complete backend suite now passes 481/481 with no exclusions. Tests deliberately omit network source behavior until it has an injectable seam, exact shuffle order, private collection/source iteration details, and future multilingual segmentation rules.
- Step 3 - additive lexical contracts (2026-08-27). New framework-independent contracts
under
Words/define normalized entries, display/grid forms, graphemes, source-specific scored provenance, source descriptors/raw acquisition, immutable versioned snapshots, catalog requests, and side-effect-free game eligibility. Focused tests cover immutability and invalid-state boundaries. Nothing is registered in dependency injection or called by the existing production word sources, endpoints, Letter Golf generator, or Reverse Cross fixture provider yet. - Step 4 - immutable catalog build and publication (2026-08-27). A compatibility adapter
can expose existing
IWordsimplementations as provenance-bearing lexical sources. The shared builder now applies versioned language normalization, suite-wide deny filtering, source merge and validation, minimum-size validation, deterministic catalog versioning, and safe aggregate telemetry before constructing a complete immutable snapshot. The in-memory provider publishes one current snapshot per language, coalesces concurrent builds, preserves the last known good snapshot across refresh failures, and gives caller cancellation the semantics documented below. Twenty-one focused tests cover the builder, provider, and legacy adapter. These types remain deliberately unwired from production dependency injection, so Letter Golf behavior and memory ownership have not changed yet. - Step 5 - explicit game profiles and shared views (2026-08-27). A composable, versioned
eligibility profile now filters normalized catalog metadata by game, form, source, optional tags,
themes, and source-native score without I/O. Named Letter Golf Standard/Common Seed and Reverse
Cross Crossword profiles preserve separate admission boundaries.
WordCatalogViewretains the shared snapshot and entry references, exposes stable profile/context fingerprinting, and proves a permissive Reverse Cross form or source cannot broaden Letter Golf. The initial Reverse Cross profile reproduces the Crossword Nexus source view; it does not imply puzzle generation. - Step 6 - additive
IWordscatalog facade (2026-08-27).CatalogWordsAdapterprojects named catalog views through the legacyIWordscontract for incremental caller migration. Characterization comparisons preserve current Standard/Crossword unions and case-insensitive membership. The new path forwards the requested language, uses stored grapheme counts for length, and rejects unsupported themes/styles rather than discarding them. The facade necessarily materializes the legacy string-set result, so new game code should use entry-bearing views. It is not registered in production yet. - Step 7 - Letter Golf catalog-derived indexes (2026-08-27).
WordSignatureIndexcan now build its count trie from catalog entry IDs and the snapshot's authoritative graphemes, while its compatibility constructor preserves the existing string-based generator path. The frequency table likewise accepts catalog entries without re-segmentation.LetterGolfCatalogIndexretains the shared view entries, derives the common-seed subset from provenance, and resolves trie IDs back through the snapshot. Its provider coalesces builds and atomically caches by catalog version, profile ID/version, and index-options fingerprint; a newer version does not invalidate an older index already held by a caller. At this milestone the catalog-derived index remained additive and was not production-wired, so current Letter Golf endpoint, generator, serialized puzzle, and memory behavior remained unchanged pending the later source-version/rights and merge gates. - Step 8 - physical ownership and permanent naming (2026-08-27). Shared lexical domain,
normalization, sources, content policy, catalog, views, and temporary compatibility types now
live under
Words/; Letter Golf and Reverse Cross domain/content/generation code now lives underGames/<game>/with application and validation subareas where needed. The production Letter Golf implementation is now namedLetterGolfGenerator, with a production keyed-service constant. Tests mirror durable ownership and no longer carry phase-step names. These were mechanical file moves and naming changes: namespaces, generation behavior, HTTP contracts, persistence, and production catalog wiring remain unchanged. The steady-state design and old-to-new migration are documented in Lexical and Game Architecture. - Step 9 - additive catalog and derived-index observability (2026-08-27). The shared catalog path now emits safe Activity spans for catalog build, per-source refresh/read, initial load, refresh publication, view build, and Letter Golf derived-index build. These spans carry language, version/fingerprint, bounded counts, and status/error-type tags only; they never tag raw lexical content, denied terms, or entry IDs. Focused tests cover success, cancellation, retry-after-failure, last-known-good retention, failed-view eviction, and index single-flight behavior without wiring the additive path into production DI at that milestone.
- Step 10 - production composition and Letter Golf cutover (amended 2026-08-28). Native
HTTP lexical sources now acquire pinned artifacts through an injected client with explicit
timeout, bounded transient retry, cancellation, parsing, and minimum-size validation. Their immutable descriptors identify the
source, language, pinned commit, declared license, and provenance URI; an unavailable, malformed,
or unexpectedly small source fails the candidate catalog instead of publishing partial content.
Production DI registers Common Words, Webster, dwyl, the local prepared Frequency List, the local
Verbolus common-word compilation, Crossword Nexus, the local Peter Broda scored list, and
first-party Reverse Cross fixtures as source singletons. The local artifacts are copied into
build and publish output. Frequency List and Verbolus common words contribute to Letter Golf and
Reverse Cross profiles, while Peter Broda remains eligible only through Reverse Cross profiles.
Composition then publishes one process-wide
catalog provider, view provider, and Letter Golf index provider. The live
LetterGolfGeneratorconsumes that catalog-derived index and its shared entry/grapheme objects; the keyedIWordsservice is now aCatalogWordsAdapterretained only for validation callers. Shared builds are bound to application shutdown and a three-minute catalog operation limit, while request cancellation remains scoped to each caller's wait. Solution lookup now normalizes historical lowercase puzzle keys before querying the uppercase catalog signature index. Newly generated puzzles persist and publish the catalog and Letter Golf profile versions used to derive them. Catalog identity includes canonical accepted content, so moderation changes cannot reuse a stale derived index under the same version. A deterministic composition test proves Letter Golf and Reverse Cross views can reference the same snapshot and entries; Reverse Cross remains fixture-backed and no generation algorithm was added. Source-license declarations and the completed dwyl/Moby provenance review are recorded in Third-Party Notices.
The existing observability baseline is already substantial and has been extended rather than
replaced: StartupDiagnostics records safe process-to-listening milestones and phase durations;
AzureAppConfigurationDiagnostics records App Configuration operation duration/status and safe
Azure SDK warning metadata; the legacy WordList.ColdStartLoad span measures MultiDict
initialization when that compatibility implementation is exercised;
LetterGolf.DailyPuzzleGeneration measures cache-miss Daily generation; and the shared catalog
path now emits
WordCatalog.Build, WordCatalog.SourceRefresh, WordCatalog.SourceRead, WordCatalog.Load,
WordCatalog.Refresh, WordCatalog.ViewBuild, and LetterGolf.CatalogIndexBuild. The new
catalog/index spans stay on safe language/version/count/status fields. They are now operationally
visible when the live Letter Golf path cold-loads or rebuilds its catalog-derived index.
Snapshot publication semantics¶
Immutable shared layer. A catalog build is private until every selected source has been read,
normalized, moderated, merged, and validated. The builder then copies the accepted records into a
WordCatalogSnapshot; callers cannot mutate its entry, source, grapheme, or tag collections. The
provider publishes the completed object with one reference swap. All consumers of the current
language version receive the same snapshot instance rather than copying a million strings per
game. A consumer already holding an older snapshot can continue reading it safely after a refresh.
Single-flight loading. The provider keeps at most one in-flight build task per language. Concurrent cold-start callers await that same task and receive the same published object. During a refresh, ordinary reads continue receiving the last published snapshot; only after the replacement is complete does a new caller see it. Concurrent refresh requests also share one build. A failed initial build is removed from the in-flight slot so the next request can retry rather than pinning a faulted task for the process lifetime.
Versioned snapshots. The catalog version is a deterministic digest of the catalog schema, canonical language, normalization version, suite content-policy version, and sorted source identity/version/license/attribution descriptors. A source version must therefore identify pinned content or a verified content fingerprint; changed source bytes under an unchanged version would violate the source contract. The provider retains only the current snapshot to avoid duplicating the full corpus in memory. An explicit request for a different version fails rather than silently substituting current content. Previously returned immutable snapshots remain valid while referenced; a future artifact store may support historical lookup without retaining every corpus in each API process.
Cancellation and failure. A token canceled before GetSnapshotAsync starts performs no build.
Once a shared build is running, a request token cancels only that caller's wait; it does not cancel
work needed by other callers or poison the shared task. The builder itself accepts a separate
operation-lifetime token and passes it through source refresh, source enumeration, and moderation
refresh waits. Production DI binds that token to application shutdown and a three-minute catalog
operation limit; the HTTP acquisition client also has a 60-second request timeout. A canceled or
failed candidate is never published. Initial failure is retryable; refresh failure is reported to
the refresher while the last known good snapshot remains available to readers.
Characterize before changing¶
- Add executable characterization tests for every current source,
MultiDictunion behavior, source failure/retry behavior, membership, selection, Letter Golf generation, and deny checks. - Pin representative catalog fixtures for unit tests; normal tests must not depend on GitHub or a million-word network download.
- Capture the overload that drops theme/language and the code-unit length checks, then introduce correct behavior through the new contract/adapter. Do not silently alter an existing call path; every intentional behavior change gets its own regression test and migration note.
- Introduce an injected deterministic random source for tests; remove dependence on one global
static seeded
Randomwithout making generated Dailies unreproducible.
Extract the shared content pipeline¶
- Define a raw-source contract with source ID, language coverage, version/fingerprint, provenance/license, retrieval policy, cancellation, and structured failure.
- Replace the static downloader with an injected loader using explicit timeouts and bounded retry only for transient operations. Validate format and minimum expected content before publishing a snapshot; keep the last known good snapshot on refresh failure.
- Normalize case and Unicode using a language-aware policy. Store display and grid forms separately and segment cell units through a language-specific grapheme service.
- Build one immutable
WordCatalogSnapshotper language/content version. Load and refresh it single-flight, swap atomically, and publish its version with every derived puzzle. - Preserve source-native scores rather than pretending scores from unrelated sources share one scale. Record third-party notices and verify the rights of each current source.
- Move suite-wide and
appliesTomoderation decisions into the catalog build. Keep an authoritative submission-time check as defense in depth, without returning or logging matched denied content.
Add per-game views without duplicate corpora¶
- Define a composable eligibility query/profile over catalog metadata: language, form kinds, game/mode, minimum source/editorial quality, theme, frequency/familiarity, and content-policy version.
- Express today's Letter Golf acceptance as a named profile and add an initial Reverse Cross profile capable of representing the existing fixtures. A Reverse Cross exception must never silently broaden Letter Golf validation.
- Have game indexes reference catalog entry IDs and immutable grapheme data. Cache derived indexes by catalog version plus profile/options fingerprint; drop them atomically after snapshot refresh.
- Keep Letter Golf's signature/count-trie and generation options under a Letter Golf generation namespace/folder. Move files only in coherent, reviewable commits and avoid behavior changes in pure organization commits.
Keep lexical metadata dimensions separate¶
The initial LexicalForm flags are a provisional admission vocabulary, not the final linguistic
model. In particular, inflection is broader than declension: it includes plural and possessive
forms; verb person, tense, mood, and aspect; participles and gerunds; adjective/adverb comparative
and superlative forms; and language-specific case, gender, number, and agreement. For example,
CATS, RAN, RUNNING, and HAPPIEST can all be inflections. A normalized entry therefore needs
an optional lemma/root reference plus structured, language-aware morphology features; a single
Inflection bit cannot say what changed or identify the base lexeme.
Do not flatten these independent dimensions into one enum:
- Entry shape: a single grid token or a multi-token phrase, with idiom status recorded separately from its physical shape.
- Grammar: noun, verb, adjective, adverb, pronoun, determiner, conjunction, interjection, and other language-specific parts of speech.
- Morphology: lemma/root plus plural, possessive, conjugation, participle, comparison, declension, agreement, or other applicable features.
- Usage and editorial classification: proper name, abbreviation, acronym, foreign term, informal, archaic, topical, and other eligibility-relevant labels.
An exclamation is often a usage of an utterance, while an interjection such as WOW is a lexical
or grammatical classification. Likewise, an interrogative is usually a syntactic or pragmatic
function: WHO or WHAT can be marked with their grammatical roles, but should not automatically
make every occurrence an "interrogative entry." Punctuation is not a blocker. Display form and
grid form remain separate, so a source spelling such as DON'T! may have a normalized grid form
such as DONT when the selected game profile permits that explicit, versioned transformation.
Metadata may be unknown when a source does not provide reliable morphology or grammar. Unknown must remain distinct from false, and ingestion should not guess aggressively. Eligibility profiles can then opt into specific shapes, grammatical classes, morphological forms, and usage labels for Reverse Cross without broadening Letter Golf.
Current scope decision (2026-09-07): Do not add LexicalPartOfSpeech, lemma references,
structured morphology, language metadata, or a typed usage-classification model merely to ingest
the next curated source. Current games do not consume those distinctions, and carrying them would
expand entry contracts, catalog merge/fingerprint logic, evaluation persistence, tests, and
retained memory without changing play. Prepare a compact surface<TAB>forms artifact instead:
collapse ordinary POS codes and their expanded inflections to word, preserve K as
proper-noun, preserve abbr as abbreviation, and union classifications for ambiguous surfaces.
Omit frequency and do not add source-derived tags. The complete rationale, format, deferred-model
definitions, and implementation triggers are recorded in
Lexical and Game Architecture.
Ownership layout¶
Words/
Domain/ lexical entries and source metadata
Normalization/ language normalization and grapheme segmentation
Sources/ source adapters and acquisition
Content/ moderation inputs and eligibility policy
Catalog/ immutable snapshot construction and publication
Views/ per-game projections over a snapshot
Compatibility/ temporary IWords/MultiDict migration layer
Games/
LetterGolf/ domain, content, generation, application, validation
ReverseCross/ domain, content, fixtures, generation (later)
Storage/ Cosmos entities and repositories
Endpoints/ HTTP mapping and public DTOs
This layout is now established. See Lexical and Game Architecture for the current subfolders, compatibility boundary, and future-game pattern.
Observability and safety¶
- Measure cold-load and refresh duration, source failures, accepted/rejected counts by reason, snapshot size, derived-index build time, and active catalog version. Never tag telemetry with a raw rejected entry.
- Bound startup and request-path work. Prefer warm-up/readiness or an immutable packaged/versioned artifact where appropriate, while retaining an observable fallback.
- Treat an unexpectedly tiny, malformed, or unlicensed source as a failed build, not an empty but valid dictionary.
Exit criteria - implementation complete; verification pending¶
- Letter Golf generation consumes the catalog-derived index directly; existing validation callers use a compatibility adapter over the same catalog.
- Deterministic Letter Golf and Reverse Cross integration views resolve from one shared snapshot instance; derived indexes reference catalog entries rather than duplicating the raw string corpus. This does not yet production-wire Reverse Cross.
- Catalog-native language and theme parameters work through explicit policy or are rejected as
unsupported; the legacy
/v1/common-wordsdefault-English behavior remains characterized and backward compatible. - Migrated generation lengths and cell tokens use the shared grapheme abstraction.
- Snapshot versions, source descriptors, and safe catalog/index telemetry are available to operators on the production Letter Golf path; generated puzzle contracts publish catalog and profile versions.
- No Reverse Cross generation algorithm has been added.
- Run the complete backend and frontend suites, lint, type-check, production builds, and representative serialization comparisons.
- Run a focused Letter Golf browser journey covering daily-puzzle load, keyboard input, submission, and victory rendering against a deterministic mock API.
- Compare the generated OpenAPI contract with the trusted pre-cutover baseline.
- Build and run the relevant Docker image locally, then verify liveness and readiness behavior.
- Measure production-sized cold/warm catalog and index duration, memory/GC behavior, source failure and cancellation, refresh/last-known-good behavior, first-request latency, and readiness.
- Complete the explicit dwyl underlying-data rights review before treating the source inventory as commercial-use or redistribution clearance. The review accepts the pinned artifact on the basis of the Moby public-domain grant and documents dwyl's transformation and maintenance in Third-Party Notices.
Verification evidence captured on 2026-08-28:
- Generated OpenAPI at trusted pre-cutover commit
39b3675and current HEAD. After removing the environment-specific server URL, the only change was the approved additive nullablecatalogVersionandcatalogProfileVersionfields onLetterGolfPuzzleResponse.OpenApiCompatibilityTestspreserves that baseline as an executable contract gate. - Ran the opt-in production-source catalog measurement on Windows 10.0.26200, .NET SDK 10.0.400, an Intel Core i7-11800H, and 63.6 GiB RAM. The four pinned sources produced 767,019 merged catalog entries and 378,789 Letter Golf entries. The first validation warm-up request took 17.49 seconds, catalog build activity took 16.01 seconds, warm catalog access took 0.065 ms, index construction took 3.98 seconds, and warm index access took 0.591 ms. Retained managed-memory deltas were about 707.4 MiB for the catalog and 198.1 MiB for the index, with 3,278.3 MiB allocated during the run. These are workstation observations, not portable service-level thresholds.
- Re-ran 30 deterministic catalog builder, provider, and Letter Golf index tests covering minimum
size, source failure, cancellation, coalescing, retry, version replacement, and last-known-good
publication. The external-source measurement remains skipped unless
MINIGAMES_RUN_PRODUCTION_CATALOG_MEASUREMENT=1is set. - Built the pinned multi-stage backend Dockerfile as a local-only 116.4 MiB Linux amd64 image.
The container reached listening in 437 ms and ran as UID/GID 1654 with a read-only root
filesystem, a temporary
/tmp, all capabilities dropped, andno-new-privileges. With Cosmos deliberately pointed at an unavailable loopback endpoint,/health/liveand the Docker health check remained healthy with HTTP 200 while/health/readyreturned HTTP 503Unhealthy; the process remained running. The temporary container and image tag were removed without publishing.
Phase 1 verification is complete. Phase 2 and Phase 3A-3D were subsequently completed as recorded below; production-class generation validation remains a Phase 10 release gate.
Phase 2 - Reverse Cross hardcoded vertical slice¶
Branch: jm/phase2-integration
Keep the current puzzles, but make every layer look like the future generated game. This phase proves the shared catalog, private/public contract boundary, validation, telemetry, and arbitrary dimension model before search complexity is introduced.
Execution progress¶
- Step 1 - migrate the three fixtures (2026-08-28). The 5x5, 7x7, and 9x9 fixtures now have canonical public masks, private solved grids, stable ordered entries, and explicit slot-to-entry placements. Fixture construction runs the shared structural validator and fails with typed diagnostics if any authored invariant is broken. The 5x5 and 7x7 layouts and banks are unchanged. The 9x9 layout and its twelve correctly authored Across entries are unchanged, but its copied 7x7 Down suffix was replaced by the twelve Down entries actually formed by the solved grid; the old suffix could not fill the 9x9 slot geometry and therefore could not be represented as a valid fixture. Focused parser, validator, and fixture tests passed 37/37.
- Step 2 - enforce catalog eligibility (2026-08-28). A versioned, first-party MIT lexical
source now contributes all 48 unique fixture entries to the same shared catalog snapshot used by
the existing sources. The Reverse Cross profile admits that source, and fixture resolution fails
if any entry is absent from its eligible view. Proper nouns, abbreviations, acronyms, phrases,
idioms, inflections, foreign terms, normalized spacing, and normalized punctuation are explicit
forms/tags; this includes
PDFS,ERDRICH,ONA, andONTHEDL. Display strings remain unchanged because the current English normalization contract deliberately preserves spaces and punctuation. Focused source metadata, catalog resolution, DI composition, and fixture tests passed 17/17. - Step 3 - replace the legacy generator (2026-08-28). The synchronous
IReverseCrossGenerator/TestReverseCrossGeneratorprototype and hardcoded model builders were removed.IReverseCrossPuzzleProvidernow returns a public puzzle with its private solution, andReverseCrossPuzzleOptionscarries independent dimensions, language, profile, requested difficulty/theme placeholders, and an optional deterministic seed. The fixture provider propagates cancellation through catalog resolution, rejects unsupported options explicitly, validates configured row/column limits, and selects exact or random eligible fixtures. The production provider now uses this boundary asynchronously. Focused Reverse Cross and production-composition tests passed 107/107. - Step 4 - add public mapping (2026-08-28). The typed response contains provider identity, language, independent dimensions, catalog/provider versions, nullable difficulty/quality fields, explicit public cell kinds, and stable entry IDs with display/grid/grapheme forms; it cannot reference private solved cells or placements. The frontend validates the untrusted payload before using it. Backend endpoint tests covered all fixture sizes; frontend contract tests, ESLint, TypeScript, backend build, formatting, and editor diagnostics were clean.
- Step 5 - complete platform seams (2026-08-28). The fixture provider, catalog resolver,
structural validator, and public mapper now emit correlated
ReverseCross.FixtureSelection,ReverseCross.CatalogResolution,ReverseCross.Validation, andReverseCross.PublicMappingactivities through the shared OpenTelemetry source. Tags are limited to game/mode/language/profile identity, catalog/provider versions, dimensions, bounded counts, deterministic-selection state, response format, and status/error type; fixture identity, answer text, solved cells, placements, and exception messages are excluded. A dormantReverseCrossPuzzleEntitydefines the existing puzzle identity/discriminator fields with separate public puzzle and private construction-proof payloads, without adding a Cosmos store method or write path. The shared play envelope gained an optional, null-omitted Reverse Cross placement payload keyed only by stable slot and entry IDs, preserving serialized Letter Golf documents.IReverseCrossPlayValidationServicedefines a pure future validation boundary and non-spoiling result codes over an already resolved public/private puzzle pair; it is not registered or implemented. No Daily/Practice lifecycle, persistence, autosave, timing, submit, score, stats, or group behavior was added. The affected Reverse Cross and Letter Golf serialization slice passed 116/116 tests; formatting and editor diagnostics were clean. - Step 6 - close contracts and gates (2026-08-28). The generated OpenAPI document and its executable compatibility gate lock the typed non-spoiling puzzle contract, the absence of solution and placement properties, and the independently reviewed document fingerprint. Review follow-up cached immutable authored fixtures in the singleton resolver so parsing and first-pass validation do not repeat per request, and expanded telemetry checks across every selected entry form. The focused review slice passed 28/28 tests. Final gates passed 664 backend tests with one existing skip, 433 frontend tests across 49 files, ESLint, explicit-project TypeScript checking, the Next.js production build, C# formatting, and editor diagnostics. All six browser journeys passed in both desktop and Pixel 7 Chromium configurations (12/12); they emitted only the existing brand-image aspect-ratio warning. No merge, push, deployment, Azure/Terraform mutation, or production feature flag change was performed.
Domain and contracts¶
- Separate fixture construction, domain puzzle, persisted internal solution, public response, and endpoint mapping. Remove hardcoded builders from the persistence/public model.
- Replace
char/sentinel cells with explicit cell types and grapheme strings. ModelRowsandColumnsindependently and validate configured size limits at the boundary. - Give every entry and slot a stable ID. Store display form separately from grid form and never key state solely by answer text.
- Define an asynchronous, cancellable provider interface and an options record containing
dimensions, language, profile, requested difficulty/theme placeholders, and deterministic seed.
Its Phase 2 implementation is a fixture provider, not a generator. Rename the current
IReverseCrossGenerator/TestReverseCrossGeneratorpair toIReverseCrossPuzzleProvider/ReverseCrossFixtureProviderwith that contract change; reserveReverseCrossGeneratorfor the later construction/search algorithm. - Include non-spoiling metadata on the public puzzle: puzzle key when persisted, language, dimensions, content version, fixture/generator version, and nullable difficulty/quality fields. Keep solved cells and placements in the private representation.
Fixture parsing and validation¶
- Create one canonical parser for hand-authored layouts and a slot extractor used by fixtures, future generation, server validation, and tests.
- Validate at build/test time that all existing fixtures have legal runs, matching crossings, in-bounds placements, exact slot lengths, no missing or repeated entry IDs, and a complete private solution.
- Resolve every fixture entry through the Reverse Cross catalog profile. Any exception for a name, abbreviation, or phrase is an explicit tagged/catalog decision, not a bypass.
- Add malformed-fixture tests and property assertions. Preserve the deployed fixture rotation and public behavior unless an existing fixture cannot be represented safely.
Platform-ready seams¶
- Add a Reverse Cross puzzle discriminator and game-specific payload behind the shared puzzle storage boundary without making Letter Golf's schema less compatible.
- Define the eventual play payload and validation service interfaces, but do not implement Daily, autosave, timing, or stats yet.
- Add structured spans for fixture selection, catalog resolution, public mapping, and validation; include versions, dimensions, and counts, never answer content.
- Generate/update OpenAPI and add endpoint contract tests so the frontend migration can be additive.
- Keep a feature-flagged rollback to the existing response mapping until the new client contract is verified.
Exit criteria¶
- The same hardcoded puzzles remain playable, now selected through an async fixture provider over an arbitrary row/column model.
- Every served fixture is proven internally consistent and catalog-eligible before it can ship.
- The public response contains no private solution or placement data.
- Letter Golf and Reverse Cross share catalog memory, moderation, language/grapheme primitives, identity conventions, and telemetry plumbing while retaining game-specific domain logic.
- No fill, mask, or puzzle-generation search has been implemented.
Phase 3 - Basic on-demand puzzle generation¶
Branch: feat/reverse-cross-generator
The Phase 3A design decision is recorded in ADR 0001. The two historical mask-generator exports remain input to Phase 3C rather than a preselected algorithm.
Subphase status¶
| Subphase | Status | Outcome |
|---|---|---|
| 3A. Design and measurement foundation | Complete | Versioned bounded options, replay identity, scalar measurement contracts, an opt-in production catalog/view measurement, and ADR 0001. |
| 3B. Fill known masks | Complete | Native bounded MRV fill reuses a bulk-built positional catalog index and solves the validated 5x5/7x7/9x9 matrix deterministically. |
| 3C. Construct masks | Complete | Deterministic structural candidates use fair shares of global time/node budgets for measured fillability feedback. |
| 3D. Production integration | Complete | Validated on-demand generation uses one version-keyed index, bounded concurrency, safe telemetry, and fixture fallback behind a default-off feature flag. |
Required contract, independent of the chosen algorithm¶
- Introduce versioned
ReverseCrossGenerationOptionswith independent rows/columns, entry profile, seed, time/attempt budget, minimum/maximum slot length, and initially nullable quality knobs. - A deterministic seed plus catalog/content version, generator version, and complete options must reproduce the same candidate or a documented failure.
- Generation is asynchronous and cancellable, with a hard wall-clock/attempt budget and structured failure reasons. No unbounded recursion or retry loop runs on a request thread.
- Build the complete private solution first, then derive the public mask and shuffled entry bank. Solvability is a construction invariant, not a hopeful postcondition.
- Validate every emitted puzzle independently: dimensions and cells; legal maximal slots; catalog eligibility; grapheme lengths; agreeing crossings; complete entry/slot coverage; connectivity and checked-cell rules selected by the ADR; and at least one reproducible solution.
- Accept every rule-valid reconstruction. Treat the generated private solution as a solvability witness, and leave alternate-solution discovery to God View/editorial tooling.
Evaluation harness before optimization¶
- Benchmark cold and warm catalog/index states separately across a matrix of rectangular and square sizes. Record p50/p95/max generation time, attempt/backtrack counts, rejection reasons, allocations, slot metrics, and success rate.
- Add seed-based regression cases and property/fuzz tests so every production failure can be replayed.
- Establish an initial service objective after measurement: normal on-demand requests complete in seconds with a bounded tail and a clean timeout/fallback, never minutes.
- Compare candidate solution-first, mask-first-with-fillability-feedback, constraint-programming, and hybrid approaches against the same harness rather than choosing on elegance alone.
- Remove avoidable duplicate ownership and transient allocation amplification before sizing the container. Measure baseline, retained views/indexes, bounded generation peaks, representative concurrency, startup, and headroom; increase replica memory when the remaining requirement is demonstrated rather than treating the private-beta 0.5-1 GiB allocation as an absolute ceiling.
- The Phase 3A workstation baseline retained approximately 817.9 MiB of managed catalog and game views, ended at a 979.0 MiB process working set, and observed a 1,157.5 MiB post-catalog checkpoint. Use at least 2 GiB for the next production-container benchmark; do not call that allocation final until Phase 3B fill and concurrency measurements establish its headroom.
Phase 3B measured result¶
- Implemented deterministic MRV backtracking for fixed validated masks with distinct structured outcomes for success, no-fill, invalid options, validation failure, node/time limits, and caller cancellation. Successful candidates are independently validated before return.
- Rejected the length-bucket-only baseline after its 5x5 p95 reached approximately 2,676 ms and all three 7x7 attempts reached the 10-second limit against the 567,657-entry Reverse Cross view.
- Added one reusable positional index for supported lengths 3-9. It bulk-builds mutable posting lists and freezes them into catalog-entry reference arrays and flat integer arrays. It does not clone lexical content or perform persistent immutable-tree insertion per catalog entry.
- A 2026-08-28 isolated Release run indexed 243,643 entries and 1,758,867 grapheme positions in 294.1 ms, allocating 33.3 MiB and retaining approximately 8.7 MiB after full GC. Post-index process working set was 1,006.0 MiB.
- With seed 1729, a 10-second limit, and a 100,000-node limit, all three measured attempts succeeded for every fixture. The 5x5, 7x7, and 9x9 p50/p95 values were 66.4/69.5 ms, 572.2/604.0 ms, and 116.4/121.5 ms respectively; the largest search used 708 nodes and 694 backtracks.
- The result accepts native indexed fill for Phase 3B and clears Phase 3C experimentation. It does not establish mask-generation performance, concurrent-request headroom, production-container behavior, or a final memory allocation.
Phase 3C measured result¶
- Added deterministic mask candidates keyed by complete generation options, seed, and attempt. Candidates enforce legal slot lengths and open-cell coverage before fill; exact blocked density, checked-cell ratio, and open-cell connectivity remain optional quality inputs rather than fixed presets.
- Added an outer result and generator that aggregate attempts, nodes, backtracks, and slot counts, preserve the Phase 3C replay identity, re-stamp successful puzzles with the outer generator version, and rely on Phase 3B's independent final validation.
- Rejected the first orchestration policy after all three generated 9x9 samples spent the full 10-second global budget on the first candidate. The accepted policy gives each remaining mask a fair share of remaining time and nodes, then continues after that local slice is exhausted while retaining hard global limits and immediate cancellation.
- In an isolated Release run against the pinned 767,019-entry production catalog, all three seeds (1729, 2718, and 3141) succeeded for 5x5, 7x7, and 9x9 with 25 mask attempts, 10 seconds, and 100,000 total nodes. P50/p95 generation was 30.0/40.2 ms, 432.5/497.2 ms, and 991.6/993.1 ms, respectively. Maximum attempts were 1/2/3, maximum nodes were 14/539/1,040, and measured total allocations were 0.2/0.7/3.3 MiB.
- The shared positional index remained unchanged: 243,643 entries and 1,758,867 references, bulk-built without per-entry persistent immutable trees or lexical-content copies. The run retained approximately 8.7 MiB for that index and observed a 1,005.9 MiB post-index process working set.
- At the Phase 3C checkpoint, production serving integration, feature-flagged fallback, concurrency, Azure container measurements, and product quality presets remained. Phase 3D has since completed serving integration, fallback, and bounded per-process concurrency; Azure measurements remain Phase 10 work and quality presets remain Phase 7 work.
Phase 3D production integration result¶
- The production puzzle provider now selects validated generation behind the
separate
ReverseCrossGenerationserver-side feature flag. An absent, disabled, or failed flag evaluation returns the existing fixture path without requesting the generation index. The flag remains absent from checked-in configuration and therefore defaults off until an operator creates and targets it in Azure App Configuration. - Generated requests without explicit dimensions deterministically select a supported 5x5, 7x7, or 9x9 preset from the generation seed. Other production defaults are five seconds, 25 mask attempts, 100,000 total search nodes, slot lengths 3-9, no quality preset, and at most two admitted generation requests per process. Bounds are startup-validated. Requests above the concurrency limit return a fixture immediately instead of queuing additional generation work.
- One singleton fill-index provider coalesces builds by language, catalog/profile version, and length bounds. It preserves the Phase 3B flat posting arrays and catalog entry references, publishes replacements only after complete construction, evicts failed builds for retry, and prevents one canceled caller from canceling shared index construction.
- Successful generation retains the unchanged public response contracts and independently validated private witness. The public provider ID is a stable SHA-256 identity over the complete replay contract. Traces record scalar replay inputs, catalog/generator versions, bounded outcome, elapsed time, attempts, nodes, backtracks, and slot count without lexical content or the private solution.
- Bounded no-fill/time/node/attempt outcomes, catalog or generation errors, and concurrency rejection return fixtures. Caller cancellation is propagated and never converted to a fixture. Focused tests cover flag-off behavior, generation success, fallback, cancellation, concurrency, safe telemetry, replay IDs, index reuse, catalog-version replacement, and failed-build retry.
- This completes Phase 3D implementation. Persistence is complete in Phase 4; product quality presets remain Phase 7; representative load and Azure container startup, tail-latency, memory, and replica sizing evidence remain required before staged release in Phase 10.
Historical ideas to test, not requirements¶
- Rotational or diagonal symmetry;
- minimum slot length of three;
- per-row/per-column coverage and whole-grid connectivity;
- black-cell density bands;
- symmetry-aware mask mutations and bounded random retries.
Each can improve or harm fillability, ambiguity, visual balance, and runtime. Keep them as measured options until play data justifies presets.
Exit criteria¶
- The production provider can produce independently validated, unthemed puzzles under explicit time, attempt, node, dimension, and concurrency bounds.
- Generation replay identity includes the seed, complete options, content version, and generator version; successful results retain their private solution witness.
- Failures are observable and reproducible; generated serving is default-off and feature-flagged, with tested fixture fallback.
- No themes or editorially rich entry forms are required for this milestone.
- Validate cold/warm startup, representative load, tail latency, memory, and replica sizing on the production container class before enabling generated serving. This remains in Phase 10.
- Persist replay metadata and private solutions when Daily/Practice puzzle persistence is added in Phase 4.
Phase 4 - Daily, Practice, play persistence, and timing¶
Completion branch: phase-4/tests-complete
Step 6 completion - Puzzle persistence telemetry and measurement plan (2026-08-29)¶
Status at this checkpoint: Puzzle persistence Steps 1-6 complete. Play lifecycle and authoritative timing were pending.
- Telemetry instrumentation (2026-08-29). Four production classes now emit safe, low-cardinality activities:
ReverseCross.Daily.GetOrCreate: Daily puzzle lifecycle withcache.hit,path(cache_hit/generated), dimensions, and version tags.ReverseCross.Practice.CreateNew: Practice creation distinguishing server/client key source and cached/generated paths.ReverseCross.Daily.PreGenerate: Summary activity recording attempted, success, and failure counts, elapsed time, and status.ReverseCross.Storage.ReadandReverseCross.Storage.CreateIfNotExists: Cosmos point operations recording request charge, status code, and conflict-winner path. All tags exclude puzzle keys, dates, seeds, entries, solutions, placements, and user input.- Focused telemetry tests (2026-08-29). Added deterministic activity-capture assertions covering:
- Daily cache-hit metadata and Practice generated/cached paths.
- Daily pregeneration partial-failure and cancellation summaries.
- Cosmos read/create/conflict status and request-charge propagation.
- Privacy/cardinality assertions: no activity tag contains puzzle keys, dates, identifiers, or sensitive data.
- Measurement runbook and decision record (2026-08-29). Created
doc/phase4-pool-measurement-plan.mddocumenting: - Telemetry infrastructure and activity names/tags.
- On-demand P95 latency thresholds: <3s no pool, 3-10s optional, >10s required.
- Daily freshness target >99%, steady-state <120s, request-rate 5 RPS, container headroom 500 MiB, throttle rate <5%.
- Locally measured evidence: 5x5/7x7/9x9 fixed seeds all succeeded; observed sample maxima were 15.4 ms, 667.5 ms, and 1,281.8 ms respectively.
- Staging-only measurements: real Cosmos RU, concurrent load, TTL cleanup, container growth, player behavior.
- Provisional decision: No general Practice pool now. Nine local generation samples spanning 5x5/7x7/9x9 all succeeded, with a worst observed sample of 1,281.8 ms for 9x9. Revisit at p95 >= 3s; require a pool or equivalent change above 10s, or if deployed reliability/resource thresholds fail.
- Roadmap update (2026-08-29). Updated Phase 4 status to document Step 6 completion and cross-reference the measurement plan. Phase 10 gates any pool implementation on deployed-environment evidence.
Historical note: Play endpoint orchestration and timing were unfinished at this Step 6 checkpoint. They are now complete in play lifecycle Steps 1-9 below, and Phase 5 can consume the resulting APIs in the production UI.
Play lifecycle implementation sequence¶
| Step | Scope | Status |
|---|---|---|
| 1 | Finalize play rules and contracts | Complete (2026-08-29) |
| 2 | Complete the shared play storage model | Complete (2026-08-29) |
| 3 | Implement idempotent Start | Complete (2026-08-29) |
| 4 | Implement revision-guarded autosave and resume | Complete (2026-08-29) |
| 5 | Implement Practice pause/resume and abandonment | Complete (2026-08-29) |
| 6 | Implement authoritative, idempotent completion | Complete (2026-08-29) |
| 7 | Enforce competition, ownership, and spoiler boundaries | Complete (2026-08-29) |
| 8 | Add endpoint integration and contract coverage | Complete (2026-08-29) |
| 9 | Run the Phase 4 completion gate | Complete (2026-08-29) |
Play lifecycle Step 1 - Rules and contracts (2026-08-29)¶
Status: Complete. Endpoint orchestration starts after the shared storage model is complete.
NotStartedis an explicit API/domain state returned before a play document exists. Fetching or preloading a puzzle never creates a play or starts its clock.- Start transitions
NotStartedtoInProgressand is idempotent.CompletedandAbandonedare terminal; retries return the existing terminal state rather than reopening the play. - Board mutation and completion are allowed only while a play is active,
InProgress, and not paused. - Daily and Practice play can pause and resume while
InProgress; pause is orthogonal to lifecycle status rather than a fifth lifecycle state. Server-providedcanPausecan disable pause for a future timing policy. - Public contracts carry stable slot/entry assignments, an expected board revision for mutations, server timing anchors, accumulated active duration, and lifecycle timestamps. They do not expose Cosmos ETags or private solution data.
Play lifecycle Step 2 - Shared play storage model (2026-08-29)¶
Status: Complete. No data migration or container change is required.
- The shared play envelope now supports nullable server-owned
startedAtandabandonedAtlifecycle timestamps. - Existing Cosmos status ordinals remain stable (
InProgress=0,Completed=1); additiveNotStarted=2andAbandoned=3values preserve legacy documents.NotStartednormally remains a projected state rather than a stored document. - The versioned Reverse Cross payload stores stable placements, a monotonic board revision, the current active or paused timing anchor, and accumulated active milliseconds. Missing fields in legacy documents retain safe zero or null defaults.
- Atomic
IPlayStore.CreateAsyncmakes the first Start race-safe: one create wins and a duplicateplayKeyproduces a Cosmos conflict for the caller to re-read. Existing Cosmos reads return the current ETag, and later saves apply it withIfMatchEtagin the sameplayKeylogical partition.
Play lifecycle Step 3 - Idempotent Start (2026-08-29)¶
Status: Complete. POST /v1/reverse-cross/{puzzleKey}/play/start is the only transition that creates a play.
- Start verifies that the persisted Reverse Cross puzzle exists, resolves the caller only from the signed user
cookie, and atomically creates an
InProgressplay with server-ownedstartedAtandactiveSincetimestamps. - Repeated Start calls return the existing state without changing its board, timing, or lifecycle. Completed and abandoned plays remain terminal.
- Concurrent first Starts use Cosmos create-only semantics. The loser of a
409 Conflictre-reads and returns the winning document rather than replacing it.
Play lifecycle Step 4 - Revision-guarded autosave and resume (2026-08-29)¶
Status: Complete. GET and PUT /v1/reverse-cross/{puzzleKey}/play expose restore and autosave.
- GET projects
NotStartedwithout creating a document and otherwise returns the persisted placements, revision, lifecycle, and server timing anchors without exposing an ETag or private solution. - PUT requires the current
expectedBoardRevision; a successful mutation increments it exactly once. An identical stale retry is idempotent, while a divergent stale request returns409with the authoritative current state. - Autosave accepts incomplete or currently incorrect arrangements so they can be restored and corrected. It rejects blank, unknown, or repeated slot/entry identities, and cannot mutate paused or terminal plays.
- Cosmos ETag preconditions remain the final write guard. A losing writer re-reads the winner and returns either an idempotent success or revision conflict instead of overwriting newer state.
Play lifecycle Step 5 - Pause/resume and Practice abandonment (updated 2026-08-31)¶
Status: Complete. Revision-guarded pause, resume, and abandon actions are persisted server-side.
- Daily and Practice pause close the current active segment into accumulated milliseconds and record
pausedAt; resume clears that pause anchor and starts a new active segment without counting paused wall-clock time. - Board autosave remains disabled while a play is paused. Daily pause is interruption-tolerant; a future Strict or
Tournament policy can return
canPause=falsewithout changing the lifecycle contract. - Abandon is available from active or paused
InProgressplay, closes any active timing segment, clears timing anchors, recordsabandonedAt, and makes the play terminal without discarding its board. - Each accepted lifecycle mutation verifies and advances the monotonic board revision and uses the current Cosmos ETag. Repeated actions that already reached their requested state return that state without writing again.
Play lifecycle Step 6 - Authoritative, idempotent completion (2026-08-29)¶
Status: Complete. POST /v1/reverse-cross/{puzzleKey}/play/complete atomically accepts a solved board and time.
- Completion requires an active, unpaused
InProgressplay and the current expected board revision. The submitted placements must use every public entry and maximal slot exactly once, match slot lengths, and agree at crossings. - Validation uses only public puzzle geometry and the shuffled entry bank. A valid reconstruction is accepted without comparing placements to the persisted private construction witness.
- The accepted write persists final placements, advances the revision once, closes the current active segment into
accumulated milliseconds, clears timing anchors, records server-owned
completedAt, and becomes terminal. - Repeated completion returns the original persisted result without restamping time. An ETag loser re-reads the winner and returns it only when that winner completed; other concurrent mutations return a revision conflict.
Play lifecycle Step 7 - Competition, ownership, and spoiler boundaries (2026-08-29)¶
Status: Complete. Current Phase 4 trust boundaries are explicit and executable.
- Every play read derives its composite key from the signed-cookie user and requested puzzle. Loaded documents and race winners must also match that expected document ID, play key, user ID, and puzzle key before projection or mutation, preventing a mismatched stored record from crossing an ownership boundary.
- Normal Reverse Cross puzzle responses continue to map only public mask, metadata, and entry-bank fields; the persisted private construction witness is not part of any gameplay contract.
- The shared stats policy rejects Practice and solution-viewed completions before profile I/O, with explicit Reverse Cross coverage. Reverse Cross does not publish Letter Golf-shaped score or group updates; duration-aware personal and group competition remains Phase 6 scope.
Play lifecycle Step 8 - Endpoint integration and contract coverage (2026-08-29)¶
Status: Complete. The public HTTP lifecycle is covered through the production route and service composition.
- Real-service
WebApplicationFactorytests exercise NotStarted projection, Start and repeated Start, partial autosave, Practice pause/resume, completion and repeated completion, abandonment and repeated abandonment, and terminal-board rejection against ETag-aware in-memory stores. - Integration coverage verifies server-owned active duration across a paused interval, cookie-isolated play keys, rejection of tampered cookies, and rejection of every play route when only a forged identity header is supplied.
400,404, and409mappings cover malformed bodies, invalid placements, missing puzzles, missing plays, divergent stale revisions and terminal mutations. Public puzzle and play JSON is checked for its typed schema and absence of private solution fields.- OpenAPI compatibility assertions now cover the method, request schema, success schema, and documented status set for Start, GET/PUT play, pause, resume, abandon, and complete without changing the trusted canonical fingerprint.
Play lifecycle Step 9 - Phase 4 completion gate (2026-08-29)¶
Status: Complete. Phase 4 is ready to hand its stable backend contracts to Phase 5.
- A clean Release restore and solution build compiled both the API and test projects with no warnings or errors.
- The complete backend suite passed 888 tests: 887 passed, one existing test was skipped, and none failed. This run includes puzzle persistence, Cosmos concurrency, play lifecycle, endpoint integration, cookie ownership, spoiler boundaries, and OpenAPI compatibility coverage.
- An explicit Letter Golf and legacy play-endpoint regression slice passed all 101 tests, confirming that the shared play-envelope and Reverse Cross endpoint work did not regress the existing game.
- Whole-solution
dotnet format --verify-no-changes, editor diagnostics,git diff --check, and clean-worktree checks passed. The approved OpenAPI fingerprint remains unchanged from Step 6.
Puzzle lifecycle¶
- Implement
reversecross|global|{yyyy-MM-dd}Daily keys using the same Pacific-time date service as Letter Golf. Fetch is idempotent and does not start play. - Implement
reversecross|practice|{shortid}Practice keys, expiry/TTL, direct restore, and the same ownership/public-read posture chosen for Letter Golf unless a security review changes it. - Extend the shared puzzle store with a game discriminator and typed game payload/envelope. Avoid a second Cosmos abstraction and avoid adding Reverse Cross fields to Letter Golf models.
- Persist public definition, private solution, generation metadata, and content/generator versions atomically. Never return private solution fields from normal endpoints.
Play lifecycle and authoritative time¶
- Model
NotStarted,InProgress,Completed, andAbandonedexplicitly. An idempotent Start transition records server time and prevents fetch/prefetch from consuming the player's clock. - Persist entry placements and board revision with optimistic concurrency so autosave, multiple tabs, retries, and reconnects cannot silently overwrite newer state.
- The backend validates that placements use the public bank exactly once, fill every maximal slot, and agree at crossings; equality with the private construction witness is not required. It records completion and duration atomically and returns the same completed result on retried submissions.
- Store timestamps and accumulated active duration separately from the displayed rounded time. Client timers interpolate for display only.
- Preserve game-specific play payloads behind a shared envelope. Remove assumptions that every play has Letter Golf words, wildcards, or a word-count score.
Pause policy¶
| Mode | Rule | Rationale |
|---|---|---|
| Daily | Explicit Start; pause/resume allowed when canPause |
Supports interruptions while server-owned active segments remain comparable. |
| Practice | Pause/resume allowed; board and bank hidden while paused | Supports interruption without affecting competitive records. |
Pause waits for pending persistence and hides the board and bank. Visibility loss obscures content immediately and requests a server pause on a best-effort basis; return reconciliation never resumes automatically. Browser visibility does not determine elapsed time, and the web client does not claim to prevent operating-system capture. A future Strict or Tournament policy may disable pause.
Exit criteria¶
- Daily and Practice can be created/fetched without coupling persistence to a specific generator.
- A player can start, autosave, resume, and idempotently complete; the server owns the accepted time.
- Practice results and spoiled/admin-inspected plays are excluded from Daily stats and competition.
- Concurrency, retry, expiration, unauthorized access, and spoiler boundaries have integration tests.
Phase 5 - Production player UI and accessibility¶
Branch: feat/reverse-cross-gameplay-ui
Implementation checkpoints (2026-08-29)¶
- Steps 1-4 complete: public play contracts, stable ID-based board state, URL restoration, and server-gated Start/timing/lifecycle rendering are isolated in reviewed commits.
- Step 5 complete - persisted playable loop: compact direction selection, explicit entry/slot preview and placement, keyboard traversal and removal, autosave/retry/revision reconciliation, authoritative completion, and a small critical Playwright journey.
- Step 6 complete - keyboard and screen-reader hardening: logical roving grid traversal, visible focus, selected/used states, focus restoration, persistent concise live regions, predictable Escape/cancel behavior, and spoiler-free errors.
- Step 7 complete - revision-aware autosave hardening: debounced and serialized placement saves,
explicit Unsaved/Saving/Saved/Offline/Retry states, current expected revisions, authoritative
409replacement, reconciliation announcements, and cancellation-safe timers. - Step 8 complete - Daily/Practice mode management: accessible roving mode tabs, generated Practice keys, URL creation/restoration, distinct expiry and transient-load handling, authoritative abandon and start-another actions, and unsaved-work protection across links, mode changes, reload, and browser history. Practice completion remains free of Daily scoring and sharing language.
- Step 9 updated - Daily and Practice pause/resume: pause waits for synchronized, saved state and server acceptance before hiding the board and bank; pending requests keep both visible but lock mutation. Authoritative responses and conflicts reseed persistence, paused timers stop interpolating, and focus returns to Resume or gameplay. Visibility loss obscures content immediately, waits for in-flight save acceptance before requesting pause, and reconciles authoritative state on return without auto-resume.
- Step 10 complete - authoritative completion hardening: the save-before-complete queue uses the accepted revision, keeps Victory and duration messaging server-authoritative, and locks visible board and bank controls during completion. Failures unlock input with explicit Retry; conflicts restore the authoritative board and support either revision-aware completion retry or a newly edited save.
- Step 11 complete - responsive presentation: rectangular and 5x5/6x6/7x7/8x8/9x9 boards retain 48-pixel cells inside a focusable horizontal scroll region, with 44-pixel controls and no page-level overflow. Desktop, Pixel 7, effective 200% zoom for 8x8 and 9x9, keyboard scrolling, dark theme, forced colors, and reduced motion checks pass. Measurements show browser zoom plus deliberate board scrolling covers the supported sizes, so custom zoom controls are not needed.
-
Step 12 complete - Phase 5 completion gate: the Playwright suite and contract-faithful mock API cover server-gated Start, reload/resume, authoritative autosave conflict replacement, Practice pause/reload/resume, completion, offline Retry, and Pixel 7 keyboard/touch paths. Generated 6x6 and 8x8 Practice journeys additionally cover source/size request propagation, returned dimensions, keyboard placement, autosave, pause/resume, and completion. Reverse Cross and How-to-Play documentation now match the shipped lifecycle and controls. The original Phase 5 frontend gate passed 120 Reverse Cross and 75 Letter Golf tests, 31 combined browser journeys with one intentional desktop skip for the touch-only case, ESLint, TypeScript, mock syntax, editor diagnostics, and the production Next.js build. Manual rendered-state, keyboard-focus, and accessibility-tree review found no blockers; physical screen-reader and device smoke checks remain part of release validation.
-
Reuse
GameHeader, shared identity, feature loading, error/skeleton states, mode controls, and completion presentation where semantics match; keep Reverse Cross language free of golf terms. - Add a pre-start Daily/Practice ready state. Start only after the explicit player action succeeds on the server, then reconcile the visual timer to server state.
- Replace text-keyed entry state and JavaScript code-unit indexing with entry IDs and grapheme arrays.
- Implement autosave status, offline/retry feedback, stale-revision recovery, restoration by URL, expired Practice handling, and safe mode switching with unsaved progress.
- Prototype and playtest entry selection/placement, Across/Down choice, conflict feedback, removal, keyboard traversal, touch targets, focus restoration, screen-reader announcements, and reduced motion. Invalid feedback cannot leak the solution.
- Support rectangular and larger grids using responsive cell sizing plus deliberate scroll/zoom/pan behavior. Test minimum supported mobile viewport and high zoom before setting maximum dimensions.
- When pause is available, hide both board and word bank, persist the server transition, and restore focus predictably on resume.
- Add unit tests for reducer/store logic, component accessibility tests, browser flows for start/save/resume/complete/pause, and visual snapshots for supported dimensions and themes.
Exit criteria¶
- A full persisted puzzle is playable with keyboard, touch, and pointer at supported responsive sizes, including reload and cross-session resume.
- The timer remains visually accurate through latency/retry without becoming authoritative.
- Daily/Practice status and pause rules are understandable before the player starts.
- Automated accessibility and browser checks cover the critical path, supplemented by manual rendered-state, keyboard-focus, and accessibility-tree review. Physical screen-reader and device smoke checks remain a release-environment responsibility.
Phase 6 - Stats, streaks, groups, and competitive timing¶
Branch: feat/revx-group-standings
Status: Complete. Steps 1-13 cover Daily pause, personal duration statistics, streaks, deterministic recomputation, group presence and standings, player-facing presentation, private aggregate telemetry, and the final compatibility gate.
Personal statistics and replay checkpoint (2026-08-31)¶
- Shared profile updates accept typed game results. Letter Golf retains its existing score, wildcard, hole-in-one, and longest-word behavior; Reverse Cross contributes active duration.
- Eligible global Dailies on or after the
2026-08-31statistics epoch incrementgamesStarted. Completion incrementsgamesCompleted; completion rate is derived as completed divided by started. Abandoned Dailies contribute only the start. - Practice, spoiled, invalid-version, pre-epoch, and superseded plays contribute no Reverse Cross statistics or streaks. Malformed historical identities are skipped during replay.
- Best duration is exact. Typical duration uses at most 241 mergeable 15-second histogram buckets, selects the lower median bucket, and returns its midpoint except for the one-hour overflow bucket, which returns its lower bound.
- Reverse Cross streaks advance from eligible Daily completion dates. Live Start and Complete updates run only when the persisted lifecycle transition is new, making retries and concurrent winners idempotent.
- Merge, repair/backfill, reset, and export project persisted plays through the same typed inputs as live updates. Account merge keeps the first completion, ignores already-superseded records, and excludes duplicate Reverse Cross puzzle keys whose persisted version fingerprints differ.
- Normal Daily and Practice play can pause when the server returns
canPause=true. Visibility loss hides puzzle content immediately and requests pause after pending persistence settles; return reconciliation never resumes automatically. Strict/Tournament timing can disable pause later.
Group competition and presentation checkpoint¶
- Step 8 - exact comparison identity. A standing is comparable only when game type, puzzle key, language, difficulty, content version, and generator/provider version all match. Persisted identity remains authoritative during updates and backfill.
- Step 9 - typed results and deterministic ranking. Group standings accept game-specific results. Reverse Cross ranks by exact authoritative milliseconds and gives exact ties the same rank while formatting a friendly duration. Letter Golf retains score ordering, its legacy score field, and dual-write compatibility.
- Step 10 - spoiler-free group presence. Newly accepted Daily starts publish
Playing, and newly accepted completions publishCompletedwith the exact duration. Practice and duplicate transitions do not publish. Backfill exposes lifecycle state and final typed results, never entries, placements, banks, or solutions. - Step 11 - scalable group Today UI. A URL-backed game picker prioritizes current activity while retaining every supported game. It renders only the selected leaderboard and a game-specific action, so unlike scoring systems are never mixed.
- Step 12 - personal stats and private telemetry. The profile and Daily completion views show Reverse Cross best/typical time and streak information, with the full profile also showing started/completed counts and completion rate. Stats and standings activities carry aggregate outcomes and bounded duration buckets only. An idempotent completion retry can replay authoritative plays to repair a failed secondary stats write without double counting. Letter Golf and Reverse Cross completion overlays now share the same centered hierarchy: personalized result, explicit Daily or Practice completion, game-specific metrics, current and best Daily streak, scorecard link, sharing controls, and game-specific group standings links. Reverse Cross consolidates best, current, and typical times into one three-column row and obscures the solved board behind its completion overlay to save vertical space and keep screenshots spoiler-free.
- Step 13 - completion gate. Backend and frontend regression suites cover retries, concurrency, replay, merge, reset, exclusions, comparison identity, exact ties, and Letter Golf compatibility. Desktop and mobile browser journeys cover Reverse Cross lifecycle behavior and the group game picker, URL selection, typed standings, keyboard focus, and responsive reflow.
Exit criteria¶
- One accepted Daily completion updates Reverse Cross stats/streak once under retries.
- Group ranking is deterministic, spoiler-free, and based only on comparable server-owned times.
- Shared screens render game-appropriate labels and never show golf scoring fields for Reverse Cross.
Phase 7 - Difficulty, quality, and fun calibration¶
Branch: feat/reverse-cross-quality
The implemented evaluator contract, report persistence path, synthetic benchmark corpus, private calibration workflow, and future human-feedback boundary are documented in Reverse Cross Evaluator Design.
Do not begin with one hand-tuned Easy/Medium/Hard formula. Persist raw signals first, run
playtests, then publish versioned presets that map to independently adjustable generation and
selection ranges.
Candidate signal families¶
| Family | Candidate signals |
|---|---|
| Structure | Rows/columns, playable cells, slot count, length distribution, long-entry count, crossing density, checked-cell ratio, connected components, symmetry, branching, black-cell ratio. |
| Reconstruction | Valid placement count per entry, early/late branching, concrete and transpose-equivalence-class reconstruction counts, forced placements, constraint propagation, measured solver nodes/backtracks. |
| Lexical | Familiarity/frequency, source score, entry length, rare graphemes, proper-noun/abbreviation/phrase ratios, inflection/root repetition, language-specific ambiguity. |
| Aesthetic | Visual balance, interlock, isolated pockets, unchecked cells, repeated patterns, entry variety, cohesion, novelty. |
| Empirical | Completion and abandon rates, median/p90 time, rejected placements, undo/move count, hint use, replay intent, qualitative rating by cohort/device. |
Work items¶
- Build a deterministic evaluator that returns raw metrics plus named rejection/warning reasons.
- Evaluate every successful generated candidate while full lexical metadata is available. Persist each complete versioned report as a separate, independently readable Cosmos item rather than embedding it in the hot gameplay puzzle document. V1 Daily and Practice reports are durable and independent from Practice puzzle TTL. Keep report storage behind its own interface so retention, sampling, cleanup, or a later dedicated container does not change generation. Never recompute historical difficulty under a changed formula without retaining the original result.
- Add a versioned synthetic known-good/known-bad evaluator corpus with complete metric
fingerprints and readable finding-code contracts. Keep authorized manually transcribed
calibration examples under ignored
.local/infrastructure; never commit or redistribute them. - Add replay-versioned
IndependentV1andSymmetryPreferredV2mask strategies. Preserve the original strategy for rollback, prefer rotational blocking without requiring exact symmetry, and gate fully checked, connected generation behindReverseCrossStructuralQuality. - Add bounded deterministic structural cohorts over fixed seeds for 5x5, 7x7, and 9x9, plus production activity tags for checked ratio, unchecked cells, connected components, and rotational mismatch pairs. Treat these as engineering and rollout evidence, not human quality calibration.
- Before alternate-board multiplicity affects quality, difficulty, selection, or rejection,
version reconstruction analysis to retain the raw concrete-board count and add a distinct count
modulo valid Across/Down transposition. Cover an open square with
2 concrete / 1 modulo transpose, a genuinely ambiguous puzzle with more than one equivalence class, and masks or rules for which transposition is not an equivalence. - Add abbreviation-aware filler controls and classify rotational, horizontal-only, vertical-only, multi-axis, and asymmetric masks without treating rotational symmetry as a validity requirement. Track implementation and acceptance evidence in issue #80.
- Add a playtest dashboard/export. Segment results by dimensions, language, experience cohort, and input device while respecting telemetry privacy.
- Treat "fun" as a rubric and ranking problem. Automated scoring can reject obvious poor candidates and prioritize a queue, but playtesting/editorial review owns claims such as clever, elegant, quirky, cohesive, or topical.
- Introduce feature-flagged presets only after enough data exists. Keep every underlying knob available to experiments and record the full options fingerprint on the puzzle.
- Decide whether hints, mistakes, pause, or alternate reconstruction affect difficulty labels, competitive eligibility, or merely result annotations.
Decoy-entry experiment¶
Treat extra bank entries that are not required by the construction witness as a complete, independently releasable difficulty feature rather than part of God View or the initial generated puzzle rollout. The current contract requires every bank entry to be used exactly once; a decoy experiment must deliberately version that rule so completion instead requires every slot to be filled, every selected entry to be used at most once, and all crossings to agree while allowing unused bank entries.
- Select decoys only from lengths present in the puzzle's slots and from the same language, normalization, content-quality, and moderation policy as the playable bank. Reject duplicate entry IDs and grid forms.
- Model decoy count as an explicit difficulty knob, beginning with a zero-decoy control and small measured cohorts rather than coupling it to board size or a named preset implicitly.
- Run bounded fixed-mask, fixed-bank solution analysis after adding decoys. Persist total/alternate reconstruction counts when exhaustive, or the search cap and truncation state when not, so decoys do not introduce unexplained ambiguity.
- Measure completion time, abandon rate, placement changes, perceived fairness, and qualitative fun separately from generator runtime. More candidate entries are not automatically better or harder.
- Roll out behind a dedicated server-enforced feature flag, initially in Practice for targeted playtesters. Preserve an immediate zero-decoy rollback path, and do not mix flagged and unflagged Daily results in one competitive cohort.
- Update public puzzle/play contracts, authoritative validation, instructions, accessibility copy, analytics, tests, and puzzle fingerprints together when the experiment is implemented.
Exit criteria¶
- Presets have documented target bands, evaluator version, benchmark evidence, and rollback.
- Generator runtime difficulty and player-observed difficulty are measured separately.
- Quality gates reject known-bad regression seeds without eliminating controlled novelty.
Phase 8 - Rich entries, themes, and editorial workflow¶
Branch: feat/reverse-cross-content
This phase builds on the platform roadmap's Content Governance work. It does not relax Letter Golf rules and does not treat all strings in a crossword list as equally publishable.
Content forms and policy knobs¶
- Add explicit eligibility options for proper nouns, pronouns, conjunctions, abbreviations, acronyms, inflections, multiword phrases, idioms, foreign terms, titles, and topical entries.
- Preserve display and grid forms, spacing/punctuation transformations, locale, capitalization, and rationale for any editorial override.
- Compose form limits with difficulty and theme profiles; for example, cap abbreviations rather than toggling an entire source on or off.
Sources and rights¶
- Continue evaluating the Crossword Nexus Collaborative Word List as a scored crossword source.
Its public repository describes a
word;scorelist with more than 425,000 entries and an MIT license. The shared catalog now acquires a pinned version with bundled notice and validation; Phase 8 still needs Reverse Cross eligibility, moderation, and documented score interpretation. See the source repository. - Prefer first-party curated packs and sources with explicit commercial redistribution/use rights. Candidate proper-name, phrase, idiom, and topical corpora require a written provenance/license, freshness, bias, safety, and removal review before code depends on them.
- Never scrape or republish another publisher's clue/answer archive. Use current commercial games for interaction and quality comparison, not as an unlicensed content feed.
Themes and editorial workflow¶
- Model a theme pack with stable ID/version, language, title/reveal policy, relationship description, eligible entries, supporting-fill policy, provenance, editorial owner, moderation state, and optional topical expiry.
- Build CLI/job-based import, validation, diff, review, approve, publish, rollback, and audit flows; no unauthenticated public content write endpoint.
- Require a theme to survive both construction and player review. Because entries are given up front, reject themes whose relationship makes placement trivial or whose supporting fill feels arbitrary, offensive, or stale.
- Maintain suite-wide denies and game-specific overrides at both ingestion/generation and authoritative validation. Record counters/reasons, never denied text in logs.
The broader LLM-assisted categorization, moderation, lexical expansion, and timely-theme direction is tracked in LLM-Assisted Content Enrichment and Theming.
Exit criteria¶
- A reviewed content version can selectively enable rich forms for Reverse Cross while Letter Golf acceptance remains unchanged.
- Every published entry and theme has traceable provenance, rights, policy state, and rollback.
- Themed generation meets the same bounded runtime and validation contract as unthemed generation.
Phase 9 - Language and grapheme expansion¶
Branch: feat/reverse-cross-languages
- Register normalization, segmentation, casing, comparison, alphabet/script, spacing, and display
rules by language rather than treating
langas an ignored string. - Count and place grapheme clusters, not UTF-16 code units. Test combining marks, composed/decomposed
forms, diacritics, and scripts where one visible cell is not one
char. - Define whether diacritics are significant, stripped, or optionally displayed per language. A normalization decision is versioned and shared by generation, client rendering, and validation.
- Make direction/layout and accessibility work for RTL and bidirectional content before advertising support for those locales.
- Build language-specific catalogs, moderation, frequency/familiarity signals, quality thresholds, and benchmarks. Do not rank players together across incomparable language/content profiles.
- Localize instructions, timer/status language, errors, share text, and metadata; use locale-aware formatting without translating entry display forms accidentally.
Exit criteria¶
- Each enabled language has an approved source/content policy, native-speaker/editorial review, grapheme property tests, generator benchmarks, and end-to-end browser coverage.
- Puzzle identity and standings include the language/profile needed for fair reproducibility.
Phase 10 - Generation operations and staged release¶
Branch: feat/reverse-cross-operations
- Establish production service objectives from Phase 3/7 measurements: warm and cold generation latency, success rate by preset/size, memory, source/index health, and bounded failure rate.
- Keep on-demand generation viable. Add scheduled Daily pre-generation and an idempotent lazy fallback using the same persistence contract; add a refillable general puzzle pool only if traffic or tail latency demonstrates the need.
- Daily pre-generation and lazy get-or-create are idempotent over stored puzzle keys. The source decision is made only for missing dates; disabling generation flags affects not-yet-persisted dates only. A full 14-day horizon that was filled from fixtures will naturally show generated Dailies only as new dates enter the horizon, unless reviewed future fixture documents are manually removed.
- Store seed, complete options fingerprint, catalog/content-policy version, generator/evaluator version, and validation outcome so any production puzzle can be replayed offline.
- Refresh catalog snapshots and derived game indexes atomically. A failed refresh keeps the last known good version and alerts operators; it never partially changes a live generator.
- Add admin-only generation preview, diagnostics, quarantine, approve/reject, regenerate, and rollback tools. Solution inspection is spoiler-sensitive and audited.
- Ship behind feature flags by mode: internal corpus, creator playtest, opt-in Practice,
generated Practice, generated future Dailies, then general release. Preserve fixture kill
switches during rollout. Use
ReverseCrossDailyGenerationas the Daily-specific source gate andReverseCrossGenerationas the master generated-serving gate; Daily evaluates both withsystem:reverse-cross-daily, while Practice continues to use the caller identity. - Use
ReverseCrossStructuralQualityas the independent structural-policy switch within theReverseCrossGenerationaudience for both Daily and Practice generation after a request is admitted to generation. Daily evaluates it withsystem:reverse-cross-daily; Practice evaluates it with the caller identity. Compare strategy, outcome, fallback, resource, and structural activity tags against a legacy baseline; disable the quality flag to restore legacy generation, or disable generation to restore fixture serving. Follow the feature-flag operator runbook. - Restrict caller-targeted policy comparisons to newly generated Practice puzzle keys. Daily keys are globally shared and persisted, and Daily flag evaluation does not inherit the caller identity. Do not use user targeting for Daily generation flags.
- Dashboard aggregate attempts, timeout/fallback, validation rejection reasons, quality bands, completion/abandonment, duration distributions, and catalog versions without raw puzzle content.
- Add load, soak, failure-injection, cancellation, content-refresh, Cosmos concurrency, and rollback drills before public Daily competition depends on generation.
Exit criteria¶
- Operators can explain, replay, quarantine, and roll back any served puzzle version.
- Daily availability does not depend on one unbounded synchronous generation request.
- The generated game has passed staged playtesting, accessibility, privacy, security, observability, deployment, and rollback reviews.
Cross-phase test strategy¶
- Unit: normalization, graphemes, policy composition, slot extraction, validators, timing state, stats calculation, quality metrics, deterministic seeds.
- Property/fuzz: arbitrary supported dimensions, masks, crossing agreement, full coverage, malformed sources/fixtures, cancellation, and reproduction from failure seeds.
- Contract: OpenAPI/public DTOs, hidden-solution boundary, additive persistence envelopes, and backward compatibility with Letter Golf.
- Integration: catalog refresh/failure, Cosmos idempotency/concurrency, Daily/Practice lifecycle, server timing, submission, stats, and group ranking.
- Browser/accessibility: explicit Start, placement input modes, autosave/reload/resume, Practice pause, completion, keyboard/focus/screen reader, mobile/zoom, and rectangular grids.
- Performance: cold/warm catalog and index build, generation matrices, request cancellation, memory/allocation, concurrent starts/submits, and scale-to-zero recovery.
- Editorial/playtest: versioned puzzle corpus with creator notes and measured player outcomes; regression seeds remain reproducible after algorithm changes.
Decision log to keep current¶
Add dated entries here when a decision closes. Do not hide a product or algorithm decision only in code or a transient chat.
| Date | Decision | Status |
|---|---|---|
| 2026-08-26 | Share one catalog snapshot and content pipeline; keep eligibility and search indexes game-specific. | Locked and implemented |
| 2026-08-26 | Complete shared lexical architecture and hardcoded Reverse Cross vertical slice before generation. | Locked and implemented |
| 2026-08-26 | Start Daily timing only on explicit Start; initially recommend no Daily pause and allow Practice pause. | Product decision pending playtest/accessibility review |
| 2026-08-31 | Make normal Daily interruption-tolerant with server-owned pause/resume, immediate visibility obscuring, and no automatic resume; reserve canPause=false for future Strict/Tournament timing. |
Locked and implemented |
| 2026-08-31 | Use an exact best duration plus a bounded 15-second mergeable histogram for typical duration; replay the same typed projections for merge, repair/backfill, reset, and export. | Locked and implemented |
| 2026-08-26 | Use the two historical mask-generator exports as Phase 3 seed material, not as a preselected algorithm. | Locked |
| 2026-08-27 | Accept the roadmap and close Phase 0; later creator feedback may refine open phases. | Locked |
| 2026-08-27 | Accept ADR 0001: bounded native fill is the first benchmark candidate; private solutions are witnesses, all rule-valid reconstructions are accepted, and uniqueness analysis is deferred to God View. | Locked |
| 2026-08-27 | Treat 0.5-1 GiB as a cost target, remove avoidable memory amplification first, and resize replicas when repeatable production-class measurements justify the irreducible requirement. | Locked |
| 2026-08-28 | Accept the bulk-built, reference-only positional index and bounded native MRV search for known-mask fill after the Release 5x5/7x7/9x9 matrix succeeded within measured latency and memory bounds. | Locked |
| 2026-08-28 | Accept deterministic mask-first construction with fair per-attempt shares of the global time and node budgets after the Release generation matrix succeeded for 5x5/7x7/9x9. | Locked |
| 2026-08-28 | Complete Phase 3D with default-off generated serving, fixture fallback, bounded per-process concurrency, replay-derived IDs, and safe scalar telemetry; retain production-container validation and progressive flag enablement as Phase 10 gates. | Locked |
| 2026-09-15 | Gate missing Daily generation behind ReverseCrossDailyGeneration and the master generation flag, evaluate Daily generation and quality with one stable system targeting identity, and preserve fixture fallback plus immutable persisted dates. |
Locked and implemented |
| 2026-09-15 | Preserve raw valid-board counts, but treat a structurally valid Across/Down transpose as the same reconstruction for any future ambiguity-based quality, difficulty, selection, or rejection policy. | Locked; evaluator versioning pending |