Flags — the ontology of a reader's commitment

# Flags — the ontology of a reader's commitment

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

Companion to [systems](systems.md) (which owns the *engine-side* weight of an interaction — does it fork,
what does it write) and [decisions](decisions.md) (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](systems.md)). 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.

| Nature | What it carries | Does it branch? | Where it pays |
|---|---|---|---|
| **`divergent`** | A commitment between continuations that genuinely differ in world state | **Yes** | Immediately and permanently: the route now differs |
| **`conditional`** | A small commitment that sets a condition something later reads | No | Deferred — a gate, a scene generated from state, an option that exists |
| **`personal`** | A commitment that expresses who the reader is being, and moves nothing | No | Reflectively — read back as a portrait of how they played |

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

| Verb | The act | Primary nature | Faculty trained |
|---|---|---|---|
| **`choose`** | Take one continuation over another | `divergent` (and `conditional` below a fork) | Commitment under partial information |
| **`guess`** | State what you think will happen, before the reveal | `conditional` | **Pre-cognition** |
| **`tell`** | Disclose, withhold, or say it *this* way rather than that | `personal` (and `conditional` when a seat learns something) | **Acting** |

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](README.md)). 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](decisions.md) 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:

```text
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](decisions.md)). 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](README.md), [systems §3](systems.md)):

- **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.

| Phenomenon | Derived from | Faculty it feeds |
|---|---|---|
| **Gating** — an option or route that only exists because of what you did hours ago | A pure predicate over `(route, ledger)` or branch state ([systems §3](systems.md)) | Pre-cognition — you learn that acts set conditions |
| **Taste / stance** — who you are being in this world | The *distribution* of your `personal` flags, not a separate mechanic | Acting |
| **Stance coherence** — whether you held a character or drifted | Consistency of that distribution across a route; drift is information, not error | Acting |
| **Attention and omission** — what you never looked at | The cursor's seen-set against what the frame actually contained | Pre-cognition — the world was denser than your sample |
| **Timing and restraint** — acting now versus holding | When a flag was set relative to the window's close (arc grain already gives the unit) | Pre-cognition |
| **Conviction** — how much you'd stake, separate from what you picked | `stake`, priced by Scenario's existing conviction economy | Pre-cognition — calibration, distinct from correctness |
| **Attribution** — which source you believed when two conflicted | A `guess` whose content names the evidence it rested on | Pre-cognition |
| **Register** — warmth, cruelty, deflection | The content of a `tell`, read as characterisation rather than preference | Acting |
| **Dramatic irony** — you know what the character does not | Reader seen-set versus seat projection, two stores already kept apart ([systems §5](systems.md)) | Acting |
| **Perspective cost** — what the other seat could not have known | Re-reading a produced route from a different seat; zero new assets | Acting |

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](systems.md) 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:

| Harvest | Reads | Serves |
|---|---|---|
| **World harvest** | A later scene generated *from* the state the flag moved — not a reference to it | `divergent`, `conditional` |
| **Gate harvest** | An option, route, or ending that exists only because the condition cleared | `conditional` |
| **Mirror harvest** | An ending card that reads back the reader's own record: the stance they played, what they anticipated, what they never looked at | `personal`, and the calibration half of `guess` |

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](systems.md)).
- **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](README.md)).
- **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](systems.md)).
- **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:

```text
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

| Requirement | State | Where |
|---|---|---|
| Typed relationship, thread, knowledge, and ownership deltas (the world-side half) | **shipped** | `FrameDelta`, `ThreadDelta.updates`, `WorldDelta.addedNodes`, `OwnershipDelta` |
| Priced futures with an as-of vantage (`asOfEntryId`, `contextScope`) | **shipped** | `Reading`, `Future` |
| Seat projection and concealment regimes (what a `tell` may address) | **shipped** | `projectForSeat`, `scenario.ts` |
| Conviction economy (the `stake` field in live posture) | **shipped** | `scenario.ts` |
| Arc grain as the timing unit | **shipped** | `SCENES_PER_ARC` |
| **The flag record itself (`nature` · `verb` · `vantage` · `stake` · `content`)** | **build** | playthrough ledger beside the cursor, never canon |
| **Nature disclosure in the reader (branching labelled, others in-flow)** | **build** | reader surface ([reader.md](reader.md)) |
| **`guess` affordance before a reveal, priors withheld** | **build** | reader surface |
| **`tell` affordance for disclosure and register** | **build** | reader surface, seat-bounded |
| **Derivations (gating, coherence, omission, timing, calibration)** | **build** | pure derivations in `core` over `(ledger, world state)` |
| **Mirror harvest on the ending card** | **build** | reader surface |
| **Harvest detector (a flag nothing downstream reads)** | **build** | pure derivation |

---

## 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](systems.md) 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.

Raw Markdown source