docs: bring reader-authored games and events into scope
The release thread's only feature request from the reader with the most games,
asked twice and asked for nothing else. No adapter roadmap reaches a ten-game
juggler, so this is the part of the product that serves readers we will never
scrape for.
Records the decision in the PRD as F13 rather than letting the code drift from a
spec that still lists user-submitted events as out of scope, and specifies the
key spaces in DATA-MODEL before any of it is built — a reader's event must never
be minted as ${game}:${slug}:${date}, because they can type a title identical to
a scraped one and the collision would silently share one completion mark, note
and streak between two events.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
This commit is contained in:
co-authored by
Claude Opus 5
parent
1dd58d3f52
commit
4029885833
@@ -319,6 +319,63 @@ would stop a later parser improvement from ever reaching that event. This is the
|
||||
`progress` that changes what the app *shows* rather than recording what the reader did, which is
|
||||
why it lives beside their other notes rather than in the feed.
|
||||
|
||||
### Reader-authored key spaces
|
||||
|
||||
PRD F13 lets a reader define their own game and enter their own events. Those records get their own
|
||||
ID spaces, and the reason is the one this document keeps making:
|
||||
|
||||
```
|
||||
mygame:<slug> a game the reader defined "mygame:limbus-company"
|
||||
myevent:<random> an event the reader entered "myevent:k3f9qa2m"
|
||||
```
|
||||
|
||||
**A reader's event is never minted as `${game}:${slug}:${date}`.** That space is derived from source
|
||||
titles, and a reader can type a title identical to a scraped one — same game, same start date, same
|
||||
slug, same key. Two records under one key means one completion mark, one note and one streak
|
||||
silently belong to both, and the collision is invisible until someone notices their progress moving
|
||||
on its own. A random suffix makes that impossible rather than unlikely.
|
||||
|
||||
The randomness buys a second property worth keeping: **renaming your own event does not move its
|
||||
ID.** A feed event's ID follows its source title, so a wiki renaming an event mints a new ID and
|
||||
reconciliation has to recognise the near-match to preserve marks. A reader's event has no source to
|
||||
follow, so its ID is assigned once at creation and never derived from anything they can edit.
|
||||
|
||||
Three first segments are now reserved and **none of them may ever become a `GameId`**: `dailies`,
|
||||
`mygame`, `myevent`. A test asserts this against `GameId.options`, because the day that stops being
|
||||
true is the day two key spaces merge silently.
|
||||
|
||||
```ts
|
||||
"gacha-tracker:v1:customGames" // { [id]: { id, name, hue, at } }
|
||||
"gacha-tracker:v1:customEvents" // { [id]: { id, game, title, type, summary,
|
||||
// startsAt, startPrecision,
|
||||
// endsAt, endPrecision, at, updatedAt } }
|
||||
```
|
||||
|
||||
Reader-authored events reuse `progress`, `daily` and `ignored` unchanged, keyed by their `myevent:`
|
||||
id — everything the reader can say about a scraped event they can say about their own, with no
|
||||
second set of stores to keep in sync.
|
||||
|
||||
Field rules mirror the feed's, because the reader deserves the same guarantees the parsers are held
|
||||
to:
|
||||
|
||||
| Rule | Why |
|
||||
|---|---|
|
||||
| `endsAt` null pairs with `endPrecision: "unknown"` | The same invariant `GachaEvent` enforces. "I don't know when this ends" is a supported answer for a reader too, and a required one — otherwise entering an unannounced event forces them to invent a date |
|
||||
| A date with no time is `"day"` precision, a date with one is `"exact"` | So the UI's existing "accurate to the day only" note is honest about their input as well |
|
||||
| `endsAt` must be after `startsAt` | A backwards interval is a typo whoever made it |
|
||||
| `hue` must match `#rrggbb` | It reaches a `style` attribute, and an imported file is not necessarily one the reader wrote |
|
||||
| `regionScoped` is always false | They entered one instant, not a per-region map. Claiming otherwise would fabricate three timestamps out of one |
|
||||
|
||||
There is deliberately **no `dailyTasks` for a custom game**, so it contributes no standing
|
||||
`dailies:<game>` chore. That list is the routine every player of a tracked game recognises; asking a
|
||||
reader to invent one is a form to fill in for a reminder they already have. Their events can still be
|
||||
marked as repeating, per event, like any other.
|
||||
|
||||
**Deleting.** Removing your own event leaves any marks and logged days behind rather than reaching
|
||||
into three other stores on a single tap; they are inert, and the alternative is a misclick that
|
||||
deletes a streak. Removing a game that still has events is refused and says how many, rather than
|
||||
cascading.
|
||||
|
||||
### Migration from `completions`
|
||||
|
||||
`completions` used membership to mean "done", which cannot express "started". `progress` replaces it
|
||||
@@ -353,10 +410,26 @@ old key.
|
||||
"dailies:genshin": { "days": ["2026-08-14", "2026-08-15"], "at": "..." }
|
||||
},
|
||||
"ignored": { "zzz:some-event-i-skip:2026-08-19": { "at": "..." } },
|
||||
"customGames": {
|
||||
"mygame:limbus-company": { "id": "mygame:limbus-company", "name": "Limbus Company",
|
||||
"hue": "#c74b50", "at": "..." }
|
||||
},
|
||||
"customEvents": {
|
||||
"myevent:k3f9qa2m": { "id": "myevent:k3f9qa2m", "game": "mygame:limbus-company",
|
||||
"title": "Walpurgisnacht", "type": "banner", "summary": null,
|
||||
"startsAt": "2026-08-20T00:00:00.000Z", "startPrecision": "day",
|
||||
"endsAt": "2026-09-03T00:00:00.000Z", "endPrecision": "day",
|
||||
"at": "...", "updatedAt": "..." }
|
||||
},
|
||||
"prefs": { "region": "europe", "hiddenGames": [], "sort": "ending", "onboarded": true }
|
||||
}
|
||||
```
|
||||
|
||||
`customGames` and `customEvents` are additive keys, so a v1 export written before F13 simply lacks
|
||||
them — not an error, just a file from a device that had none. They merge by id like everything else,
|
||||
and because an event and the game it belongs to travel in the same file, an import never lands an
|
||||
event whose lane is missing.
|
||||
|
||||
Import **merges** every set: a mark present in either the file or the current device survives, and
|
||||
import never removes one. `daily` merges as a **union of days per ID** — every day either side
|
||||
recorded is a day the reader actually played. An export written before daily checklists existed
|
||||
|
||||
Reference in New Issue
Block a user