# Config Field Drift

The most common silent failure in DruksCode: a feature works in preview but is quietly skipped in the exported APK because a config field name drifted between the export factory and the shell config class.

## Why it happens

The shell reads its config with **Gson**, and Gson **silently drops** unknown or missing fields — no exception, no log. So if the JSON key written by the export factory does not exactly match the `@SerializedName` on the shell config field, the feature just… doesn't run, with no error.

The three things that must stay aligned:

1. The payload keys in `ApkConfigJsonFactory.kt` (the `"key" to value` pairs).
2. The `@SerializedName("key")` annotations in `ShellModeManager.kt`'s shell config classes.
3. The `ApkConfig` fields they map from.

## The gate

A CI gate checks this automatically:

```bash
./gradlew :app:checkConfigFieldDrift --no-configuration-cache
# or directly:
python3 scripts/check_config_field_drift.py
```

It parses the payload keys out of `ApkConfigJsonFactory.kt` and the `@SerializedName` annotations out of `ShellModeManager.kt`, then reports any mismatch (subject to an allowlist in `scripts/config_field_drift_allowlist.json`).

**Run it whenever you change config fields.** It is part of the Android CI `check` job.

## Diagnosis checklist

When a feature "works in preview, broken after export," check in this order:

1. Did the shell config JSON actually contain the field at runtime?
2. Does the field name in `ApkConfig` JSON match the `@SerializedName` in shell config? Run `checkConfigFieldDrift`.
3. Is the runtime use site shell-synced (not host-only)?
4. For adblock specifically: confirm `adBlockEnabled` mapping, host filter rebuild from cached subscriptions, and export rule compile without wiping host state.
5. Rebuild the template after sync changes (stale template is a frequent miss).

## Adding a setting that affects the generated APK

Trace and update **all** of:

1. Model (`WebApp` / nested config) and editor UI binding.
2. Export mapping (`ApkBuilder` / `ApkConfig` / `ApkConfigJsonFactory`).
3. Shell config types (`ShellModeManager` / shell config data classes) if the runtime reads them.
4. Runtime use site in shell-synced code.
5. Unit tests for export wiring when flags change.

Missing any step usually yields: editor shows the switch, export ignores it, or export embeds config the runtime never reads.