Eve library

Instrumented open-source game seeds (YSD-14173)

Other

Revision 1

On this page

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.