save-persistence-and-migrations
Builds and checks the save layer - valibot save document, sync expo-sqlite writes, WAL, current/backup slots, load plan, quarantine, migrations with frozen fixtures, node:sqlite tests, boot hydration, kill test. Use when saved data, its format or its loading changes. Not for stores (state-stores).
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- save-persistence-and-migrations
- description
- Builds and checks the save layer - valibot save document, sync expo-sqlite writes, WAL, current/backup slots, load plan, quarantine, migrations with frozen fixtures, node:sqlite tests, boot hydration, kill test. Use when saved data, its format or its loading changes. Not for stores (state-stores).
02 资源文件 175
- 资产文件assets/shared.json1.2 KB
- 脚本examples/save-v2/packages/shell/src/services/save/fixtures/fixture-checksums.ts402 B
- 脚本examples/save-v2/packages/shell/src/services/save/fixtures/save-fixtures.test.ts2.0 KB
- 参考文档examples/save-v2/packages/shell/src/services/save/fixtures/save-v2.full.json2.7 KB
- 参考文档examples/save-v2/packages/shell/src/services/save/fixtures/save-v2.minimal.json1.4 KB
- 脚本examples/save-v2/packages/shell/src/services/save/migrations/save-migrations.ts1.8 KB
- 脚本examples/save-v2/packages/shell/src/services/save/migrations/v1-to-v2.test.ts1.9 KB
- 脚本examples/save-v2/packages/shell/src/services/save/migrations/v1-to-v2.ts693 B
- 脚本examples/save-v2/packages/shell/src/services/save/schema/default-save-doc.ts1.8 KB
- 脚本examples/save-v2/packages/shell/src/services/save/schema/save-doc-v2.ts595 B
- 脚本examples/save-v2/packages/shell/src/services/save/schema/save-doc.ts822 B
- 脚本examples/save-v2/packages/shell/src/services/save/schema/save-sections-v2.ts600 B
- 参考文档references/boot-and-kill-test.md18.2 KB
- 参考文档references/migrations-and-fixtures.md8.4 KB
- 参考文档references/save-document.md11.3 KB
- 参考文档references/write-path.md21.7 KB
- 脚本scripts/check-lib.mjs44.4 KB
- 脚本scripts/check-save-layer.mjs21.3 KB
- 脚本scripts/inspect-save.mjs7.9 KB
- 脚本scripts/kill-test.mjs19.9 KB
- 脚本scripts/lib/android-device.mjs10.2 KB
- 脚本scripts/lib/android-emu.mjs3.4 KB
- 脚本scripts/lib/app-modules.mjs3.1 KB
- 脚本scripts/lib/fixture-tree.mjs1.4 KB
- 脚本scripts/lib/kill-plan.mjs2.1 KB
- 脚本scripts/lib/save-db.mjs6.1 KB
- 脚本scripts/selftest.mjs7.7 KB
- 脚本templates/packages/shell/src/app/hydrate-save.test.ts3.2 KB
- 脚本templates/packages/shell/src/app/hydrate-save.ts2.5 KB
- 脚本templates/packages/shell/src/app/use-checkpoint-on-background.test.ts1.9 KB
- 脚本templates/packages/shell/src/app/use-checkpoint-on-background.ts679 B
- 脚本templates/packages/shell/src/services/clock/clock-port.ts976 B
- 脚本templates/packages/shell/src/services/clock/fake-clock.test.ts1.8 KB
- 脚本templates/packages/shell/src/services/clock/fake-clock.ts1.6 KB
- 脚本templates/packages/shell/src/services/clock/system-clock-adapter.test.ts1.6 KB
- 脚本templates/packages/shell/src/services/clock/system-clock-adapter.ts1.1 KB
- 脚本templates/packages/shell/src/services/error-log/error-log-port.ts767 B
- 脚本templates/packages/shell/src/services/error-log/fake-error-log.test.ts794 B
- 脚本templates/packages/shell/src/services/error-log/fake-error-log.ts1.2 KB
- 脚本templates/packages/shell/src/services/error-log/sqlite-error-log-adapter.ts2.8 KB
- 脚本templates/packages/shell/src/services/save/checksum.test.ts883 B
- 脚本templates/packages/shell/src/services/save/checksum.ts416 B
- 脚本templates/packages/shell/src/services/save/expo-sqlite-sql-driver.ts875 B
- 脚本templates/packages/shell/src/services/save/fake-save-store.test.ts1.5 KB
- 脚本templates/packages/shell/src/services/save/fake-save-store.ts1.2 KB
- 脚本templates/packages/shell/src/services/save/fixtures/fixture-checksums.ts339 B
- 脚本templates/packages/shell/src/services/save/fixtures/save-fixtures.test.ts1.8 KB
- 参考文档templates/packages/shell/src/services/save/fixtures/save-v1.full.json2.7 KB
- 参考文档templates/packages/shell/src/services/save/fixtures/save-v1.minimal.json1.4 KB
- 脚本templates/packages/shell/src/services/save/load-plan.test.ts5.6 KB
- 脚本templates/packages/shell/src/services/save/load-plan.ts4.3 KB
- 脚本templates/packages/shell/src/services/save/migrations/save-migrations.test.ts1.6 KB
- 脚本templates/packages/shell/src/services/save/migrations/save-migrations.ts1.8 KB
- 脚本templates/packages/shell/src/services/save/peek-current-save.ts947 B
- 脚本templates/packages/shell/src/services/save/reset-progress.test.ts2.4 KB
- 脚本templates/packages/shell/src/services/save/reset-progress.ts874 B
- 脚本templates/packages/shell/src/services/save/save-codec.test.ts3.0 KB
- 脚本templates/packages/shell/src/services/save/save-codec.ts2.5 KB
- 脚本templates/packages/shell/src/services/save/save-db-schema.ts2.4 KB
- 脚本templates/packages/shell/src/services/save/save-service.test.ts13.7 KB
- 脚本templates/packages/shell/src/services/save/save-service.ts6.7 KB
- 脚本templates/packages/shell/src/services/save/save-store.ts1.4 KB
- 脚本templates/packages/shell/src/services/save/schema/default-save-doc.test.ts4.7 KB
- 脚本templates/packages/shell/src/services/save/schema/default-save-doc.ts1.7 KB
- 脚本templates/packages/shell/src/services/save/schema/save-doc-v1.ts964 B
- 脚本templates/packages/shell/src/services/save/schema/save-doc.ts822 B
- 脚本templates/packages/shell/src/services/save/schema/save-primitives.ts1.1 KB
- 脚本templates/packages/shell/src/services/save/schema/save-run-v1.ts1.2 KB
- 脚本templates/packages/shell/src/services/save/schema/save-sections-v1.ts3.0 KB
- 脚本templates/packages/shell/src/services/save/sql-driver.ts1.0 KB
- 脚本templates/packages/shell/src/services/save/sqlite-save-store.test.ts2.2 KB
- 脚本templates/packages/shell/src/services/save/sqlite-save-store.ts3.0 KB
- 脚本templates/test/integration/save/node-sqlite-sql-driver.ts1002 B
- 脚本templates/test/integration/save/sqlite-error-log-adapter.test.ts4.5 KB
- 脚本templates/test/integration/save/sqlite-save-store.test.ts5.9 KB
- 参考文档tests/fixtures/check-save-layer/bad-boot-file-missing/EXPECT.txt89 B
- 参考文档tests/fixtures/check-save-layer/bad-boot-file-missing/REMOVE.txt39 B
- 参考文档tests/fixtures/check-save-layer/bad-boot-not-yet-due/EXPECT.txt372 B
- 脚本tests/fixtures/check-save-layer/bad-boot-not-yet-due/packages/shell/src/services/save/save-db-schema.ts2.4 KB
- 参考文档tests/fixtures/check-save-layer/bad-boot-not-yet-due/REMOVE.txt236 B
- 参考文档tests/fixtures/check-save-layer/bad-checkpoint-not-called/EXPECT.txt95 B
- 其他tests/fixtures/check-save-layer/bad-checkpoint-not-called/packages/shell/src/app/shell-app.tsx694 B
- 参考文档tests/fixtures/check-save-layer/bad-fixture-edited/EXPECT.txt43 B
- 参考文档tests/fixtures/check-save-layer/bad-fixture-edited/packages/shell/src/services/save/fixtures/save-v1.full.json2.7 KB
- 参考文档tests/fixtures/check-save-layer/bad-loose-schema/EXPECT.txt50 B
- 脚本tests/fixtures/check-save-layer/bad-loose-schema/packages/shell/src/services/save/schema/save-sections-v1.ts3.0 KB
- 参考文档tests/fixtures/check-save-layer/bad-missing-migration/EXPECT.txt87 B
- 脚本tests/fixtures/check-save-layer/bad-missing-migration/packages/shell/src/services/save/migrations/save-migrations.ts1.3 KB
- 脚本tests/fixtures/check-save-layer/bad-missing-migration/packages/shell/src/services/save/schema/save-doc-v2.ts964 B
- 脚本tests/fixtures/check-save-layer/bad-missing-migration/packages/shell/src/services/save/schema/save-doc.ts822 B
- 参考文档tests/fixtures/check-save-layer/bad-newer-db-throws/EXPECT.txt79 B
- 脚本tests/fixtures/check-save-layer/bad-newer-db-throws/packages/shell/src/services/save/sqlite-save-store.ts2.9 KB
- 参考文档tests/fixtures/check-save-layer/bad-no-wal/EXPECT.txt39 B
- 脚本tests/fixtures/check-save-layer/bad-no-wal/packages/shell/src/services/save/save-db-schema.ts2.4 KB
- 参考文档tests/fixtures/check-save-layer/bad-peek-writes/EXPECT.txt45 B
- 脚本tests/fixtures/check-save-layer/bad-peek-writes/packages/shell/src/services/save/peek-current-save.ts888 B
- 参考文档tests/fixtures/check-save-layer/bad-premium-reset/EXPECT.txt51 B
- 脚本tests/fixtures/check-save-layer/bad-premium-reset/packages/shell/src/services/save/reset-progress.ts902 B
- 参考文档tests/fixtures/check-save-layer/bad-second-persistence/EXPECT.txt63 B
- 脚本tests/fixtures/check-save-layer/bad-second-persistence/packages/shell/src/stores/cache.ts106 B
- 参考文档tests/fixtures/check-save-layer/bad-sqlite-in-screen/EXPECT.txt36 B
- 脚本tests/fixtures/check-save-layer/bad-sqlite-in-screen/packages/shell/src/screens/home/use-best.ts174 B
- 参考文档tests/fixtures/check-save-layer/bad-write-no-transaction/EXPECT.txt91 B
- 脚本tests/fixtures/check-save-layer/bad-write-no-transaction/packages/shell/src/services/save/sqlite-save-store.ts3.0 KB
- 参考文档tests/fixtures/check-save-layer/bad-write-unvalidated/EXPECT.txt75 B
- 脚本tests/fixtures/check-save-layer/bad-write-unvalidated/packages/shell/src/services/save/save-service.ts3.2 KB
- 参考文档tests/fixtures/check-save-layer/good/README.md438 B
- 参考文档tests/fixtures/inspect-save/bad-android-adb-checksum/args.txt145 B
- 参考文档tests/fixtures/inspect-save/bad-android-adb-checksum/EXPECT.txt29 B
- 其他tests/fixtures/inspect-save/bad-android-adb-checksum/save.sql4.2 KB
- 参考文档tests/fixtures/inspect-save/bad-android-adb-checksum/scenario.json156 B
- 参考文档tests/fixtures/inspect-save/bad-checksum/EXPECT.txt29 B
- 其他tests/fixtures/inspect-save/bad-checksum/save.sql4.2 KB
- 参考文档tests/fixtures/inspect-save/bad-missing-backup/EXPECT.txt42 B
- 其他tests/fixtures/inspect-save/bad-missing-backup/save.sql2.4 KB
- 参考文档tests/fixtures/inspect-save/bad-not-wal/EXPECT.txt47 B
- 其他tests/fixtures/inspect-save/bad-not-wal/save.sql4.2 KB
- 参考文档tests/fixtures/inspect-save/bad-other-game/EXPECT.txt56 B
- 其他tests/fixtures/inspect-save/bad-other-game/save.sql4.2 KB
- 参考文档tests/fixtures/inspect-save/bad-quarantine/EXPECT.txt44 B
- 其他tests/fixtures/inspect-save/bad-quarantine/save.sql4.3 KB
- 参考文档tests/fixtures/inspect-save/bad-version-mismatch/EXPECT.txt81 B
- 其他tests/fixtures/inspect-save/bad-version-mismatch/save.sql4.2 KB
- 参考文档tests/fixtures/inspect-save/error-android-adb-no-serial/args.txt106 B
- 参考文档tests/fixtures/inspect-save/error-android-adb-no-serial/EXPECT.txt69 B
- 其他tests/fixtures/inspect-save/good/save.sql4.2 KB
- 参考文档tests/fixtures/inspect-save/pass-android-adb/args.txt145 B
- 参考文档tests/fixtures/inspect-save/pass-android-adb/EXPECT.txt168 B
- 其他tests/fixtures/inspect-save/pass-android-adb/save.sql4.2 KB
- 参考文档tests/fixtures/inspect-save/pass-android-adb/scenario.json156 B
- 参考文档tests/fixtures/kill-test/bad-android-damaged-save/args.txt140 B
- 参考文档tests/fixtures/kill-test/bad-android-damaged-save/EXPECT.txt29 B
- 其他tests/fixtures/kill-test/bad-android-damaged-save/save.sql4.2 KB
- 参考文档tests/fixtures/kill-test/bad-android-damaged-save/scenario.json156 B
- 参考文档tests/fixtures/kill-test/empty-sdk/README.txt106 B
- 参考文档tests/fixtures/kill-test/error-android-dry-run-create/args.txt134 B
- 参考文档tests/fixtures/kill-test/error-android-dry-run-create/EXPECT.txt556 B
- 参考文档tests/fixtures/kill-test/error-android-dry-run-serial/args.txt149 B
- 参考文档tests/fixtures/kill-test/error-android-dry-run-serial/EXPECT.txt161 B
- 其他tests/fixtures/kill-test/error-android-image-missing/app-release.apk89 B
- 参考文档tests/fixtures/kill-test/error-android-image-missing/args.txt125 B
- 参考文档tests/fixtures/kill-test/error-android-image-missing/EXPECT.txt66 B
- 参考文档tests/fixtures/kill-test/error-android-no-device/args.txt75 B
- 参考文档tests/fixtures/kill-test/error-android-no-device/EXPECT.txt58 B
- 参考文档tests/fixtures/kill-test/error-android-not-apk/args.txt114 B
- 参考文档tests/fixtures/kill-test/error-android-not-apk/EXPECT.txt22 B
- 其他tests/fixtures/kill-test/error-android-root-refused/app-release.apk89 B
- 参考文档tests/fixtures/kill-test/error-android-root-refused/args.txt148 B
- 参考文档tests/fixtures/kill-test/error-android-root-refused/EXPECT.txt141 B
- 其他tests/fixtures/kill-test/error-android-root-refused/save.sql4.2 KB
- 参考文档tests/fixtures/kill-test/error-android-root-refused/scenario.json161 B
- 参考文档tests/fixtures/kill-test/error-android-udid/args.txt86 B
- 参考文档tests/fixtures/kill-test/error-android-udid/EXPECT.txt18 B
- 参考文档tests/fixtures/kill-test/error-ios-dry-run/args.txt95 B
- 参考文档tests/fixtures/kill-test/error-ios-dry-run/EXPECT.txt179 B
- 参考文档tests/fixtures/kill-test/error-platform-unknown/args.txt75 B
- 参考文档tests/fixtures/kill-test/error-platform-unknown/EXPECT.txt34 B
- 其他tests/fixtures/kill-test/fake-sdk/cmdline-tools/latest/bin/avdmanager799 B
- 其他tests/fixtures/kill-test/fake-sdk/emulator/emulator750 B
- 其他tests/fixtures/kill-test/fake-sdk/platform-tools/adb3.0 KB
- 其他tests/fixtures/kill-test/fake-sdk/system-images/android-35/google_apis/arm64-v8a/source.properties95 B
- 参考文档tests/fixtures/kill-test/good/args.txt140 B
- 参考文档tests/fixtures/kill-test/good/EXPECT.txt126 B
- 其他tests/fixtures/kill-test/good/save.sql4.2 KB
- 参考文档tests/fixtures/kill-test/good/scenario.json185 B
- 其他tests/fixtures/kill-test/pass-android-create/app-release.apk89 B
- 参考文档tests/fixtures/kill-test/pass-android-create/args.txt148 B
- 参考文档tests/fixtures/kill-test/pass-android-create/EXPECT.txt542 B
- 其他tests/fixtures/kill-test/pass-android-create/save.sql4.2 KB
- 参考文档tests/fixtures/kill-test/pass-android-create/scenario.json156 B
- 参考文档tests/fixtures/kill-test/pass-android-serial-calibrated/args.txt126 B
- 参考文档tests/fixtures/kill-test/pass-android-serial-calibrated/EXPECT.txt131 B
- 其他tests/fixtures/kill-test/pass-android-serial-calibrated/save.sql4.2 KB
- 参考文档tests/fixtures/kill-test/pass-android-serial-calibrated/scenario.json185 B
- 脚本tests/fixtures/support/packages/shell/src/app/start-shell.ts222 B
03 SKILL.md 正文
Save persistence and migrations
Everything the player owns is one versioned JSON document, validated on every load and before every write, committed to SQLite in one synchronous transaction, kept twice (current and backup), and upgraded only by tested migrations; scripts prove the code, the fixtures and the file on a simulator.
Rules that must hold
- One save document, one writer. Everything persisted lives in
save_slots('current'|'backup')ofsave.dband is written only bySaveService.update(recipe, { refreshBackup }); no AsyncStorage, MMKV, SecureStore or Zustand persist, and SQLite is imported only insideservices/saveandservices/error-log. One document means one version number and pure migrations. - Validate with the strict valibot schema on every load and before every write. An invalid document is never written: test builds throw, store builds log and skip. N10: losing a player's progress is the worst bug the Shell can have, so a bug must fail loudly in tests and never reach disk.
- Open SQLite with
journal_mode = WALandsynchronous = FULL, write through the synchronous API in one transaction, and refreshbackuponly at startup, at a run end, after a reset and after a Premium change. A committed transaction survives a kill or power loss; per-move writes touching onlycurrentcan never spoil the last good backup. - Never lose the whole save, and never crash-loop on it. A damaged
currentfalls back tobackup; only when both are damaged does the app start fresh; bad rows are quarantined, never deleted; a run the game cannot parse is dropped alone; a save from a newer app (a newer document or newersave.dbtables) is played in memory and never written, and opening it never throws. - Change the format only through a new schema version, one pure frozen
vK-to-vK+1step, and new frozen fixtures with checksums. Never edit a shippedsave-doc-vN.ts, section file, fixture or checksum, and commit the change with aGate-Change:trailer. Old saves on real phones must keep upgrading exactly as tested. - Premium never turns off without an explicit revocation date, and never in a reset.
keepPremiumUnlessRevokedguards every writer; "Reset all progress" keeps settings, language, first-run flags, ads and Premium. - At boot, write nothing before the direction check; the language peek is read-only; hydrate synchronously before the first render. Module code runs again after a direction reload, so an early write would happen twice.
- Checkpoint the WAL (
wal_checkpoint(TRUNCATE)) when the app goes to the background, and keep the save in the device backup (D5, spec 8.6). iOS backs upDocuments/SQLite/by itself; on Android, Auto Backup keepsallowBackup: truewith backup rules (backup_rules.xmlanddata_extraction_rules.xml) that include exactlySQLite/save.db,-waland-shmof the files domain. The backup then copies one self-containedsave.db, and progress follows the player to a new phone with no network request of ours. - Test the real SQL on
node:sqlitethroughSqlDriver, and finish every change to the write path or boot with the simulator kill test. Jest proves the SQL; only a real kill proves the app.
Workflow
- Read references/save-document.md (the v1 shape, sections, resets, defaults) and references/write-path.md (tables, drivers, codec, load plan, SaveService, backup moments, checker rules).
- New Shell, in two parts that follow the Shell build order. At Shell step 4 copy everything under
templates/except the two boot files:packages/shell/src/services/save/(drivers, stores, codec, load plan,SaveService, resets, the startup peek, schema v1, migrations, fixtures and their tests),services/clock/andservices/error-log/(ports, adapters, fakes and tests) andtest/integration/save/(thenode:sqlitedriver and the SQL tests). Installnpm install -E valibot@1.5.0 -w packages/shell(a Shell-only dependency) andnpx expo install expo-sqliteinside everyapps/<game>(it writes~57.0.3), plus"expo-sqlite": "*"inpackages/shell/package.jsonpeerDependencies(the dependency-management rules). The clock and error-log files are identical copies in every skill that ships them (an olderclock-port.tswithoutmsUntilNextLocalDayis replaced). They need onlygame-kit/src/dates/date-key.tsfrom earlier steps (Shell step 2, daily-and-statistics); none of the step-4 templates importsapp/test-only.tsor the test-only pair, so step 4 compiles and its tests pass without them.app/test-only.tsarrives at Shell step 6 (architecture-and-boundaries, with the test-only pair, which holds onlyTEST_BUILD_SENTINELuntil step 7), and the first save file that imports it ishydrate-save.ts, so it is needed by Shell step 7. At Shell step 7 (the boot, withstart-shell.ts, together with the composition root, because each imports step-7 code or is imported by it) copypackages/shell/src/app/hydrate-save.tsanduse-checkpoint-on-background.tswith their tests: they need@react-navigation/native, RNTL, state-stores'testing/create-test-save.tsand the test-only pair's members, which arrive at steps 6 and 7. Untilpackages/shell/src/app/start-shell.tsexists,check-save-layer.mjsprintsSKIPlines for them (a pass); from then on a missing one is amissing-fileproblem. The composition root that callshydrateSaveand mountsuseCheckpointOnBackground(save)once is game-host-integration's template (app/create-shell-parts.ts,app/shell-app.tsx); this skill ships nocreate-shell-app.tsx. - A service or store needs to save something: add it to the document (step 4 if the shape changes), then call
save.update((doc) => ({ ...doc, section }), { refreshBackup })withrefreshBackup: trueonly for a run end, reset or Premium change. Never touch SQL. - The stored shape changes: read references/migrations-and-fixtures.md and follow "Adding version N+1" in order, imitating
examples/save-v2/(schema v2, step, step test with a fast-check property, default doc, fixtures, checksums). A new version is permanent for players once shipped: name it in the report to the owner. - Boot or kill-test work: read references/boot-and-kill-test.md (boot order, peek,
hydrateSave,resumeState, SQL tests, kill test). - Run the tests:
npx jest packages/shell/src/services/save packages/shell/src/app/hydrate-save.test.ts packages/shell/src/app/use-checkpoint-on-background.test.ts test/integration/save --ci --selectProjects unit --coverage --collectCoverageFrom='packages/shell/src/services/save/**/*.ts' --coverageThreshold='{}'(paths first; onlynpm run test:coveragejudges the thresholds) andnpx tsc -p packages/shell --noEmit(plusnpx tsc -p .for the roottest/program). - When the write path, the schema or the boot changed and a Release test-variant simulator build exists:
node ${CLAUDE_SKILL_DIR}/scripts/kill-test.mjs --create --app <App.app> --bundle-id <id> --game-id <game-id> --repo .must printRESULT: PASS; inspect any save.db withnode ${CLAUDE_SKILL_DIR}/scripts/inspect-save.mjs. On Android, with a Release test-variant APK:node ${CLAUDE_SKILL_DIR}/scripts/kill-test.mjs --platform android --create --app <app-release.apk> --bundle-id <package> --game-id <game-id> --repo .(agoogle_apisemulator;--serial <serial>for a running dedicated one), andinspect-save.mjs --platform android --serial <serial> --bundle-id <package>reads the app'sfiles/SQLite/over adb. Without a build, say in the report that the kill test is still owed. - Run
node ${CLAUDE_SKILL_DIR}/scripts/check-save-layer.mjs .from the repo root; fix everyFAILline and rerun until it printsRESULT: PASS.
Definition of done
- [ ] Only
SaveServicewrites save rows; SQLite appears only inservices/save,services/error-log,test/and tooling. - [ ] Every save schema uses
v.strictObject;LATEST_SAVE_VERSIONandLATEST_SAVE_SCHEMAname the highestsave-doc-vN.ts. - [ ] Every version above 1 has its step, its registration, its step test and both frozen fixtures with checksums; no shipped file was edited.
- [ ]
load-plan,save-service,reset-progress,save-migrations,save-fixtures,hydrate-save,use-checkpoint-on-backgroundandtest/integration/savetests pass;tscis clean. The device-only files (expo-sqlite-sql-driver.ts,peek-current-save.ts) carry their// device-only:line. - [ ] Resets keep settings, first-run flags, ads and Premium, and refresh the backup.
- [ ] A
save.dbwhoseuser_versionis newer thanDB_STRUCTURE_VERSIONopens read-only with thenewer-versionoutcome; the integration tests prove nothing is written, not even an error log row. - [ ] After a write-path, schema or boot change: the kill test printed
RESULT: PASS, or the report says it is owed. - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-save-layer.mjs .printsRESULT: PASS
Anti-patterns
- "Just add a field" to
save-sections-v1.tsafter v1 shipped. Every existing save then fails validation and falls back or resets; make v2 with a migration. - Editing a fixture or checksum to make a test pass. The fixture is what old phones hold; fix the code, or add a new version.
- A migration that imports
createDefaultSaveDocor readsDate. Tomorrow's defaults would change yesterday's upgrade; write literal values. - Writing the backup on every move. One bad write sequence would then overwrite the last good copy; refresh it only at the four moments.
- Deleting a damaged row "to clean up". Quarantine it: it is the only evidence, and the debug export needs it.
await-ing an async SQLite call before the first render, or opening the database at module load. Use the synchronous API in the composition root (createDeviceAdapters()opens it once, after the direction check).- A second store (AsyncStorage, MMKV) "for a small flag". Add a field to the document instead; a side store has no version and no backup.
- Turning Premium off because a restore returned nothing. Only an explicit revocation date may turn it off.
throwincreateSqliteSaveStorefor a neweruser_version. Every launch after a downgrade then crashes before the first frame (a crash loop the player cannot escape); return the read-only store and let the load plan show "please update".- Opening the app's
save.dbin place from the host. Copy it first (inspect-savedoes); opening it can checkpoint or lock the live file.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/save-document.md | Product rules, valibot choice, sections and resets, every v1 schema, defaults, notes on the shape | Workflow step 1 |
| references/write-path.md | Tables and pragmas, drivers, SaveStore, codec, load plan and outcomes, SaveService, backup moments, resets, checkpoint, error log, checker rules | Workflow steps 1 and 3 |
| references/migrations-and-fixtures.md | Migration rules, runner, adding version N+1 step by step, writing a step, frozen fixtures, tests per version | Workflow step 4 |
| references/boot-and-kill-test.md | Boot sequence, peek, hydrateSave, composition root, clock adapter, SQL tests, kill test, inspect-save, verified facts | Workflow steps 5 and 7 |
templates/packages/shell/src/services/save/ |
Driver port and drivers, SaveStore (SQLite and fake), SQL, checksum, codec, load plan, SaveService, resets, peek, schema v1, migrations, fixtures, and their tests | Workflow step 2 |
templates/packages/shell/src/services/clock/ |
clock-port.ts, system-clock-adapter.ts (the one file that reads Date), fake-clock.ts and their tests, synced from the library (do not edit here) |
Workflow step 2 |
templates/packages/shell/src/services/error-log/ |
sqlite-error-log-adapter.ts (newest 200 rows; clearErrorLog(driver) empties the table for a parity capture, never a newer app's save.db), plus error-log-port.ts, fake-error-log.ts and its test synced from the library |
Workflow step 2 |
templates/packages/shell/src/app/ |
hydrate-save.ts (hydrateSave over an injected SaveStore, resumeState), use-checkpoint-on-background.ts, and their tests |
Workflow steps 2 and 5 |
templates/test/integration/save/ |
node:sqlite driver and the SQL integration tests |
Workflow steps 2 and 6 |
examples/save-v2/ |
A complete v1-to-v2 change (schema, step, step test, defaults, fixtures, checksums) | Workflow step 4 |
scripts/check-save-layer.mjs |
Static checker for the save layer, schemas, migration chain, fixture checksums and the newer-save.db boot path |
Workflow step 8, and at the end |
scripts/inspect-save.mjs |
Health check of a save.db, a .sql dump, the simulator app's file, or with --platform android the emulator app's files/SQLite/ pulled over adb |
Workflow step 7, and when a save looks wrong |
scripts/kill-test.mjs |
Kill test on an iOS simulator, or with --platform android on an emulator over adb (e07-android-kill-test on the google_apis image, adb root, kill -9, pull files/SQLite/): a calibration launch times the first save write, then launch and SIGKILL at growing delays over 1.5 x that, inspect |
Workflow step 7 |
scripts/lib/android-device.mjs |
The adb, emulator and avdmanager side of both scripts on Android: SDK tool paths, boot wait, root check, kill round, pull, teardown (proven by the self-test) | Never by hand |
scripts/lib/android-emu.mjs |
The pinned system image, the SDK lookup, the adb devices list, the free console port (5554 to 5682) and the sleep (synced from the library, the same file toybox-visual-parity uses; do not edit here) |
Never by hand |
scripts/lib/save-db.mjs |
Stages a copy of save.db and judges its health (used by both scripts above) | Never by hand |
scripts/lib/kill-plan.mjs |
The kill test's timing: the calibrated step and the first-write test (proven by the self-test) | Never by hand |
scripts/lib/app-modules.mjs |
Imports the app's TypeScript modules for inspect-save --deep |
Never by hand |
scripts/lib/fixture-tree.mjs |
Builds the self-test trees (templates plus one planted bug) | Never by hand |
scripts/selftest.mjs |
Proves check-save-layer and inspect-save pass good input and catch every planted bug, the kill plan and the Android helpers, and the kill test's iOS and Android plans (dry runs) and Android runs against the fake SDK | After changing a checker or a template |
scripts/check-lib.mjs |
Shared script helper, synced from the library (do not edit here) | Never by hand |
assets/shared.json |
Declares the shared files this skill copies in (check-lib, the clock and error log files) | When adding a shared file |
tests/fixtures/ |
Planted-bug overlays for check-save-layer (with support/, the start-shell.ts stand-in that makes the boot files due) SQL dumps for inspect-save (Android cases read a fake adb), and the kill-test cases with kill-test/fake-sdk/ (fake adb, emulator, avdmanager that never reach a device) |
When adding a checker rule |
Related skills
state-stores- the stores that callsave.updateand publish after it.daily-and-statistics- the daily and stats sections and the run-end recipe.settings-and-preferences- the settings section, its defaults and rows.premium-purchase- the Premium section andpersistPremium.rtl-and-direction- the direction check and the key-value guard that run before hydration.ios-simulator-build- the Release test-variant build the kill test installs.e2e-maestro- the mid-level kill flow.golden-tests- the Gate-Change trailer policy for frozen files.
04 同仓库更多 Skills
unit-and-component-tests
Sets up Jest and writes Pocket Arcade test code - three projects, RNTL 14 async via renderWithShell, root SDK mocks, fakes, fast-check, coverage, Stryker. Use when a test needs the Shell wrapper, a mock or a fake, or Jest fails. Not for the red-green loop (tdd-workflow) or goldens (golden-tests).
typescript-and-lint-rules
Enforces Pocket Arcade's strict TypeScript 6 tsconfigs, ESLint 9 flat config, Prettier and size limits. Use when writing or splitting .ts/.tsx or fixing a tsc or lint error. Not for gate wiring (quality-gates), names (naming-conventions) or import zones (architecture-and-boundaries).
demo-skill
Builds a demo. Use when testing the pitfall checker.
demo-skill
Builds a demo. Use when testing the pitfall checker.
troubleshooting-playbook
Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).
toybox-visual-parity
Proves a built Pocket Arcade screen matches its Toybox design screenshot (light/dark, en/fa) and drives the fixes: capture, element gates, sheets, sign-off. Use when any screen is built or changed, or for visual parity, design match, screenshot compare. Not for building screens (toybox-screens).