# Instrumented open-source game seeds (YSD-14173)

What this directory holds, why the game had to be rebuilt rather than read, and
what a recorded session does and does not contain about a person.

## The five things the item names

| requirement           | where it is                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| reproducible build    | `stk-session-lock.json` → `attestation` — source tarball, instrumentation, toolchain, cmake options and binary, each by digest |
| connector             | `stk-session-stream.ts` (reader) and `stk-connector.ts` (schemas, batches, tier)                                               |
| telemetry             | a real captured session: 47 452 samples over 11 863 ticks, four karts, Hacienda                                                |
| license               | `open-corpus-catalog.ts` → `supertuxkart`; the instrumentation is GPL-3.0-or-later, the same terms as the program              |
| privacy documentation | this file, and `stkIngestPlan` in `stk-connector.ts`                                                                           |

## Why the shipped replays are not Tier B

SuperTuxKart ships fifty-one `.replay` files. They carry genuine engine state —
kart transforms and controls per tick, with the build version in the header —
and the corpus ingests them (`stk-ghost-replays`). It is tempting to call that
Tier B and stop.

`game-study-tier.ts` says why not, in two fields:
`requiresSignedTelemetry: true` and `requiresAuthorizedBuild: true`. A shipped
replay is plain text with no attestation. Anyone can write one in an editor, and
a study resting on it cannot tell an engine's record of a race from a person's
description of one. **A record of what the engine did is only evidence if
something binds it to the engine.**

So the corpus keeps the shipped replays as what they are — real material, Tier A
— and this directory adds the instrumentation that can produce something better.

## The instrumentation

`stk-instrumentation/` holds the patch and the two files it adds. It is
GPL-3.0-or-later, the same terms as SuperTuxKart, because it is built into it.

Three hooks:

- `World::update()`, **after** the physics step, writes one line per kart per
  physics tick. After, not before, so the sample is the state the tick ended in.
- `LinearWorld::newLap()` writes a lap crossing. Emitted rather than derived
  from the per-tick `lap` field, because a consumer watching that field change
  learns only that the lap ended somewhere between two samples, and the engine
  knows which tick crossed the line.
- `World::updateWorld()`, at the point the race is declared over, writes the
  finish record. **Not** `terminateRace()`, which is the
  leave-the-results-screen path that a headless run never reaches — a session
  recorded by automation would otherwise end with no statement of how many
  samples it should have had, which is precisely the case a reader cannot tell
  from a truncated file.

Three properties are deliberate:

1. **Off unless asked.** Nothing is written unless `STK_STUDY_TELEMETRY` names a
   path. An instrumented build that records by default records people who did
   not ask to be recorded.
2. **It records the simulation, not the machine.** No hostname, no user name, no
   home directory, no input-device identity, no wall-clock time, no file paths.
3. **It is a stream of facts, not a summary.** Nothing is averaged in the
   emitter. A consumer that wants a mean computes one and says so.

## Privacy: what a session contains about a person

**Almost nothing, and that is a design decision rather than a happy accident.**
The emitter was written so that there would be nothing to scrub.

A session carries, per kart per tick: position, orientation, speed, steering,
throttle, brake, nitro, skid state and lap count. All of it is about a vehicle
in a fictional world.

The privacy surface is exactly two fields:

- **`driver`** in the session header — `ai`, `player`, or `unknown`. This is the
  field that decides whether a session is about anybody at all. A race in which
  every kart is `ai` is not personal data, and `stkSessionSummary().allAi`
  answers that question first so a study does not have to treat every session as
  though somebody was driving. An unrecognised value reads as `unknown` rather
  than `ai`: guessing in the safe-looking direction is still guessing.
- **`kart`** — the index, classified `player-identifier` and therefore
  pseudonymized by the default disposition. An index into a race looks harmless
  and is the join key: two sessions from one study that both say "kart 0" invite
  a reader to treat them as the same person, and under per-session consent they
  may not be.

The **input** stream is held at `pseudonymized` even for an all-AI session. The
privacy class is a property of the stream, not of one recording; relaxing it
when the karts happen to be AI would force a silent tightening the first time a
person drove, and `event-schema-registry.ts` refuses that — correctly — as an
incompatible change.

The recorded session in `stk-session-lock.json` is `allAi: true`. Nobody was
driving. It is a race between four AI karts, and there is no data subject.

## What the recorded session grounds

`registered`, and therefore **Tier B** — since 2026-08-15, and the date matters
because for six days before it the same capture was `self-attested` and Tier A.
Nothing about the race changed. The key did.

> the signature establishes **integrity**; the attestation establishes
> **provenance**; a key registry establishes **identity**.

`attestationTrust` has three levels rather than two so that a self-signed build
cannot quietly become an authorized one, and the middle rung is where this
capture sat for as long as the only key in the tree was the demonstration key —
whose private half is a seed constant in `stk-node-adapters.ts`, so anybody with
a clone can sign as it. `PUBLICLY_HELD_KEY_IDS` refuses to let a registry vouch
for such a key at validation and again at resolution.

What moved it:

- an ed25519 key generated with `openssl` **on the build host that compiled the
  binary in the attestation**, its private half mode 0600 outside this tree, and
  never committed, printed or copied into a fixture;
- its public half published in `build-public-keys.ts`, because a signature over
  a committed lock that nobody can check is decoration;
- a registration in `build-key-registry.ts` naming the accountable person, the
  date, the scope (`instrumented-game-build`) and a basis that **states its own
  limit**: the host that signed and the deployment that registered are the same
  machine, so the row says the signer is the build host, not that the build host
  is who it claims to be. A certificate authority or an organisational key store
  would say the second thing. Nothing here claims to.

`stk-session-lock.spec.ts` re-derives all of it on every run — both signatures
against the published key material, the registry's pinned fingerprint against
one computed from that material, and the `trust` block against a fresh
resolution — so an edit to the lock fails rather than ships.

### What Tier B does not buy

Tier B affords nine telemetry kinds. **This capture carries three streams**:
kart motion, kart input and race progress. So `stkClaimIssues` refuses
`ai-telemetry`, `network-telemetry`, `camera-telemetry` and the rest over this
session even now, with a message naming what the session does cover — because a
tier is a claim about what the source affords and the covered streams are a
claim about this particular session, and only the first was ever checked. That
gap was unreachable while every telemetry claim was already being refused for
the tier reason; the promotion is what made it reachable, which is why the guard
landed with it.

## Reproducing the capture

The build is reproducible; the session is not. Two runs of this build on this
track with the same kart count and difficulty finished in different orders,
because the AI is seeded from state the command line does not fix. That is why
the capture class is `recorded-state` and not `deterministic-replay`: declaring
the latter would promise that re-running recovers this session, and it does not.

```bash
# 1. the source the corpus already pins by digest
curl -LO https://github.com/supertuxkart/stk-code/releases/download/1.5/SuperTuxKart-1.5-src.tar.gz
tar -xzf SuperTuxKart-1.5-src.tar.gz && cd SuperTuxKart-1.5-src

# 2. the instrumentation
cp <repo>/libs/yemaya/study-workspace/src/connectors/stk-instrumentation/study_telemetry.{hpp,cpp} src/utils/
patch -p1 < <repo>/libs/yemaya/study-workspace/src/connectors/stk-instrumentation/stk-1.5-study-telemetry.patch

# 3. the build recorded in the attestation
mkdir build && cd build
cmake .. -DSERVER_ONLY=ON -DCMAKE_BUILD_TYPE=Release -DBUILD_RECORDER=OFF
make -j"$(nproc)"

# 4. a session
STK_STUDY_TELEMETRY=session.jsonl ./bin/supertuxkart --no-graphics \
    --profile-laps=2 --track=hacienda --numkarts=4 --difficulty=2 --mode=1

# 5. verify and re-write the lock
YSD_STK_SESSION=session.jsonl \
YSD_STK_TARBALL=../../SuperTuxKart-1.5-src.tar.gz \
YSD_STK_BINARY=./bin/supertuxkart \
YSD_STK_SIGNING_KEY=/root/.config/oshun/ysd-14173-build-signing-key.pem \
YSD_STK_WRITE_LOCK=1 \
  npx vitest run src/connectors/stk-capture.live.spec.ts
```

Omit `YSD_STK_SIGNING_KEY` and the run signs with the demonstration key and
resolves to `self-attested` — which is the correct outcome for a reader
reproducing this on their own machine, since they hold no key this registry
vouches for. It is not a downgrade to be worked around: a lock that said
`registered` on a build nobody registered is the thing all of this exists to
prevent. To reach Tier B on your own capture, generate a key your repository
does not contain, publish its public half, and register it under your own name:

```bash
openssl genpkey -algorithm ed25519 -out ~/build-signing-key.pem && chmod 600 ~/build-signing-key.pem
openssl pkey -in ~/build-signing-key.pem -pubout -outform DER | base64 -w0   # → build-public-keys.ts
openssl pkey -in ~/build-signing-key.pem -pubout -outform DER | sha256sum    # → the pinned fingerprint
```

`SERVER_ONLY=ON` is what makes this runnable with no GPU and no display: it
builds the simulation without graphics or sound, so the physics, the AI and the
race are real and nothing is rendered.
