Adapters: define a versioned installable game-adapter package format #92

Owner package-scope addition — 9 October 2026: Future installable game integrations must be able to bundle versioned experience/presentation declarations as well as bounded exact-game semantic capabilities — primary-slot display names, secondary faces, action descriptors, assets and trusted/composable UI elements. The UI belongs to the game integration as a package, but host shell/navigation/input/focus, universal profile, protected save transactions and permission enforcement remain TrainerOS-owned. 'Packs are separate' below means internal franchise presentation and exact-build semantic adapters are separate composable responsibilities, not that game-specific UI must be scattered in generic shell source or that the installation necessarily requires two unrelated products. See #174–#178 for the installed/in-tree proof before stabilizing external packaging. Do not grant untrusted downloaded QML/native modules arbitrary execution permissions or prematurely pick a dynamic ABI.

Goal

TrainerOS should eventually be able to add, update and remove game integrations without rebuilding the whole operating system.

Define a versioned installable game-adapter package format that can carry the exact-build knowledge and semantic implementation required for one or more supported games.

Do not freeze the format prematurely. Use the output of #89 and the durable research records from #91 as input.

Core distinction

Keep these separate:

• research knowledge — complete technical understanding, evidence and provenance from Research workflow: make game-adapter knowledge persistent, indexed and mandatory during save/adaptation work #91;
• runtime adapter package — the bounded artifact TrainerOS installs and executes/loads.

A research folder may contain much more information than a runtime package needs.

Package responsibilities

An adapter package should be able to describe, where applicable:

• stable adapter/module ID;
• adapter version;
• adapter API/schema version;
• exact supported game/build identities;
• semantic capabilities;
• declarative lookup/reference data;
• save-format/version support;
• semantic readers;
• semantic candidate transforms/writers;
• validation rules;
• optional title-specific semantic extensions;
• links/metadata for tests, provenance and license information.

The exact directory/archive extension is intentionally not prescribed yet.

Separate data from executable logic

Prefer declarative data for things such as:

• hashes/build allowlists;
• IDs and lookup tables;
• bounded rule tables;
• shops/items/locations;
• presentation metadata;
• capability declarations.

Use executable logic only where a declarative model would become misleading or unsafe.

The current Emerald structure — C++ semantic logic + generated JSON + Python build tooling — is useful evidence but not necessarily the final portable format.

Host boundary

An installed adapter must not own TrainerOS or the filesystem.

TrainerOS remains responsible for:

• locating the configured save;
• Trainer/profile ownership;
• proving the game is not writing;
• reading the source bytes;
• protection backups;
• source revision checks;
• atomic replacement;
• readback verification;
• rollback/recovery;
• Bluetooth/network transport;
• UI/navigation;
• process/emulator lifecycle.

Conceptually:

TrainerOS host
   ↓ verified bounded input
Adapter
   ↓ semantic result / candidate bytes
TrainerOS host
   ↓ backup / commit / verify

Do not let a package gain arbitrary host powers merely because it declares a write capability.

Installation / lifecycle

Research and define safe behavior for:

• install;
• update;
• rollback;
• disable;
• remove;
• incompatible adapter API version;
• incompatible TrainerOS version;
• conflicting adapters claiming the same exact build;
• adapter downgrade;
• corrupted/incomplete package;
• package signature/provenance state.

An adapter update must not silently widen write capabilities for an exact build without explicit validated support.

Executable format research

Do not choose one yet without evidence.

Compare practical options such as:

• compiled in-tree/native modules;
• versioned manifest + native code;
• process-isolated helper protocol;
• sandboxed portable module such as WASM;
• declarative schema with optional executable hooks.

Evaluate at minimum:

• ARM64/x86-64 portability;
• crash isolation;
• performance on handheld hardware;
• sandboxing;
• ABI/API versioning;
• testing;
• distribution size;
• community adapter safety;
• reproducibility;
• ability to reuse adapter knowledge outside TrainerOS.

Adapter catalog / UI

The format should allow a future TrainerOS surface such as:

Game Integrations

Pokémon Emerald
Adapter 1.4
Verified build detected
✓ Party
✓ Storage
✓ Pokédex
✓ Center
✓ Shops

[Update] [Details]

Do not build a public catalog/store as part of this issue unless needed to validate the package contract.

Packs are separate

TrainerOS franchise packs from #90 and game adapters are different entities.

A pack decides how a family of games is presented.

An adapter decides what an exact game/build exposes semantically.

One pack may consume many adapters.

One adapter must not control the whole pack/shell.

Relationship to #89 / #91

• Architecture: audit and strengthen game adapter encapsulation #89 defines the architectural adapter boundary.
• Research workflow: make game-adapter knowledge persistent, indexed and mandatory during save/adaptation work #91 preserves the complete game research/evidence.
• this issue defines the distributable runtime artifact.

Do not create a second semantic framework that competes with #42/#89.

Initial proof

Before calling the package format stable, test it against materially different adapters.

At minimum use:

1. Pokémon Emerald;
2. another state-rich game;
3. a structurally different non-RPG game.

Do not freeze adapter-v1 after only Emerald/FireRed.

Acceptance

• one documented installable adapter-package contract exists;
• exact builds and semantic capabilities are versioned and machine-readable;
• package install/update/remove/rollback behavior is defined;
• adapters cannot directly bypass TrainerOS backup/transaction ownership;
• package compatibility fails closed on unknown API/schema versions;
• declarative data and executable logic have a clear boundary;
• franchise packs remain separate from adapters;
• the format is proven against more than one game family/genre before being declared stable;
• the result can evolve toward external/community adapters without requiring arbitrary trusted native code by default.