Journal
This page owns the player-facing Journal for Game 1. The Journal is the structured persistent memory layer: an ordered ledger of what the MC records, what the player has learned, and which active planning or world surfaces still depend on that memory.
The Journal is not a one-time popup, a raw event dump, or the combat Chronicle. It is the durable memory record for survival, discovery, objectives, clues, missions, territories, sites, characters, and lore artefacts.
Role
The Journal should answer three questions:
- What changed that the MC would keep?
- In what order did it change, and under which branch or precondition did it land?
- What can the player reopen later when they need context, evidence, or a live planning link?
The Journal keeps the Act 0 through Act 7 campaign readable across long play sessions. It preserves first-person or close-perspective uncertainty without turning hidden cosmology into omniscient exposition.
Ownership Boundaries
- Journal owns persistent day-based memory, written entries, annotations, rereadable discoveries, and cross-links back into planning and world surfaces.
- Current Plan owns urgency and short-horizon synthesis.
- Objectives owns active objective, clue, and mission structure.
- Territory Dossier owns deep place inspection for the currently selected Territory.
- Combat Chronicle owns encounter-by-encounter combat readback and remains distinct from Journal.
Record Model
Every Journal entry is a stable record, not just a paragraph. The record must carry:
- an immutable
entry_id - a day bucket label for organization
- explicit sequence or order within that bucket
- an entry class
- a title
- readable prose
- linked objective, clue, mission, activity, territory, site, character, artifact, feature, or threat ids when relevant
- tags
- a branch key
- preconditions or state gates
- later annotations layered on top of the base record
The Journal is persistent because the record shape is persistent. The prose is one field inside the record, not the whole model.
Day Buckets And Sequence
Journal entries are grouped by in-world day because that is readable to the player, but the day label is organizational only. A day page is a memory bucket, not a story gate.
Each day bucket should support:
- a day header with date, broad state, and place context
- ordered entries whose sequence preserves when the MC learned or decided something
- expandable linked records for objectives, clues, missions, territories, sites, features, threats, characters, and lore artefacts mentioned in that bucket
- a running annotations area where the player can pin, mark, or comment on unresolved details
The Journal must remain useful even when the player returns many in-game days later. Day grouping is for reread and recall. Sequence and preconditions carry the actual progression meaning.
State Gates, Not Calendar Gates
Journal progression is state-gated. Entries land when explicit preconditions resolve: an objective becomes active, a clue becomes legible, a mission completes, a territory reaches the required knowledge state, a branch is joined or rejoined, or a named survival threshold is crossed.
A calendar rollover alone does not emit a Journal entry and does not unlock the next beat. The player may camp, train, scout, or repeat routines across many days without auto-promoting later-act story beats until the relevant state gate fires.
Entry Classes
The Journal supports multiple entry classes. These are Journal types, not new runtime planning nouns.
- Day Opening - the day's opening condition, pressure, and immediate state
- Observation - what the MC noticed in the field without claiming more than the MC knows
- Objective Shift - a meaningful change to an objective, clue, or mission
- Discovery - a site, feature, person, artefact, route, or truth newly made legible
- Decision - the player's chosen approach, vow, priority, or working theory
- Outcome - the outcome of a mission, expedition, night, or other bounded effort outside combat-round readback
- Lore Record - a recovered book, inscription, journal, map, relic, or other readable artefact plus the consequence it creates
- Condition Record - a survival-state turn such as hunger, cold, exposure, fatigue, or loss that matters to the story memory of the day
Dynamically generated quest events — a Feature escalating due to ignored pressure, a route becoming dangerous, a settlement shortage reaching a threshold — produce Outcome or Observation entries in the Journal, not a separate entry lane. The generator rules for which world-state changes produce Journal hooks are documented in ../systems/gd-dynamic-quest-pressure-model.md under "Output Planning Artifacts". The Journal's ownership of entry classes is unchanged; the dynamic contract only specifies which preconditions cause entries to land.
Links And Tags
Entries may link to:
- objectives
- clues or leads
- missions
- activities
- territories
- features
- sites
- characters
- lore artefacts
- threats or pressures
These links are metadata and navigation, not prose. The Journal may also carry
tags for filtering and later recall, such as survival, weather,
first-night, ward-sign, ruin, people, threat, or theory.
A linked activity surfaced on a Journal entry is a canonical opener for the
shared Activity Detail inspector defined in
gd-shell-screen-model.md § Activity Detail.
Opening an activity link from a Journal entry passes journal opener context to
Activity Detail: source surface 'journal', the activity def id, and the
journal entry reference. The Journal does not own activity execution state; it
links to Activity Detail for inspection and to Queue for execution. Journal
prose remains the durable readback; Activity Detail is transient and does not
render Journal prose inline.
Annotations
The player should be able to annotate Journal content without corrupting the base record. Supported annotation shapes include:
- pinning an entry as strategically important
- adding a player note or question
- marking a theory as likely, doubtful, or disproved
- bookmarking an entry for later narration or investigation
Annotations are layered over the Journal record. They do not rewrite the original day entry.
Journal-Triggered Modals
Some Journal entry classes — specifically Decision entries that present a branching player choice, and Discovery entries that present a major narrative discovery — surface a FloatingSurface modal at the moment the corresponding entry's state gate resolves. The modal is the canonical way to demand player attention for a beat that should not be quietly logged.
The modals the Journal triggers are:
PendingChoiceModal— branching or story choice, where the player must pick a continuation before the Journal records the Decision entry. The Journal entry's downstream consequence depends on the chosen branch.FeatureDiscoveryModal— major Discovery beat where the narrative surfaces a Feature, Site, lore artefact, or world fact the MC has just earned. The modal may present a choices array (becomes buttons) or fall back to a single Acknowledge button.
Routine Journal entries — Day Opening, Observation, Outcome (non-major), Condition Record — must not raise a modal. They land in the Journal directly. The modal allowlist for Valenar lives in gd-shell-screen-model.md § Modal Taxonomy; the Journal follows that allowlist without extension.
This page does not commit to which specific quests, lore branches, or world facts trigger which modal; that belongs to the story and quest design docs.
Readable Prose And Structured Metadata
Each Journal record owns one readable prose field plus the structured metadata around it. The prose is what the player rereads in the Journal. Links, tags, branch key, preconditions, and annotations remain structured fields rather than being baked into the paragraph text.
This page does not define a second authored prose schema for alternate presentation modes. Any later transformation of Journal text for another surface is downstream of the Journal record and must not fork Journal authorship inside this owner doc.
Design Rules
- Journal is persistent. Never reduce it to a one-time popup or an ephemeral banner feed.
- Journal is structured memory, not a prose-only log.
- Journal should preserve uncertainty-first narrative framing, especially in Act 0 and early mystery chains.
- Every entry must be traceable to explicit preconditions and a stable
entry_id. - Day labels organize memory; they do not gate story progression.
- Branch-sensitive entries must carry branch keys and explicit rejoin conditions.
- Journal entries must create or clarify playable context. A lore artefact with no downstream consequence belongs outside this surface.
- Journal should let the player move from prose to the linked objective, mission, dossier, or queue row that now matters.
- Combat blow-by-blow belongs in Chronicle, not in Journal.
Runtime Status
The current implementation already ships a dedicated Journal query/version/client path and keeps Journal separate from the combat Chronicle at the accepted baseline. That runtime slice is still narrower than the full contract above, and the remaining follow-through is explicit:
- stable immutable entry ids across every runtime-issued record remain partial
- explicit sequence ordering, branch keys, and precondition enforcement remain partial
- annotations and player-authored notes remain deferred
- deeper Current Plan linking back into Journal context remains deferred
- richer site, lore artefact, character, and faction metadata remains deferred
- state-gated entry issuance across Journal, Objectives, Current Plan, and Territory Dossier remains partial
- Journal activity link → shared Activity Detail inspector (opener-context tag
'journal') remains deferred; the Wave M target architecture is described in § Links And Tags
Cross-surface runtime constraint. The Journal, Objectives, Queue, and
Territory Dossier have live runtime counterparts that constrain doc updates:
Host/ReadModels/JournalReadModel.cs, Host/ReadModels/ObjectivesReadModel.cs,
Host/ReadModels/PlayerActivityQueueReadModel.cs, and
Host/ReadModels/TerritoryDossierReadModel.cs. The client surfaces are
Client/src/hooks/useJournalDossier.ts, Client/src/hooks/useObjectivesDossier.ts,
Client/src/hooks/useTerritoryDossier.ts, and Client/src/api/types.ts.
Doc updates that introduce new fields, drop existing fields, or change
surface semantics must be checked against these paths before dispatch.
Implementation status
| Surface / Behavior | Shipped wave | Status |
|---|---|---|
| Journal query / version / client path | Wave C | Ships at the accepted baseline; deeper structure remains partial per § Runtime Status |
Journal-triggered modals (PendingChoiceModal, FeatureDiscoveryModal) | Wave C | Ships per the modal allowlist in gd-shell-screen-model.md § Modal Taxonomy |
Journal activity link → shared Activity Detail (source: 'journal') | Deferred | Journal-to-activity navigation is deferred; the target opener-context contract lives in gd-shell-screen-model.md § Activity Detail |
Stable immutable entry_id across every runtime-issued record | Partial | See § Runtime Status |
| Annotations and player-authored notes | Deferred | See § Runtime Status |
| Recursive drill from a journal-origin Activity Detail | Deferred, Wave B | Requires parent-run / child-run reference projection on the activity run snapshot — Wave B-owned, pending sync |