Flags — the ontology of a reader's commitment

Status: rough spec (direction). Not an implementation contract; nothing here ships until scheduled.

Companion to systems (which owns the engine-side weight of an interaction — does it fork, what does it write) and decisions (which owns when a fork may stop a reader at all). This document owns the axis neither covers: what a commitment is as a record, what it carries, and which human faculty it trains. Systems.md grades by cost to the engine; this grades by consequence felt in the reader. Both are needed and they are orthogonal.

A flag is a recorded act of Will at the reader's grain. It is not a hidden integer. It is what a person committed to, from what vantage, and what it will later be read against.

The vocabulary is deliberately reclaimed. A hand-authored visual novel uses flags because it cannot afford to hold a world, so a flag stands in for state it could not otherwise keep (systems §2). That critique is unchanged and still correct: we do not store flags instead of world state. A flag here is the reader-side half of a commitment — the personal ledger beside the cursor — and the world-side half is always a typed delta or nothing at all.

---

1. Compression first — two axes, six values

The design constraint that governs this whole document: the fewer mechanics the reader must learn, the more depth the world underneath can carry. Every mechanic added at the surface is paid for twice — once in explanation, once in the optimising posture it invites. So the ontology is two small enumerations and nothing else.

Nature — what the flag carries. This is disclosed to the reader.

Verb — how it was elicited. This is how the reader meets it.

Three verbs, three natures. The rule that keeps this compressed: no fourth verb is added without removing one. Pre-cognition and acting are the two faculties the design exists to nurture, and each has exactly one verb; choose is the third because a story with no fork is not this medium.

---

2. Nature is disclosed; the reader is never guessing about weight

This follows directly from the delivery spec's rule that a commitment must announce its posture (README §3). Nature is the finer-grained version of the same honesty:

• divergent is labelled as branching — it takes the choice screen, it takes confirmation weight, it stops the work. In live posture it additionally spends Will and may not resolve the reader's way, which is a further escalation and must look like one.
• conditional and personal never stop the work. They occur inside the flow of a scene, at the grain the medium actually plays them, and they never wear a fork's affordance.
• What is disclosed is the nature, never the outcome. "This will change the shape of what follows" is honest. "This leads to the good ending" is a prior shown before the choice, which decisions §4 already forbids.

The failure mode this prevents is the medium's most-mocked line: consequence signalled where none was recorded. A flag may only claim the weight its nature actually carries, and its nature is a property of the typed deltas beneath it — not a writing decision made at the surface.

---

3. The record

One shape, five fields, and only the first two are surfaced:

Flag {
  nature   divergent | conditional | personal    — what it carries (shown)
  verb     choose | guess | tell                 — how it was elicited (shown as affordance)
  vantage  the cursor it was taken from + the seat that took it
  stake    what the reader put behind it (nothing, or conviction in live posture)
  content  the commitment itself: the continuation, the prediction, or the disclosure
}

Vantage is the load-bearing field, and it is the same discipline the rest of the instrument already holds: a Reading records asOfEntryId + contextScope so a priced fan of futures cannot quietly acquire hindsight (decisions §4). A flag inherits that exactly. A prediction is only evidence about foresight if the moment it was made is recorded, and an acting choice is only characterisation if the information the reader held at the time is known. A flag without a vantage is an opinion; with one it is evidence.

Where the record lives is decided by posture and is not negotiable (README §4, systems §3):

• Traversal. Flags accumulate in playthrough state — a per-reader ledger beside the cursor, outside canon, disposable. Losing it loses a portrait, never content.
• Live. The commitment goes through a bounded Scenario, the deltas are real, the branch preserves them, and the flag is the reader-side shadow of a governed write.

---

4. Everything else is derived, not elicited

This is where the compression pays. The interesting phenomena are not additional mechanics; they are projections over the ledger and the world state that already exists. Nothing below adds a verb.

The design test for any future proposal: if it can be derived from (nature, verb, vantage, stake, content) plus world state, it is not a new mechanic and must not become one.

---

5. Harvest — three kinds, and every flag needs exactly one

Systems §2 established the harvest rule: an axis that nothing downstream reads is decoration, and it is detectable. The ontology extends it by naming the three legitimate harvests, because assuming only the first is what makes personal flags look like the cheap tier when they are in fact a whole faculty:

The mirror is the cheapest high-value surface in the design — it produces no assets, generates nothing, and is the only place the two target faculties become visible to the person developing them. It is a portrait, never a score (§6).

---

6. Refusals

Each refusal exists because it converts inhabiting into optimising, which is the one failure that destroys both target faculties at once.

• No scores, meters, or thresholds shown as numbers. A gate is stated in world terms — "because she has stopped hedging with you" — or it is not a gate (systems §3).
• No live readouts. Calibration and stance are shown after an ending, retrospectively. A visible accuracy meter turns a guess into a puzzle to be solved rather than a judgement to be made.
• No leaderboards, ranks, or comparison against other readers. The faculties are personal capability; ranking them recruits an entirely different motivation and the wrong one.
• No timers or QTEs. Pressure comes from the world's closing window, never from the clock.
• No priors before commitment. Restated because it will be argued for on helpfulness grounds (README §3).
• No consequence claimed without a delta. "X will remember that" over state that was never written is the lie the medium is mocked for.
• No universal personality inventory. A personal flag is read against this world's axes; importing a generic profile flattens the particular world into a test (systems §8).
• The engine never sets a flag. Auto and skip advance presentation only; a resumed save restores a position rather than replaying a decision; no recommendation appears where a commitment is asked for. Will is injected from outside the simulation, and a flag is the record of that injection.

---

7. Why this trains anything — stated as a hypothesis

The claim is that repeated, immersed play develops pre-cognition (anticipating consequence before it is revealed) and acting (inhabiting a person and holding it under cost). That is an empirical claim about transfer, and this spec does not assert it. It states the mechanism and the measurement that could falsify it:

guess at vantage V  →  world resolves  →  calibration curve over a route, and across routes
tell at vantage V   →  stance distribution  →  coherence under increasing cost

• Pre-cognition is measurable here in a way it usually is not, because a prediction has a recorded vantage and the world has a real prior to resolve it against. Whether the curve improves — and whether it improves faster for readers who return — is a question the ledger can actually answer.
• Acting is measurable as coherence, not as quality. Whether a reader held a stance when it cost them something accumulated is derivable; whether that constitutes better acting is not, and the spec should not pretend otherwise.
• Neither measurement may be shown live, which means both are research instruments and mirror surfaces rather than game systems (§6).

Held to the same standard as the rest of the instrument: reproducible is not the same as valid.

---

8. The honest ledger

---

9. Open questions

1. Is guess opt-in or ambient? Opt-in keeps the surface clean and self-selects the readers who want the training; ambient produces a far better curve and risks the puzzle posture.
2. How much of the ledger is visible mid-read — nothing (purest), named relationships only, or a full readout after an ending (systems §8 carries the same question for accumulation)?
3. Does a tell in traversal posture ever reach canon if a Director accepts a playthrough as history, or does traversal stay strictly non-writing?
4. Who authors the axes a personal flag is read against — derived from the Domain's own themes, or declared per production? Derived is more honest and harder.
5. Does a wrong guess change what is delivered? Tempting (a world that answers your misprediction pointedly) and dangerous (the world teaching to the test).
6. May a divergent flag ever be presented without its nature disclosed, for a work that wants the reader not to know a fork was a fork? My instinct: no — the honesty rule outranks the effect.