Iron Curtain — Design Documentation

Resilience Philosophy: Hackable but Unbreakable

IC gives users power over their data — open .db files, shipped .sql queries (D034), full CLI access, external tool compatibility. This is the “hacky in the good way” philosophy: transparent, moddable, empowering. But power without safety is dangerous. The design must ensure that no user action can permanently break the game, and that recovery from mistakes is always possible.

Principle: Enable everything. Protect against everything. If a user destroys something, the path back is obvious and fast.

What can a user break, and how do they recover?

Automatic protection layers (always-on, no user action required):

1. Auto-snapshot (daily): 3-day rotating critical backup (keys/, profile.db, communities/*.db, achievements.db, config.toml). ~5 MB. Runs silently during asset loading.
2. Database integrity check on startup: PRAGMA integrity_check on all databases. Corrupt files renamed, fresh databases created, user notified with restore offer.
3. Schema version validation: Forward-only migrations. Engine refuses to downgrade a database, preventing silent data loss from running an older version.
4. SCR tamper detection: Ed25519 signatures on all credential records. Tampered records automatically rejected and replaced on next community sync.
5. Fossilize-pattern writes: All database and save file writes use the append-safe pattern (temp file → fsync → atomic rename). A crash mid-write never corrupts the previous valid state.
6. Cloud sync (opt-in): Critical data uploaded on game exit and after matches. Restores automatically on new machine.

Beyond file deletion — other ways users can break things, and how the engine recovers:

CLI recovery commands:

ic data health                    # Check integrity of all databases + critical files
ic data repair                    # Run integrity_check + repair on all databases
ic data repair gameplay           # Repair a specific database
ic data reset gameplay            # Delete and recreate gameplay.db (fresh, empty)
ic data reset config              # Reset config.toml to defaults
ic data reset --all               # Reset everything except identity key (nuclear option)
ic asset validate                 # Check all imported assets for corruption
ic mod repair <package>           # Re-download and re-verify a corrupt mod package
ic server validate-config <path>  # Validate server config ranges before launch

Design principle: The game should never fail to launch. If any data file is missing, corrupt, or incompatible, the engine creates fresh defaults and continues. The only file whose loss requires user action is keys/identity.key, and that’s recoverable via the mnemonic phrase. Everything else is either re-downloadable, re-syncable, or recreatable with defaults.

The broader principle: hackable but unbreakable. IC gives users open .db files, shipped .sql queries (D034), full CLI access, hot-reload, console commands, moddable YAML/Lua/WASM, and direct filesystem access. Every exposed surface is designed so that: (1) invalid input is clamped, rejected, or replaced with defaults — never crashes the engine, (2) corrupted state is detected on startup and auto-recovered, (3) the path from “I broke something” to “everything works again” is at most one command or one click.

Alternatives Considered

• Proprietary backup format with encryption (rejected — contradicts “standard formats only” principle; a ZIP file can be encrypted separately with standard tools if the player wants encryption)
• IC-hosted cloud backup service (rejected — creates infrastructure liability, ongoing cost, and makes player data dependent on IC’s servers surviving; violates local-first philosophy)
• Database-level replication (rejected — over-engineered for the use case; SQLite VACUUM INTO is simpler, safer, and produces a self-contained file)
• Steam Cloud as primary backup (rejected — platform-specific, limited quota, opaque sync behavior; IC supports it as an option, not a requirement)
• Incremental backup (deferred — full backup via VACUUM INTO is sufficient for player-scale data; incremental adds complexity with minimal benefit unless someone has 50+ GB of replays)
• Forced backup before first ranked match (rejected — punishes players to solve a problem most won’t have; auto-snapshots protect critical data without friction)
• Scary “BACK UP YOUR KEY OR ELSE” warnings (rejected — fear-based UX is hostile; the recovery phrase provides a genuine safety net, making fear unnecessary; factual presentation of options replaces warnings)
• 12-word mnemonic phrase (rejected — 12 words = 128 bits of entropy; sufficient for most uses but 24 words = 256 bits matches Ed25519’s full key strength; the BIP-39 ecosystem standardized on 24 words for high-security applications; the marginal cost of 12 extra words is negligible for a one-time operation)
• Custom IC wordlist (rejected — BIP-39’s English wordlist is battle-tested, curated for unambiguous reading, and familiar to millions of cryptocurrency users; a custom list would need the same curation effort with no benefit)

Integration with Existing Decisions

• D010 (Snapshottable Sim): Save files are sim snapshots — the backup system treats them as opaque binary files. No special handling needed beyond file copy.
• D020 (Mod SDK & CLI): The ic backup and ic profile export commands join the ic CLI family alongside ic mod, ic replay, ic campaign.
• D030 (Workshop): Post-milestone nudge toasts use the same toast system as Workshop cleanup prompts — consistent notification UX.
• D032 (UI Themes): First-launch identity creation integrates as the final step after theme selection. The Data & Backup panel is theme-aware.
• D034 (SQLite): SQLite is the backbone of player data storage. VACUUM INTO is the safe backup primitive — it handles WAL mode correctly and produces a compacted single-file copy.
• D052 (Community Servers & SCR): SCRs are the portable reputation unit. The backup system preserves them; the export system includes them. Because SCRs are cryptographically signed, they’re self-verifying on import — no server round-trip needed. Restore progress screen visibly verifies SCRs.
• D053 (Player Profile): The profile export is D053’s data portability implementation. All locally-authoritative profile fields export to JSON; all SCR-backed fields export with full credential data.
• D036 (Achievements): Achievement proofs are SCRs stored in achievements.db. Backup preserves them; export includes them in the JSON.
• D058 (Console): All backup/export operations have /backup and /profile console command equivalents.

Phase

• Phase 0: Define and document the <data_dir> directory layout (this decision). Add IC_DATA_DIR / --data-dir override support.
• Phase 2: ic backup create/restore CLI ships alongside the save/load system. Screenshot capture with PNG metadata. Automatic daily critical snapshots (3-day rotating auto-critical-N.zip). Mnemonic seed generation integrated into identity creation — ic identity seed show, ic identity seed verify, ic identity recover CLI commands.
• Phase 3: Screenshot browser UI with metadata filtering and replay linking. Data & Backup settings panel (including “View recovery phrase” button). Post-milestone nudge toasts (first nudge reminds about recovery phrase if not yet confirmed). First-launch identity creation with recovery phrase display + cloud sync offer. Mnemonic recovery option in first-launch restore flow.
• Phase 5: ic profile export ships alongside multiplayer launch (GDPR compliance). Platform cloud sync via PlatformServices trait (Steam Cloud, GOG Galaxy). ic backup verify for archive integrity checking. First-launch restore flow (cloud detection + manual restore + mnemonic recovery). Console commands (/backup, /profile, /identity, /data, /cloud).