gacha-event-tracker/docs/superpowers/specs/2026-11-01-content-classification-design.md

# Source classifications, Miliastra and battle-pass cycles

Date: 2026-11-01. Status: approved by the owner; implemented and verified.

## Intent and evidence

The owner reported Genshin duplicates, then compared the tracker against the
game. The walkthrough is recorded in `../../2026-11-01-genshin-event-audit.md`.
It confirmed ten timed Genshin activities, one probably claimed anniversary
reward, Moontrace as a battle pass, and five named Miliastra items. It established
no additional duplicate pair requiring broader fuzzy matching.

The cached Genshin Fandom table already states:

- Moontrace: `In-Game, Battle Pass`.
- Silvery Moonlight Chronicle: `In-Game, Miliastra Pass, Miliastra Wonderland`.
- Raiment Collection, Starlit Gala: Wonderland Selects and Starlight Voyage:
  `In-Game, Miliastra Wonderland`.
- Starlit Gala: `Web, Miliastra Wonderland`.

The parser currently reduces these labels to `EventType` and loses the useful
distinctions. Cross-source merge already folds the selector, Stygian and
To Temper pairs. ReaderApp already filters ended rows and reconciles previously
seen ones into Archive: old rows in the feed do not establish a display bug.

The owner chose source-driven classification over a maintained title table, and
originally requested a show/track TCG toggle in Genshin's About tab, then
explicitly moved it to Setup after trying the release. The current location is
Setup, immediately below What to track.

## Approaches

1. **Preserve classifications from sources (selected).** Labels route new
   Miliastra activities and passes without editing a list every patch. Costs an
   additive feed field, shared classification rules and progress-safe routing.
2. **A title-to-category table.** Smaller initially, but new poetic titles need
   continual upkeep and unknown titles silently return to the wrong section.

Use reviewed family/link mappings only where the source's category vocabulary
needs interpretation. They are deterministic, evidenced rules, never a fuzzy
title classifier or a replacement for source labels.

## Goals, boundaries and constraints

- Miliastra Wonderland is an independently selectable built-in lane.
- Source-dated battle passes are tracked through Cycles, once per pass window.
- Genshin's Setup tab controls whether its TCG events are tracked.
- Notes, completion, ignores, daily logs, amounts, history and clock references
  survive reclassification, import/restore and repeated application.
- Keep IDs, source URLs, source IDs, dates, precision and the current matching
  threshold unchanged. No additional fetches or dependencies are needed.
- Reader-created games, events and routines are not classified automatically.
- Do not invent schedules for missing content or create a row for an umbrella
  notice. Wonderland Treasures: Moonlight After the Rain remains unpaired.
- Do not merge Starlit Gala and Wonderland Selects. Their source classifies one
  as Web and the other as In-Game; similar names do not establish duplicate work.
- Do not turn the owner's rounded countdowns into precise timestamps, or their
  probable Rainbow's End claim into completion state.

## Classification and compatibility

Add optional structured classification to `GachaEvent`: destination lane,
battle-pass activity, and TCG tag. Exact property names are the builder's call;
the distinctions and compatibility below are required. The original `game`
remains the source/identity game in the wire feed. For example a Miliastra row
continues to carry `game: genshin` and its existing `genshin:...` ID, with an
additive destination of `miliastra`.

This separation is deliberate: changing the wire `game` to a new enum value
would cause old cached clients to reject the entire feed. Old clients strip
optional metadata and continue their previous behavior; new clients resolve a
logical destination for rendering and tracking. Old cached feeds still parse.
Register Miliastra's metadata for the new client without emitting a new game
value in old wire fields. Do not alter `slugify` or `eventId`.

Parsers preserve stated classifications, including established pass-only source
registrations (Nameless Honor, City Fund and Mira Journey). Merge retains
classification supplied by either matched source even when the identity winner
lacks it; date and title selection do not change. Explicit incompatible
classifications are reported and left unresolved rather than guessed. Absent
classification is not evidence against a stated classification.

For older feeds and saved event snapshots, a shared deterministic resolver may
recognize established source article paths and the owner-confirmed families.
Keep each rule's evidence beside it. Unknown content stays in its original lane
and ordinary-event category. The new parser metadata is the ongoing mechanism;
the compatibility rules protect cached/offline readers and existing history.

## Miliastra lane and saved state

Miliastra can be enabled, hidden, focused and ordered separately from Genshin.
It uses Genshin's established server/reset defaults; do not invent a different
clock. No standing daily task or new Miliastra routine is invented. Sources and
freshness reflect the same underlying Genshin source(s) that supply its rows;
there is no second request and no claim of a fresh independent source.

Like other newly added lanes, it arrives off for existing readers and is
available in setup for new readers. This lane setting takes precedence over
preserving a relocated pass's visibility: Silvery Moonlight Chronicle stays
hidden until Miliastra is enabled, with its follow/pin preferences and progress
retained. Enabling the lane restores its eligible placements. Genshin's Setup tab includes a short pointer
to Miliastra's settings so the relocated activities are discoverable.

Reclassification resolves storage as well as presentation. Use a persisted
origin-to-destination account mapping, one Miliastra counterpart for each
Genshin account whose identified Miliastra state must move. Preserve region and
clock history when establishing that counterpart, including historical revision
IDs referenced by logs; do not relabel day keys or remint event IDs. Distinct
origin accounts remain distinct even when their current region matches.
Mapped counterparts subsequently have independent settings and clocks.

Only classified source-authored Miliastra records move: progress, ignores,
daily/amount logs, seen/unread state, seen snapshots and Archive records. Leave
unrelated Genshin data and reader-created content alone. Historical archived
snapshots retain the meaning of their saved clocks and resolved boundaries.
Retired origins with moved history get a retired counterpart, not a new active
subscription. Empty counterparts need not be created until tracking is enabled.

The routing operation runs through the reader's lock/reducer/save path and is
idempotent. A failed save changes no visible ownership. Carry field timestamps
and deletion tombstones so reopening, old-tab writes, importing old backups or
clearing a migrated mark cannot resurrect data. Transfers are moves, not copies
repeated on every load. Export/import and restore retain the account mapping;
newly encountered legacy records for a mapped activity use that mapping. Never
route an old import into an arbitrary same-region account. The implementation
plan must spell out field-path rebasing and collision rules before coding.

## Pass windows in Cycles

This supersedes the ordinary-event presentation chosen in the 2026-10-16
pass-windows design; its date discipline and source coverage still apply.

Represent a pass as a feed-backed cycle window, preserving the event's existing
ID and account-scoped progress. Its sourced start/end and precision govern its
deadline. Do not express it as a fixed 42-day recurrence or reset it from a
version estimate. A new run is another sourced window, never an inferred one.

Passes are available in Routines under Cycles and follow existing independent
Checklist/Timeline placement controls. They can participate in next-deadline
guidance when followed and pinned to Checklist; a timeline-only pin does not
create a Checklist instruction. An ordinary event row for that same pass must
not render as well. Done/ignored/notes/history still use the existing pass ID;
there is no duplicate task ID or second progress store.

Follow/pin preferences belong to the pass family per account, so the next sourced
window inherits the choice while each window retains its own progress. Weekly
Battle Pass EXP remains a separate weekly routine. For existing readers who
track events, preserve pass visibility in enabled lanes by following/pinning
their existing pass family during the transition, without enabling other cycle
routines. Hidden lanes remain hidden, including newly offered Miliastra. New
readers follow passes through Cycles. An account can follow passes with ordinary
Events turned off. Silvery Moonlight Chronicle is a pass under Miliastra.

## Genshin Setup: TCG switch

Use the existing settings control style, with label **Track TCG events** and
supporting copy **Show Genius Invokation TCG events in your lists and timeline.**
This is a game-wide preference across the reader's Genshin servers; other
tracking controls can remain per account. Absent means on, preserving existing
coverage. Save immediately through the existing prefs action; display save
failure and restore the saved switch position when persistence fails.

Off removes classified TCG events from live Checklist, Timeline, next-deadline
guidance, focus counts and event-derived daily/check-in instructions. It does
not mark them ignored/done, archive them merely for being hidden, delete data,
or erase existing history. On restores eligible unfinished rows with all their
progress. It is a tracking preference, not an Archive filter; existing history
stays readable. No generic event-type filter or Miliastra setting changes.

Recognize TCG from explicit source categories, or an evidenced mapping from the
source's named TCG families/article paths. The owner's Forge Realm confirmation
is one such record. Broad words such as card, battle or challenge are not enough.
Apply the same resolver to saved snapshots so a cached copy cannot bypass the
switch. Reader-authored content is unaffected.

## Expiration and remaining deduplication

Reproduce the audited old rows through the current client, including remembered
seen-event snapshots and regional reset boundaries. Verify they are absent from
live guidance after their resolved ends and that previously seen events retain
history. Repair a demonstrated failure only; don't drop unknown-end events,
retire on raw UTC-midnight placeholders or remove historical records.

Keep current cross-source matching and `mergedIds` carry-forward. Add regression
coverage for the confirmed selector pairs and differently named seasons, and
for separate Starlit Gala activities and consecutive character trials. A
classification change does not itself establish event equivalence.

## Validation and delivery

Plan implementation in independently verifiable parts: additive classification
and merge; progress-safe lane routing; feed-backed pass cycles; TCG control;
expiration verification and documentation. State protection ships before its
dependent presentation changes. No commits or pushes unless asked.

Required checks include:

- Fixture parsing preserves all existing IDs/dates and extracts the stated labels;
  the identity winner retains the loser's classification.
- Old feeds remain readable; every wire game value remains accepted by the old
  feed contract. Unknown classifications preserve ordinary-event fallback.
- Multi-account lane routing preserves clocks, progress, logs, notes, history,
  tombstones and unknown fields across reload, import/restore and late writes;
  repeated routing and failed saves do not duplicate or lose records.
- Pass completion survives relocation; future sourced windows inherit follow
  and pins, not completion; Events off / Cycles on works; no duplicate row.
- TCG on/off/reload/failed-save behavior affects every live surface, preserves
  history and applies to remembered source rows, with independent Genshin servers.
- Browser checks at desktop/mobile sizes, both themes, and an ordinary HTTP
  hostname cover startup, migration and writes. Use fresh build origins per
  AGENTS.md. Shell-only builds must not refresh source snapshots.
- Appropriate targeted tests, full suite and typecheck. Feed before/after diff
  accounts for every changed field and confirms no ID or date moved.

Update PRD, DATA-MODEL, INGESTION, DESIGN and relevant prior specs when their
behavior changes; record the pass-window decision's supersession and source
identity versus destination-lane semantics. Reader-visible changes receive the
repository's changelog treatment when committed.

## Proposed defaults to review

The owner chose source-driven routing and requested the TCG control. The
following are design proposals: TCG defaults on and applies across Genshin
servers; Miliastra arrives off like other new lanes; existing followed pass
visibility in enabled lanes is preserved during its transition to Cycles. A fresh
builder review found the conflict between this default and Miliastra arriving
off; the proposal above explicitly gives the lane setting precedence. The owner approved these defaults before implementation.