Compact Identities and Storage Plan¶
Status: Implementation and decision record. In-memory phases 1-4 and Reverse Cross persistence
phases 7-9 are implemented on branch jm/string-repetition at a12ff3b; later decisions are
recorded in their phase sections.
Scope: Shared lexical-catalog memory, game indexes, Reverse Cross puzzle and play persistence, Cosmos document identity, compatibility, migration, diagnostics, and measurement
Audience: Engineers reviewing why the compact layout changed, reproducing measurements, or planning a compatible follow-up. For the steady-state contract, start with Data Layout and Persistence.
Purpose¶
Verbolus currently uses readable strings for many values whose structure is already known from their owner. Examples include lexical IDs, fixture-entry IDs, Reverse Cross slot IDs, puzzle and play keys, versions, modes, directions, and coordinates. Composite strings are convenient at API, persistence, logging, and debugging boundaries, but high-cardinality generated strings and per-object metadata can become expensive when retained hundreds of thousands or millions of times.
The target is not to abbreviate every JSON property or replace clear types with opaque byte arrays. It is to represent identity structurally inside the application, store only information that cannot be derived safely, and format a human-readable representation when a boundary or diagnostic tool needs one.
This plan complements the Lexical Catalog Cold-Start and Compiled-Artifact Plan. That plan covers artifact production and delivery as well as cold-start work. This document focuses on eliminating redundant retained and persisted representations without sacrificing correctness, maintainability, compatibility, or debuggability.
Related documents¶
This plan owns the compaction sequence and compatibility strategy. It does not replace the following sources of truth:
- Data Layout and Persistence is the concise current-state reference for identity scopes, measured memory, persistence schemas, Cosmos keys, and TTL.
- Lexical and Game Architecture defines snapshot ownership, per-game views, derived indexes, refresh behavior, and the separation between shared lexical infrastructure and game-specific algorithms.
- Algorithmic Complexity of the Shared Lexical and Puzzle-Generation System records the current time-and-space model for catalog construction, views, Letter Golf indexes, and Reverse Cross generation. Update its bounds when a compact representation changes them.
- Lexical Catalog Cold-Start and Compiled-Artifact Plan owns artifact construction, delivery, loading, rollback, and the evidence gate for memory mapping.
- Reverse Cross owns player-facing rules and the current technical direction for puzzles, plays, timing, stats, and groups.
- ADR 0001: Reverse Cross generation and solution semantics owns generation, completion, alternate-solution, replay, and resource-sizing decisions.
- Reverse Cross Evaluator Design owns evaluator contracts, persisted evaluation evidence, benchmark corpora, and the distinction between meaningful and transpose-equivalent alternate boards.
- Reverse Cross Roadmap owns implementation phase status and sequencing; this plan should be linked from the applicable architecture, persistence, quality, and operations phases when work is scheduled.
- MiniGames Platform Roadmap owns cross-game Cosmos models, identity, groups, stats, observability, and release sequencing.
- Phase 4 Reverse Cross Puzzle Persistence Measurement Plan defines the existing latency, freshness, Cosmos headroom, and staged-production measurement process.
- Lexical Memory Analysis Runbook records the reproducible heap-capture, retained-graph attribution, Azure measurement, and artifact-handling methods used by this plan.
Current boundaries and important distinctions¶
The production lexical catalog is process-local. Its approximately 767,000 merged entries are not copied into Cosmos DB. The four pinned raw lexical artifacts total approximately 35.86 MiB, while a 2026-08-28 workstation run measured approximately 707.4 MiB of retained managed memory for the catalog and approximately 198.1 MiB for the Letter Golf index. The retained object graph, not raw artifact size, is therefore the primary catalog concern.
Cosmos has a separate repetition problem. Reverse Cross puzzle definitions persist the public bank, mask, private solution, and replay/evaluation metadata. Each player's play then persists puzzle identity and slot-to-entry placements. Repeating verbose slot and entry IDs in every play scales with player activity even though those identities are already implied by the puzzle structure.
Not every repeated-looking string duplicates its character payload:
- Exact literals may be interned.
- Multiple objects may reference the same source ID, source version, language, or grapheme string.
- Interpolated and concatenated composite IDs normally create distinct strings.
- Even when character data is shared, each object field, collection entry, dictionary bucket, and wrapper object still has a cost.
Measurement must distinguish shared references from duplicate objects and duplicated character payloads.
Design principles¶
- Structure owns identity. Direction, coordinates, puzzle membership, catalog membership, and collection order should be typed values or ordinals rather than embedded text when practical.
- Stable IDs exist at boundaries. Public APIs, persistence compatibility, imports/exports, and cross-snapshot references retain stable external identifiers where required.
- Local handles stay local. Dense integers are valid only within their owning catalog snapshot or puzzle and must never be mistaken for globally stable IDs.
- Do not discard semantic data. Display form, normalized grid form, and grapheme segmentation are not universally interchangeable.
- Readable diagnostics are projections. Debugger displays, God View, administrative tools, and explicit formatters can reconstruct readable names without making those names the internal representation.
- Measure before and after every material change. Stop when the production envelope is met; do not adopt memory mapping or a new Cosmos topology merely because it is technically possible.
- Compatibility precedes compaction. New readers understand old data before new writers emit a compact representation.
Phase 1 - Establish a retained-memory and storage baseline¶
Use the established measurement vocabulary and recorded baselines in the cold-start plan, the complexity analysis, and the Reverse Cross persistence measurement plan.
Managed-memory baseline¶
Capture a production-sized heap after warming:
- the shared lexical snapshot;
- the Letter Golf catalog view and signature/frequency indexes;
- the Reverse Cross catalog view and positional fill index; and
- representative generation and validation requests.
Rank retained data by:
- type and owning root;
- total string bytes and duplicate string contents;
- lexical IDs;
- display and grid forms;
- grapheme arrays and their referenced strings;
- source-reference and source-score objects;
- tag collections;
- snapshot and view dictionaries;
- Letter Golf trie nodes and retained entry identities; and
- Reverse Cross posting arrays and temporary search identity sets.
Record managed heap, committed memory, process working set, cumulative allocations, GC counts, catalog/view/index construction time, and warm lookup latency. A forced-GC delta is useful evidence but not a complete accounting by itself.
Cosmos baseline¶
Measure serialized byte size and document count for representative:
- Daily and Practice Reverse Cross puzzles;
- Reverse Cross plays with zero, partial, and complete placement sets;
- Letter Golf plays;
- group standings;
- Reverse Cross evaluation reports; and
- player profiles and statistics.
Break down the major fields instead of relying only on total document size. Record average, p95, and maximum size, retention/TTL, write frequency, read pattern, indexing policy, and estimated RU and storage consequences. Do not query or export raw production content into source control.
Measurement record - 2026-09-15¶
Step 1 was measured on the Windows development workstation with .NET 10 Release builds and the
pinned production lexical sources. The catalog version was
word-catalog-v1:fbb7a50a9ef85969f591d902b1cef8c88c2a52fb33eca46468e22ed2eb465d82.
The managed-memory results are process-local and include test-host overhead, so use the forced-GC
deltas to compare construction stages and the live heap dump to rank retained types. Do not add the
two figures together.
Construction-stage baseline¶
| Stage | Entries | Retained managed-memory delta | Build/access time |
|---|---|---|---|
| Shared catalog | 802,131 | 599.5 MiB | 16,607.0 ms cold; 0.040 ms warm |
| Letter Golf index | 379,528 | 198.4 MiB | 3,499.8 ms cold; 0.539 ms warm |
| Reverse Cross crossword view | 605,776 | 54.2 MiB | 1,682.4 ms cold; 0.065 ms warm |
| Reverse Cross fill index | 263,288 | 36.2 MiB | 250.2 ms cold |
The fill-index stage allocated 254.3 MiB while constructing its retained 36.2 MiB graph. Total catalog/view/index construction allocated 3,643.8 MiB. Process working set was 113.7 MiB before the catalog, peaked at 1,252.9 MiB after catalog publication, and measured 1,075.4 MiB after the fill index. These process-wide values are noisy but confirm that allocation churn and peak headroom are separate from final retained size.
The opt-in measurement test produced all stage measurements, but its final assertion failed because
the known-mask filler timed out for three fixture shapes: fixture-6x6-v1, fixture-6x6-003-v1,
and fixture-9x9-004-v1. All on-demand generation probes succeeded. Treat the timeout result as a
separate generation-regression investigation, not as a failure of the memory measurements.
Live-heap Pareto ranking¶
The live heap dump contained 13,566,809 objects totaling 916,507,757 bytes (874.05 MiB). The dump was captured after the catalog, Letter Golf index, Reverse Cross views, and fill indexes had been constructed. The largest relevant retained types were:
| Retained type/category | Objects | Retained bytes | Live heap |
|---|---|---|---|
| Immutable dictionary nodes for string-to-entry maps | 3,261,579 | 208,741,056 | 22.78% |
| Strings | 2,430,236 | 198,029,538 | 21.61% |
| String arrays | 1,137,341 | 118,746,480 | 12.96% |
| Letter Golf trie dictionary entry arrays | 482,891 | 64,915,624 | 7.08% |
LexicalEntry objects |
802,131 | 64,170,480 | 7.00% |
LexicalSourceReference objects |
1,093,405 | 43,736,200 | 4.77% |
| Letter Golf trie dictionaries | 482,891 | 38,631,280 | 4.22% |
| Immutable tag sets | 802,150 | 38,503,200 | 4.20% |
| Integer posting arrays | 488,080 | 29,896,020 | 3.26% |
| Source-reference arrays | 802,131 | 27,998,384 | 3.05% |
| Letter Golf trie nodes | 761,956 | 24,382,592 | 2.66% |
| Entry-reference arrays | 23 | 22,915,616 | 2.50% |
SourceScore objects |
605,560 | 19,377,920 | 2.11% |
| Lists of Letter Golf entry IDs | 334,000 | 10,688,000 | 1.17% |
This ranking confirms that the repeated immutable maps and collection/object structure are at least as important as strings. It also confirms that the Letter Golf trie is a separate material target; catalog compaction alone cannot remove its node, dictionary, entry-array, and list costs.
What string repetition actually exists¶
The live heap contained 2,418,879 distinct string values across 2,430,236 string objects. Keeping one object for each exact value would remove only 11,357 string objects and approximately 0.97 MiB. Most of that duplication came from test-host method and source-file metadata, not lexical content. Global string interning is therefore not a useful optimization target.
The large string cost instead comes from unique verbose identities:
- All 802,131 lexical IDs were distinct 68-character strings and occupied 126,736,698 bytes (120.87 MiB), or 64.0% of all retained string bytes.
- The repeated
lex:text itself accounts for only about 6.12 MiB of UTF-16 payload. The larger opportunity is replacing each full string object with a 32-byte stable binary identity or a snapshot-local integer handle where global identity is unnecessary. - The 802,131 language-field references resolved to one string object.
- The 8,426,184 grapheme references resolved to 36 string objects.
- The 1,093,405 source-ID references resolved to eight string objects, and the same number of source-version references resolved to eight objects.
- The 605,560 score-scale references resolved to two string objects.
- Display form and grid form were equal for only 33 entries and were the same object for only 22. They are genuinely different semantic data for this catalog and should not be collapsed as a general optimization.
Provenance and optional metadata repeat structure rather than string payload:
- 1,093,405
LexicalSourceReferenceobjects represented only 178 distinct(source, version, scale, score)value combinations. - 589,505 entries had one source, 147,555 had two, 56,020 had three, and 9,051 had four or more.
- 801,658 of 802,131 entries had no tags, while the live heap retained 802,150 immutable tag-set objects totaling 36.72 MiB.
- Only 721 tag references and 16 distinct tag strings existed across the catalog.
The exact count of entries with four or more sources is 9,051: 5,512 with four, 2,580 with five, 931 with six, and 28 with seven.
Per-view repeated structure¶
Entries and string payloads are shared by reference, but each view currently adds both an entry
array, an equally long EntryIds array, and another immutable grid-form map:
| Owner | Entry references | EntryIds references |
Grid-map associations |
|---|---|---|---|
| Snapshot | 802,131 | n/a | 802,131, plus 802,131 ID-map associations |
| Letter Golf standard view | 379,528 | 379,528 | 379,528 |
| Reverse Cross crossword view | 605,776 | 605,776 | 605,776 |
| Reverse Cross generated view | 292,699 | 292,699 | 292,699 |
The IDs in these arrays are shared string references, not duplicate string objects. Their cost is
the reference arrays and the collection/map structures. This directly validates removing
WordCatalogView.EntryIds, replacing per-view grid maps with compact membership, and moving game
indexes to snapshot-local handles.
Production Cosmos population¶
Azure Monitor reported the following current production population. DataUsage and IndexUsage
are service metrics rather than sums of the sampled JSON lengths.
| Container | Documents | Data usage | Index usage |
|---|---|---|---|
puzzles |
353 | 1,474,560 bytes | 399,360 bytes |
plays |
409 | 1,048,576 bytes | 335,872 bytes |
players |
93 | 294,912 bytes | 52,224 bytes |
groups |
35 | 131,072 bytes | 21,504 bytes |
A read-only Azure CLI identity audit measured every document in these four containers. It consumed 51.34 RU in total, emitted only aggregate measurements, retained no document bodies, and performed no writes.
| Document shape | Count | Total JSON bytes | Average | p95 | Maximum |
|---|---|---|---|---|---|
| Letter Golf Daily puzzle | 56 | 34,780 | 621.1 | 721 | 723 |
| Letter Golf Practice puzzle | 75 | 53,885 | 718.5 | 785 | 786 |
| Reverse Cross Daily puzzle | 29 | 149,267 | 5,147.1 | 9,069 | 9,778 |
| Reverse Cross Practice puzzle | 115 | 977,385 | 8,499.0 | 13,737 | 14,320 |
| Reverse Cross evaluation report | 68 | 182,334 | 2,681.4 | 3,107 | 3,274 |
| Letter Golf play | 270 | 224,439 | 831.3 | 1,135 | 1,210 |
| Reverse Cross play | 139 | 268,171 | 1,929.3 | 2,959 | 4,268 |
| Player | 93 | 70,446 | 757.5 | 1,664 | 2,341 |
| Group metadata | 3 | 2,359 | 786.3 | 969 | 969 |
| Group standings | 32 | 33,602 | 1,050.1 | 1,314 | 1,363 |
Of the Reverse Cross plays, 92 active/abandoned plays had an empty board and averaged roughly 1.60 KiB before storing any placement. Six active plays and one abandoned play had partial boards. Forty completed plays averaged 2,607.5 bytes; their placement arrays totaled 41,130 bytes, or 39.4% of those completed documents.
Across all 144 Reverse Cross puzzle documents, major nested sections occupied:
| Section | Bytes | Share of Reverse Cross puzzle JSON |
|---|---|---|
| Public entry bank | 340,177 | 30.19% |
| Solution placements | 237,382 | 21.07% |
| Solved cells | 214,815 | 19.07% |
| Public cells | 122,671 | 10.89% |
| Generation metadata | 73,663 | 6.54% |
| Evaluation-report reference | 9,112 | 0.81% |
Property names occupied 392,415 bytes in those puzzle documents; 312,236 bytes were repeated names inside the same document, principally object-shaped cells, entries, and placements. This is not all removable, but it supports replacing repeated object arrays with documented positional structures rather than abbreviating every property name.
The literal identity measurements were:
- Puzzle documents contained 2,493 slot-ID values occupying 39,889 bytes. The repeated
slot:across:/slot:down:prefixes accounted for 27,424 bytes. - Puzzle documents contained 3,650 lexical-ID occurrences occupying 255,500 bytes and 1,336 fixture-ID occurrences occupying 24,520 bytes.
- Reverse Cross plays contained 556 slot-ID values occupying 8,904 bytes, 208 lexical-ID occurrences occupying 14,560 bytes, and 348 fixture-ID occurrences occupying 6,696 bytes.
- Duplicating
idwhen it equaled the container partition-key property occupied 8,088 bytes in Reverse Cross puzzles and 12,854 bytes in Reverse Cross plays at the current population.
The main persisted opportunity is therefore structural: remove the separately stored solved grid, encode the public mask compactly, use canonical slot order plus entry ordinals, and replace verbose placement objects with a positional vector. Prefix removal helps, but it is not the dominant saving. Current production storage is small; schema migration should remain compatibility-led rather than an urgent storage-cost response.
Exit criteria¶
Produce a Pareto-ranked table of retained bytes and persisted bytes. Every subsequent phase must name the measured category it targets and the expected benefit.
The 2026-09-15 record satisfies the Step 1 baseline and Pareto-ranking requirement. Before/after comparisons should reuse the same pinned source versions, Release configuration, view/profile set, and production-document aggregation rules.
Phase 2 - Remove low-risk in-memory duplication¶
Preserve the snapshot, view, and game-index ownership boundaries described in Lexical and Game Architecture. Any revised space or build-time bounds belong in the algorithmic complexity document.
Make changes that preserve the current external and persistence contracts:
- Remove
WordCatalogView.EntryIds; current production code does not consume it. - Keep one authoritative snapshot-level grid-form lookup instead of a second large grid-form dictionary in every view.
- Represent view membership with a bitmap keyed by snapshot entry ordinal.
- Store dense entry handles or direct references in the Letter Golf signature index instead of textual lexical IDs.
- Track used Reverse Cross generation candidates by index/ordinal rather than by string ID.
- Preserve the shared Basic Latin grapheme table and verify that sources reuse descriptor-owned strings where expected.
- Represent empty tags, missing scores, and other absent optional metadata without allocating an independent collection or wrapper per entry.
Introduce explicit value types such as CatalogEntryHandle, but keep them small and unsurprising.
A handle should wrap an integer, be valid only for one snapshot, and have a debugger display that
can resolve a readable entry through that snapshot.
Phase 2 implementation record¶
The low-risk code changes are complete:
- Items 1-3:
WordCatalogViewno longer retainsEntryIdsor a grid-form dictionary. It retains eligible entry references plus aBitArraykeyed by ordinal in its exact snapshot. - Item 4: production
WordSignatureIndexterminals retain view-local integer ordinals, whichLetterGolfCatalogIndexresolves directly through its entry array. Compatibility query methods still project textual IDs. The index-options fingerprint is intentionally version 3. - Item 5: Reverse Cross generation, solution analysis, and reconstruction analysis use owner-local integer ordinals for temporary used-entry membership. Public and persisted IDs remain textual.
- Item 6: existing tests continue to verify the shared Basic Latin grapheme instances and reuse of source descriptor ID/version strings; these sharing paths required no representation change.
- Item 7: absent tags in
RawLexicalEntryandLexicalEntrynow reuse shared immutable empty sets. Existing nullable source scores continue to represent missing scores without a wrapper. Further optional-metadata compaction requires separate measurement and evidence.
Focused catalog, view, Letter Golf, and Reverse Cross regression tests pass. Catalog and view fingerprints remain stable; the Letter Golf index-options fingerprint changed deliberately to identify its new retained/search representation. No API or persistence contract changed.
Production-size after measurement - 2026-09-16¶
The opt-in production measurement was repeated in .NET 10 Release configuration with the same pinned sources, profile set, and catalog version as the 2026-09-15 baseline. Entry counts were unchanged, all known-mask fill probes and on-demand generation probes succeeded in all three runs, and the measurement test passed.
| Stage | Before retained | After retained | Difference | Before time | After time |
|---|---|---|---|---|---|
| Shared catalog | 599.5 MiB | 536.8 MiB | -62.7 MiB (-10.5%) | 16,607.0 ms | 14,236.0 ms |
| Letter Golf index | 198.4 MiB | 167.3 MiB | -31.1 MiB (-15.7%) | 3,499.8 ms | 2,917.4 ms |
| Reverse Cross crossword view | 54.2 MiB | 8.7 MiB | -45.5 MiB (-83.9%) | 1,682.4 ms | 873.2 ms |
| Reverse Cross fill index | 36.2 MiB | 16.2 MiB | -20.0 MiB (-55.2%) | 250.2 ms | 249.4 ms |
The four forced-GC stage deltas fell by 159.3 MiB in aggregate. Fill-index construction allocated 234.3 MiB, down 20.0 MiB (7.9%), and total catalog/view/index construction allocated 3,382.2 MiB, down 261.6 MiB (7.2%). Process working set measured 115.3 MiB before the catalog, 1,151.6 MiB after catalog publication, and 923.8 MiB after the fill index. These process-wide figures remain noisy, but the final value was 151.6 MiB below the baseline run.
The after run retained the catalog version
word-catalog-v1:fbb7a50a9ef85969f591d902b1cef8c88c2a52fb33eca46468e22ed2eb465d82
and the same catalog, Letter Golf, Reverse Cross view, and fill-index entry counts. The three
known-mask fixtures that timed out in the baseline each succeeded 3/3; their measured p95 times
were 6,500.9 ms, 6,075.6 ms, and 5,463.1 ms respectively. The measurement therefore satisfies the
Phase 2 production-size and behavioral exit criteria without changing an API or persistence
contract.
Exit criteria¶
- Catalog, Letter Golf, and Reverse Cross behavior remains byte-for-byte compatible at API and persistence boundaries.
- Deterministic generation and catalog fingerprints remain stable unless an explicitly versioned contract changes.
- Production-size measurements demonstrate the retained-memory and construction-time difference.
Phase 3 - Replace retained textual lexical identity¶
The current lexical ID is lex: plus a 64-character lowercase SHA-256 value. A .NET string of that
length can plausibly consume roughly 160 bytes including object overhead. At approximately 767,000
entries, lexical ID strings alone are therefore a credible material cost, although the Phase 1 heap
profile must confirm their actual retained contribution.
Use two identity forms:
CatalogEntryHandle: a dense snapshot-local ordinal used by views and game indexes; andLexicalId: a fixed-width binary value used when stable content identity is required.
LexicalId must preserve the existing definition, SHA-256 of language + NUL + gridForm, so the
external lex:{hex} representation remains stable. Parse or format that text only at API,
persistence, export, error, and diagnostic boundaries.
Do not retain a compatibility Id property that allocates a freshly formatted string every time
hot code reads it. Move sorting, lookup, equality, search, and fingerprinting to the typed identity
before making textual formatting lazy.
Snapshot lookup can map binary lexical identity to a dense handle. Algorithms that only need entry membership should use handles directly and avoid stable-ID lookup entirely.
Hard parts¶
- Stable deterministic ordering must not silently change replay identities.
- Hash comparison and dictionary behavior need allocation-free implementations.
- Public and stored IDs must remain exactly compatible.
- A handle from one catalog version must never be accepted by another snapshot.
Phase 3 implementation record¶
The compact lexical-identity changes are complete:
LexicalIdis a fixed 32-byte value containing the existing SHA-256 digest of UTF-8language + NUL + gridForm. Strict parsing and canonical formatting preserve the publiclex:plus 64 lowercase hexadecimal characters representation.LexicalEntry, snapshot ID maps, catalog and view lookups, Letter Golf indexes, and Reverse Cross generation and evaluation use typed identities or owner-local ordinals internally. Textual IDs are created or parsed only at API, persistence, fixture, export, compatibility, and diagnostic boundaries.CatalogEntryHandleremains scoped to one exact snapshot instance. Tests reject handles from another snapshot even when both snapshots describe equivalent content.- Catalog fingerprinting deliberately hashes each identity in its canonical 68-byte textual form, preserving existing catalog versions and replay compatibility.
The pinned external identity for en-US and CAT remains
lex:6bb428218ccd59ac29b134805f83b0f21ee23825fadc2d2a942a05c9150b3312, and the pinned
one-entry catalog version remains
word-catalog-v1:889514eac5b37525498c05b7b3f303a81f52872b94db377d0ee9eb003429cc13.
Focused catalog, view, Letter Golf, Reverse Cross, evaluator, and calibration tests pass. Public
API and persistence IDs remain strings, and production Reverse Cross ordering remains stable.
The production measurement fixture retains its HTTP warm-up but replaces the unrelated Cosmos-backed account-deletion store with the existing in-memory test store. This keeps cloud credential discovery and session-revocation persistence outside the lexical measurement.
Production-size after measurement - 2026-09-16¶
The opt-in production measurement was repeated in .NET 10 Release configuration with the same pinned sources, profile set, and catalog version as the Phase 2 run. The full test completed with exit code 0, establishing that every known-mask fill and on-demand generation probe succeeded. A second pass captured the construction metrics below without repeating those long-running probes.
| Stage | Phase 2 retained | Phase 3 retained | Difference | Phase 2 time | Phase 3 time |
|---|---|---|---|---|---|
| Shared catalog | 536.8 MiB | 450.9 MiB | -85.9 MiB (-16.0%) | 14,236.0 ms | 13,426.1 ms |
| Letter Golf index | 167.3 MiB | 167.4 MiB | +0.1 MiB (+0.1%) | 2,917.4 ms | 2,784.9 ms |
| Reverse Cross crossword view | 8.7 MiB | 8.7 MiB | 0.0 MiB | 873.2 ms | 648.9 ms |
| Reverse Cross fill index | 16.2 MiB | 16.2 MiB | 0.0 MiB | 249.4 ms | 214.4 ms |
The catalog reduction is the expected material effect: replacing its 802,131 retained textual IDs with fixed-width binary values removed 85.9 MiB from the forced-GC catalog delta. The other stage deltas remained effectively flat because Phase 2 had already removed their retained textual-ID arrays and hot-path string indexes.
Total catalog, view, and index construction allocated 3,138.9 MiB, down 243.3 MiB (7.2%) from the Phase 2 run. Fill-index construction remained 234.3 MiB. Process working set measured 115.3 MiB before the catalog, 952.7 MiB after catalog publication, and 823.9 MiB after the fill index; the final value was 99.9 MiB below Phase 2. These process-wide figures remain noisy, but they support the forced-GC result.
The after run retained catalog version
word-catalog-v1:fbb7a50a9ef85969f591d902b1cef8c88c2a52fb33eca46468e22ed2eb465d82
and the same catalog, Letter Golf, Reverse Cross view, and fill-index entry counts: 802,131;
379,528; 605,776; and 263,288 respectively. The measurement and compatibility tests therefore
satisfy Phase 3 without changing an API, persistence, replay, fixture, or diagnostic contract.
Exit criteria¶
- The external lexical-ID format and catalog-version compatibility vectors remain unchanged.
- Typed identity lookup, malformed textual-ID rejection, and snapshot-local handle rejection are covered by executable tests.
- Catalog, Letter Golf, and Reverse Cross behavior remains compatible at API and persistence boundaries.
- Production-size measurement demonstrates a material retained-memory reduction, and all production generation probes pass.
Phase 4 - Normalize provenance and category metadata¶
The snapshot already owns authoritative source descriptors. Per-entry provenance should therefore reference a source ordinal rather than repeat source ID and source version fields.
Target representation:
- one snapshot-level source registry;
- a compact source bitmask or sorted source-ordinal list per entry;
- compact score contributions containing source ordinal and numeric value;
- score scale owned by the source descriptor where the source contract permits it;
- one snapshot-level tag/category registry; and
- a bitmask or sorted category-ID list per entry.
Language belongs to the language-scoped snapshot and need not occupy one field on every entry. Source version, license, attribution, and source-wide score semantics remain on the descriptor.
Do not globally intern arbitrary runtime strings. An unbounded intern pool can keep transient data alive for the process lifetime and make retention worse.
Semantic constraints¶
- Preserve all provenance and attribution needed for legal, moderation, and editorial decisions.
- Preserve source-native score scales; unrelated source scores must not become comparable merely because their storage is compact.
- Keep open-ended categories versioned and registry-backed rather than assigning undocumented magic integers.
Phase 4 implementation record¶
The provenance and category normalization changes are complete:
- Each compact snapshot owns one
LexicalMetadataRegistrycontaining its canonical language, sorted source descriptors, source ordinals, and deterministic category IDs. A registry accepts at most 64 sources so every entry can represent provenance with oneulongmask. - Compact entries retain the source mask, only the source-ordinal/numeric-value pairs that have
scores, and sorted
ushortcategory IDs. The source descriptor owns its optional score scale, and an entry with no categories retains no category array. Language,Sources, andTagsremain readable compatibility projections. Public standalone entry and snapshot constructors remain supported, including callers that supply source descriptors in a noncanonical order.- Catalog fingerprinting streams source masks, sparse scores, and category IDs through the shared registry. Eligibility profiles query compact source/category/score predicates directly. Neither hot path reconstructs source-reference objects or tag sets.
- The snapshot rejects mixed standalone/compact entry graphs, entries backed by different registries, invalid source bits, unsorted or duplicate compact scores, and invalid category IDs. Input arrays are copied so callers cannot mutate published metadata.
The source-wide score scales are declared by the production source descriptors. Distinct scales remain semantically separate, source attribution is preserved, and open-ended category spellings remain deterministic and case-insensitive. The catalog schema, canonical fingerprint bytes, external lexical IDs, public API contracts, persistence contracts, replay identities, fixtures, and diagnostics did not change.
Focused compact-metadata, catalog, eligibility, and Reverse Cross tests pass, including the exact 64-source boundary, deterministic category casing, malformed compact input, defensive-copy, and standalone compatibility cases. The full backend suite passes with 1,517 tests successful and three skipped. The production measurement harness also uses compact source predicates for its attribution report so reporting does not materialize millions of compatibility objects.
Production-size after measurement - 2026-09-17¶
The opt-in production measurement was repeated in .NET 10 Release configuration with the same pinned sources, profiles, and catalog version as Phase 3. A dedicated run completed with exit code 0, establishing that all 102 known-mask fill samples and all 102 on-demand generation samples succeeded. The captured repeat recorded the construction metrics below.
| Stage | Phase 3 retained | Phase 4 retained | Difference | Phase 3 time | Phase 4 time |
|---|---|---|---|---|---|
| Shared catalog | 450.9 MiB | 392.9 MiB | -58.0 MiB (-12.9%) | 13,426.1 ms | 14,672.4 ms |
| Letter Golf index | 167.4 MiB | 167.4 MiB | 0.0 MiB | 2,784.9 ms | 3,255.5 ms |
| Reverse Cross crossword view | 8.7 MiB | 8.7 MiB | 0.0 MiB | 648.9 ms | 882.4 ms |
| Reverse Cross fill index | 16.2 MiB | 16.2 MiB | 0.0 MiB | 214.4 ms | 289.1 ms |
The catalog reduction is the expected material effect: replacing per-entry provenance objects and tag sets with source masks, sparse scores, and category IDs removed 58.0 MiB from the forced-GC catalog delta. Derived structures remained flat because they retain references to compact entries rather than cloning provenance or category metadata. Cold timings varied upward in this workstation run, while warm catalog, Letter Golf index, and Reverse Cross view access remained 0.046 ms, 0.462 ms, and 0.105 ms respectively.
Total catalog, view, and index construction allocated 2,439.0 MiB, down 699.9 MiB (22.3%) from Phase 3. Fill-index construction allocated 181.6 MiB, down 52.7 MiB (22.5%). Process working set measured 117.8 MiB before the catalog, 899.4 MiB after catalog publication, and 739.7 MiB after the fill index; the final value was 84.2 MiB below Phase 3. These process-wide figures remain noisy, but they support the forced-GC result.
The captured repeat retained catalog version
word-catalog-v1:fbb7a50a9ef85969f591d902b1cef8c88c2a52fb33eca46468e22ed2eb465d82
and the same catalog, Letter Golf, Reverse Cross view, and fill-index entry counts: 802,131;
379,528; 605,776; and 263,288 respectively. All eight source-attribution counts matched their raw
record counts and no records were rejected. All 102 on-demand generation samples succeeded. In
the repeat, 101 of 102 known-mask fill samples succeeded; one fixture-6x6-003-v1 sample reached
the existing 10,000 ms wall-clock bound after the other two samples succeeded. The earlier
all-green dedicated run and the unchanged compatibility vectors establish Phase 4 behavior, while
the repeat records the known timing sensitivity rather than concealing it.
Exit criteria¶
- Source, score, language, and category metadata have one authoritative snapshot-owned registry.
- Compact entries do not allocate source-reference objects or empty tag collections per entry.
- Compatibility projections preserve existing public behavior, canonical fingerprint bytes, and external IDs.
- Production-size measurement demonstrates the retained-memory difference, and all production generation probes pass.
Phase 5 - Compact lexical forms and grapheme storage only if justified¶
Status: Deferred pending evidence
Do not assume display form, grid form, and grapheme segmentation are redundant:
- Display case and punctuation can be player-facing information.
- Grid normalization is a versioned language policy.
- A grapheme is not necessarily one UTF-16 code unit or Unicode scalar.
- Historical content must not change meaning when a future normalizer changes.
Low-risk improvements include deliberately sharing one string object when display and grid forms are ordinally identical. A larger compact representation can use:
- a snapshot-wide UTF-8 string table;
- fixed-width entry records containing offsets;
- a grapheme registry; and
- a flat grapheme-ID array with per-entry start/count ranges.
This representation should remain behind the catalog API. It requires explicit bounds checking, schema versioning, corruption checks, and multilingual tests. Adopt it only if Phase 1-4 results leave a material memory problem.
Before prototyping the representation, capture separate production-size retained-heap snapshots:
- immediately after catalog publication, before any game view or index is built; and
- after the Letter Golf index, Reverse Cross view, and Reverse Cross fill index are all retained.
Attribute retained bytes in both snapshots to:
LexicalEntryobjects and their direct fields;- display-form and grid-form strings;
- per-entry grapheme arrays, grapheme-reference slots, and distinct grapheme strings;
- snapshot entry arrays and identity/grid-form lookup maps;
- compact source-score and category arrays;
- Letter Golf entry arrays and signature trie nodes/terminals; and
- Reverse Cross view arrays, membership structures, and fill-index postings.
Measure the same build in the actual 2 GiB Azure container. Record scale-from-zero latency, peak and settled resident/working-set memory, managed committed and retained memory, GC pause/count data, and CPU. Exercise catalog refresh while the previous snapshot remains reachable, then measure concurrent lexical-request latency and failure headroom during publication and derived-index reconstruction. Do not infer production headroom from workstation forced-GC deltas.
Proceed with a compact lexical-form/grapheme prototype only when all of these conditions hold:
- attributed catalog retention shows that the targeted forms and grapheme structures can plausibly remove at least about 15% of catalog retention and at least roughly 60 MiB at current scale;
- the actual 2 GiB container demonstrates a named operational or cost target that those savings address, such as refresh overlap, concurrent-request headroom, scale-from-zero reliability, or a lower viable memory tier; and
- the prototype demonstrates that saving while preserving catalog fingerprints, public and stored forms, grapheme behavior, deterministic game results, and multilingual correctness.
If either the retention threshold or the operational/cost target is absent, keep Phase 5 deferred and move to artifact/cold-start work without changing the in-memory lexical representation.
Phase 5 evidence checkpoint - 2026-09-17¶
Independent .NET 10 Release processes captured the requested catalog-only and derived-index heap checkpoints with the same pinned production sources and Phase 4 catalog version. The catalog root retained 379.6 MiB. The object-identity union of the catalog, Letter Golf index, Reverse Cross views, and fill indexes retained 566.1 MiB.
ClrMD field attribution found 68,997,862 bytes of distinct display/grid strings and 86,660,616 bytes of per-entry grapheme arrays. The combined 155,658,478 bytes, or 148.45 MiB, represent 39.1% of catalog retention. Grapheme-array sizes already include their 67,409,472 bytes of reference slots, so those slots are not added a second time. Counts and attributed bytes were identical in both dumps, confirming that these structures belong to the shared catalog rather than the derived indexes.
The local retention threshold is therefore satisfied. Read-only production telemetry from 2026-09-10 through 2026-09-17 also found a 1,598.3 MiB per-pod peak working set, leaving 449.7 MiB of the 2 GiB allocation and missing the existing 500 MiB headroom target by 50.3 MiB. The same period contained 27 sampled initial catalog builds with a 32.52-second p95 and no refresh builds; 12 correlated requests ended with HTTP 499 while their builds completed successfully.
This establishes memory headroom and scale-from-zero latency as named operational concerns, but it does not prove that compact lexical forms would return at least roughly 60 MiB to the resident working set or improve the CPU-bound cold build. Phase 5 remains deferred until a bounded prototype or approved representative deployment comparison proves that effect and preserves behavior. Follow the analysis runbook for the capture commands, attribution rules, Azure metrics, and approval boundary for deliberate production exercises.
Phase 6 - Compile and deliver an immutable catalog artifact¶
Decision (2026-09-17): Deferred. The intended production operating model is to sustain enough regular use, or configure sufficient minimum capacity, that at least one backend replica remains warm. Scaling the backend to zero is not a desired long-term goal under that model, so artifact delivery does not currently solve a required user-facing cold-start target. This phase is isolated from Phases 7-10 and does not block their representation or persistence compaction.
Artifact work improves cold-start network dependency, CPU, and allocation churn. It does not by itself guarantee lower retained memory if the loader reconstructs the same managed object graph.
A compiled artifact also offers a separate development and CI benefit: container tests could load the real production catalog without downloading, parsing, normalizing, moderating, and merging its sources for every container run. The compilation cost would move into one fingerprinted, cacheable artifact-build step, enabling a much faster realistic container test loop. Revisit this phase if that repeated test cost becomes material, or if replica startup, deployment readiness, source availability, or catalog reproducibility becomes a measured operational problem.
Use the progression already established by the cold-start plan:
- Package verified pinned raw sources in a dedicated application-image layer.
- Precompute source parsing, normalization, moderation, merge, canonical ordering, and catalog versioning into a schema-versioned artifact.
- Initially load the artifact into the current or incrementally compacted object model.
- Measure artifact size, load latency, allocations, retained memory, working set, and rollback.
- Consider direct array/string-table querying or memory mapping only if simpler loading still fails agreed targets.
An artifact should contain a schema/version header, source/policy provenance, canonical content identity, integrity checksum, and deterministic ordering. It must fail closed when malformed and preserve a last-known-good operational path.
Phase 7 - Use structural Reverse Cross identities in memory¶
This phase changes representation, not the generation or solution semantics fixed by ADR 0001 or the public behavior defined in Reverse Cross.
A Reverse Cross slot is derived from the public mask, direction, and starting coordinate. It does
not require a retained string such as slot:across:2:0 in domain algorithms.
Define a canonical slot order:
- Across slots ordered by starting row and column;
- Down slots ordered by starting row and column.
Represent a slot internally by SlotOrdinal or a compact value containing direction and start
coordinate. Represent puzzle-bank entries by puzzle-local EntryOrdinal. Continue formatting the
existing readable IDs when the public API, an old storage schema, God View, or a debugger requires
them.
All validators must derive the same canonical ordering from the mask. Add invariant tests proving that extraction order is deterministic across construction, persistence, API mapping, play validation, and solution analysis.
Phase 8 - Add Reverse Cross puzzle storage schema v2¶
Keep the puzzle lifecycle and persistence rollout aligned with Reverse Cross Roadmap Phase 4 and retain evaluator evidence required by Reverse Cross Evaluator Design.
The v1 puzzle document persists several derivable representations:
- one object per public cell containing a textual kind;
- entry ID, display form, grid form, and grapheme list for every bank entry;
- a complete solved-cell grid; and
- solution placements containing verbose slot and entry IDs.
A clear v2 schema should store:
- dimensions;
- blocked-cell indexes or a documented mask bitset;
- the exact entry bank information that cannot safely be re-derived;
- one entry ordinal per canonical slot for the private witness;
- generation/replay metadata once; and
- only non-derivable evaluation references.
The solved grid is derivable from the mask, exact bank, and witness placements and should not also be persisted cell by cell. Prefer a readable property such as:
Do not pursue savings by shortening descriptive JSON property names. Compact the values and remove redundant structures instead.
The exact grapheme units needed to replay a historical puzzle must remain recoverable without assuming the current catalog or normalizer is unchanged. Omitting stored graphemes is permissible only if the schema pins and retains a normalization/segmentation version that can reconstruct them forever.
Phase 8 implementation record¶
Reverse Cross puzzle schema v2 is implemented as a compatibility-preserving mapper change:
- New writes retain the existing document identity, partition key, scope, replay metadata,
evaluation reference, TTL, and shape fingerprint while setting
schemaVersionto 2. - The public puzzle stores sorted
blockedCellIndexesinstead of one textual-kind object per cell. - Entry order defines the puzzle-local ordinal. Each entry retains its stable ID, display form, and
exact historical graphemes;
gridFormis reconstructed by concatenating those graphemes. - The private witness stores one entry ordinal per canonical slot in
entryBySlot. The solved grid and placements are reconstructed deterministically and validated for slot length, uniqueness, complete open-cell coverage, and crossing agreement. - Reads dispatch explicitly between schema 1 and schema 2. Schema 1 continues to accept the legacy cell arrays, grid forms, solved cells, and textual placements; mixed or unsupported payloads fail closed.
- Historical plays that copied puzzle schema version 1 remain eligible for stats repair alongside version 2 plays. The play document itself remains schema 1 pending Phase 9.
This targets the Phase 1 persisted-byte categories for public cell-kind objects, duplicated solved cells, textual slot/entry placement objects, and duplicated grid forms. It does not change or claim savings from duplicated Cosmos partition-key properties; that remains Phase 10.
Phase 9 - Add Reverse Cross play storage schema v2¶
The v2 mapper must preserve the authoritative timing, resume, completion, competition, and spoiler boundaries tracked in Reverse Cross Roadmap Phase 4 and the cross-game data responsibilities in the platform roadmap.
Per-player plays are the highest-scale location for Reverse Cross placement repetition. Replace a list of objects such as:
with a slot-ordered vector:
The storage mapper expands this vector into existing API slot/entry identities. Public contracts and the frontend need not change merely because persistence becomes compact.
Audit the version metadata copied into each play. Many consumers need an immutable comparison identity rather than every component string. A versioned puzzle-definition fingerprint may replace duplicated content/profile/provider/generator strings where:
- equality is the actual operation;
- the fingerprint definition is stable and canonical;
- board dimensions and result data remain available where needed; and
- historical plays remain usable after a Practice puzzle expires.
Before removing fields, trace account merge, stats replay/repair, group standings backfill, data export, deletion, support diagnostics, and historical Practice behavior.
Phase 9 implementation record¶
Reverse Cross play schema v2 is implemented as an expand-write compatibility change:
- Readers accept schema 1 placement objects and schema 2
entryBySlotvectors. Gameplay reads expand compact ordinals through the persisted puzzle definition before validation or API projection; unknown schemas and malformed vectors fail closed. ReverseCrossPlayStorageV2is a default-off server-side feature flag. Disabled or failed flag evaluation writes schema 1; enabled evaluation writes schema 2. Rollback therefore disables new compact writes while retaining dual-read support.- Schema 2 stores one nullable entry ordinal per canonical slot and omits textual placement objects. Slot and entry uniqueness, vector length, and ordinal range are validated at the storage mapper.
- Play keys, partition keys, lifecycle status, authoritative timestamps, board revision, active duration, dimensions, spoiler state, completion results, standings comparison identity, and historical version metadata are unchanged.
- Board save, completion, pause, resume, and abandon preserve external slot/entry IDs in runtime and API contracts. Account merge and data export preserve compact vectors, while stats repair accepts both play schema versions.
- Existing mutable schema 1 plays upgrade lazily only on a successful write while the flag is enabled. No background migration or Cosmos partition change is introduced.
Phase 10 - Evaluate compact Cosmos document keys separately¶
Decision (2026-09-18): Not justified. Do not implement or migrate compact document keys.
Some apparent duplication is imposed by current Cosmos partitioning:
- puzzle
idequalspuzzleKeybecause the container uses/puzzleKey; and - play
idequalsplayKeybecause the container uses/playKey.
The production audit attributed 8,088 bytes in Reverse Cross puzzles and 12,854 bytes in Reverse
Cross plays to the duplicate identity value, or 20,942 bytes total. That is approximately 1.50% of
the 1,394,823 sampled Reverse Cross puzzle-and-play JSON bytes. It is an upper bound for this
decision, not guaranteed recoverable space: Cosmos still requires id, and the lower-risk option
below retains both the id and partition-key properties. Practice puzzles expire after 30 days,
plays expire after 180 days, and the current production populations are small. There is no measured
storage-cost, RU, latency, or operational target that this change would materially improve.
Option 1 - Compact keys in the existing containers¶
A lower-risk implementation would keep the current containers and partition-key paths but replace
new play identities with a fixed-length deterministic key, for example a version-prefixed base64url
SHA-256 digest over an unambiguous encoding of the puzzle key and user ID. Both id and playKey
would still contain that digest. The document would retain readable puzzleKey and userId fields
for queries, exports, deletion, support, and diagnostics.
Implementing this option would require:
- Define and freeze a canonical, length-delimited hash input, digest algorithm, encoding, and schema prefix; publish collision handling and never silently change that contract.
- Centralize key generation and replace every key construction in both games, standings repair, account merge, deletion, exports, tests, and support tooling.
- Release readers that compute the compact key, fall back to the legacy readable key on a miss, and detect the invalid state where both identities exist for one logical play.
- Feature-flag compact writes and preserve legacy reads for at least the full play-retention window. Deletes and merge cleanup must target both identities during that period.
- Define conflict, ETag, retry, and rollback behavior. Changing both
idandplayKeycreates a new item in a different logical partition; it is not an in-place rename, and optimistic concurrency state cannot transfer atomically. - Add mixed-identity coverage for create, save, resume, complete, standings, export, merge, deletion, TTL, duplicate races, and rollback, followed by production RU and latency measurement.
Pros:
- no Terraform or container-topology change;
- bounded key length while retaining efficient point reads; and
- readable puzzle and user identities remain available outside the storage key.
Cons:
- it shortens the duplicated values but does not eliminate either required property;
- keys become opaque in Cosmos diagnostics and manual operations;
- fallback misses can add a second point read and consume more RU than the saved bytes repay;
- canonicalization mistakes become permanent identity-contract defects; and
- rollout can create two independently mutable documents for one logical play, with no atomic cross-partition move or ETag transfer.
A constant short id within each existing /playKey partition is another existing-container
variant. It keeps playKey readable and reduces only the duplicate id value, but still requires
dual-identity migration because existing item IDs cannot be renamed in place. Its smaller benefit
does not justify that migration either.
Option 2 - Replace the containers and partitioning¶
The higher-risk implementation would create new versioned puzzle and/or play containers with a
new partition-key path, such as /id, and remove the separate puzzleKey or playKey partition
property where the domain does not require it. A different partition such as /userId could be
considered only to solve a separately measured account-export or deletion-query problem, not to
save identity bytes. Cosmos partition-key paths cannot be changed in place.
Implementing this option would require everything in Option 1 plus:
- Design the new access pattern, partition cardinality, hot-partition bounds, TTL, indexing, evaluation-report placement, point-read contract, and cross-game compatibility.
- Provision versioned containers through Terraform and grant the application identity the required data-plane access without modifying the current containers.
- Add dual-container reads, controlled writes, deterministic conflict resolution, and telemetry that distinguishes old, new, fallback, duplicate, and divergent results.
- Backfill durable documents with an idempotent, continuation-token-based, ETag-aware, RU-bounded, resumable migrator; allow eligible TTL data to expire rather than rewriting it solely for uniformity.
- Reconcile writes racing with migration, validate counts and semantic checksums, switch readers and writers gradually, and retain a rollback release that understands both locations.
- Retire the old containers only after the maximum retention and rollback windows, audited account deletion, backup, recovery, and production validation have all completed.
Pros:
- it can remove a partition-key property instead of merely shortening its value; and
- a topology selected for an independently measured query problem could improve that access pattern as a separate benefit.
Cons:
- it introduces infrastructure, authorization, migration, reconciliation, monitoring, backup, rollback, and eventual container-retirement work;
- reads and writes can diverge across containers during rollout, risking duplicate, stale, or lost puzzle and play state;
- changing partitioning can regress point-read cost or create hot partitions;
- the shared puzzle and play stores make this a cross-game contract change rather than an isolated Reverse Cross optimization; and
- long-lived Daily puzzles require a durable migration path even though transient Practice puzzles and plays naturally expire.
Decision rationale¶
| Option | Maximum relevant measured category | Operational risk | Decision |
|---|---|---|---|
| Keep current readable keys | 20,942 bytes retained | None | Adopt |
| Compact keys in current containers | Less than the 20,942-byte category is recoverable | Medium | Reject |
| New containers and partitioning | Up to the 20,942-byte category is addressable | High | Reject |
The migration and permanent compatibility surface are disproportionate to at most approximately 1.50% of the sampled Reverse Cross JSON. Placement and puzzle-structure compaction target the dominant repeated payloads without changing Cosmos identity; compact document keys do not. Phase 10 is therefore complete as an evaluation and closed as not justifiable for the measured space saving.
Reopen this decision only if production measurements establish a material cost or reliability problem attributable to key size, or if a separately justified container migration can absorb this change without adding an identity-only migration. Growth in document count alone is insufficient; the evidence must include key-attributed storage or RU cost, affected access-pattern latency, a business target, and a migration risk budget.
Compatibility and migration strategy¶
Treat this as an expand/migrate/contract data rollout under the repository's production standards. Coordinate any scheduled implementation with the Reverse Cross Roadmap and record cross-game or infrastructure effects in the MiniGames Platform Roadmap.
Use an expand-write-contract rollout.
Release A - readers first¶
- Add explicit schema-version dispatch.
- Read v1 and v2 puzzle/play documents into the same domain model.
- Continue writing v1.
- Add golden v1 fixtures captured without production personal data.
- Verify APIs, completion, resume, export, merge, repair, deletion, and standings from both versions.
Release B - controlled v2 writes¶
- Enable v2 writes behind a server-side feature flag.
- Keep API and OpenAPI contracts stable unless a separate product requirement changes them.
- Monitor deserialization failures, conflicts, size, RU, latency, and fallback behavior.
- Roll back only to Release A or a later version that already understands v2.
Existing data¶
- Upgrade mutable v1 plays lazily when they are next written.
- Allow old Practice puzzles to expire naturally under TTL.
- Keep immutable Daily and fixture-backed documents readable through the v1 mapper.
- Run a background migration only for durable documents where measured savings justify its RU and operational cost.
- Do not rewrite all historical data merely to make the database aesthetically uniform.
Any background migrator must be idempotent, continuation-token based, ETag guarded, bounded for RU and throttling, resumable, and able to report document counts plus before/after byte sizes. Validate against an isolated copy or sanitized fixtures before production use.
If long-term storage cost warrants replacing v1 documents, use replace-in-place only when id and
partition key are unchanged. A changed partition identity requires writing a new document and
carefully retiring the old one; Cosmos cannot move an item between logical partitions in place.
Diagnostics and developer experience¶
Instrumentation and dashboards remain governed by the platform roadmap's cross-cutting observability plan. This work adds size, allocation, schema-version, and migration signals; it must not create high-cardinality telemetry.
Compact internal identities must not make the system opaque. Provide deliberate projections:
LexicalId.ToExternalString();CatalogEntryHandledebugger display through its owning snapshot;SlotReference.ToDebugString(puzzle);PuzzleIdentity.ToDebugString();- God View resolution of slot and entry ordinals to directions, coordinates, and display forms; and
- administrative migration reports that show both compact identity and resolved description.
Do not cache every formatted description on every domain object; that would recreate the memory problem. Format on demand in low-volume diagnostic paths.
Ordinary telemetry should continue using safe low-cardinality tags. Raw player IDs, word content, puzzle answers, placement lists, and high-cardinality composite identities do not belong in normal production metrics or traces.
Verification requirements¶
Each phase needs focused regression coverage plus the relevant full suites.
Catalog and index invariants¶
- Catalog content version and entry identity remain deterministic.
- Views contain exactly the entries allowed by their policy.
- A handle cannot resolve through the wrong snapshot.
- Letter Golf candidate sets and generated puzzle invariants remain unchanged.
- Reverse Cross candidate sets and deterministic seeds remain unchanged unless a versioned replay contract deliberately changes.
- Provenance, tags, score scales, and moderation decisions survive round-trip conversion.
Persistence invariants¶
- v1 and v2 documents project the same public DTOs and domain behavior.
- Canonical slot extraction is deterministic.
- Partial, paused, resumed, completed, abandoned, conflicted, and retried plays round-trip.
- Optimistic concurrency and idempotent completion remain correct.
- Account merge, export, deletion, stats replay, and group backfill work across mixed schemas.
- Historical plays remain meaningful after their Practice puzzle expires.
- Malformed ordinals, lengths, fingerprints, and schema versions fail closed.
Operational measurements¶
- retained managed memory and working set;
- cold and warm startup/first-request duration;
- cumulative allocations and GC behavior;
- final image and compiled-artifact size;
- average/p95 Cosmos document size and request charge;
- mixed-schema read/write latency; and
- migration throughput, throttle rate, and safe restart behavior.
Recommended implementation order¶
- Capture heap and Cosmos-size baselines.
- Remove redundant view/index identity arrays and dictionaries.
- Introduce snapshot-local handles and typed binary lexical identity.
- Compact source, score, tag, and language ownership.
- Re-measure and stop catalog work if the production envelope is healthy.
- Compile the canonical catalog artifact to improve cold start and allocation churn.
- Introduce structural Reverse Cross slot and bank ordinals internally.
- Add dual-read puzzle schema v2.
- Add dual-read play schema v2 and feature-flagged v2 writes.
- Migrate only durable data whose measured savings justify the cost.
- Consider flat grapheme/string tables, hashed Cosmos keys, a new container, or memory mapping only if simpler changes still miss explicit targets.
Explicit non-goals¶
- Do not shorten every JSON property into cryptic one-letter names.
- Do not globally intern unbounded source or player data.
- Do not persist snapshot-local integer handles as global catalog identity.
- Do not derive historical graphemes from a potentially changed current normalizer.
- Do not change Cosmos partitioning without a measured business and operational justification.
- Do not mix this work with unrelated game behavior, UI, or content-policy changes.
- Do not claim an optimization succeeded without production-class before/after measurements.
Decision gate¶
The preferred stopping point is the simplest representation that keeps production startup, steady-state memory, document size, RU consumption, and operational headroom within agreed targets. If typed handles, shared metadata registries, compact Reverse Cross placements, and a canonical compiled artifact meet those targets, retain the ordinary managed-object architecture. Escalate to memory-mapped structures or container migration only when measurements demonstrate that their additional implementation and operational complexity is warranted.