[Design] Older maps silently go stale as signatures grow (no backfill path)

Status: IN-DISCOVERY (reopened 2026-06-09)

The "Hybrid" direction below is provisional and under active design review — not locked. A software-architect design pass is in progress to confirm, refine, or replace it before any implementation. Do not build against this yet.

Provisional direction (under review): Hybrid

Committed maps remain the zero-toolchain default. On top of that:

1. Detect staleness — pin the signatures revision each map was generated from (#36), surface drift as CI metadata + a generated staleness dashboard (never a hard fail, which would block legitimate PRs).
2. Escape hatch — an opt-in rosetta regen / rosetta pull --from-signatures that regenerates the map from signatures @ HEAD + the developer's own local APK (they're hooking that app — they already have it; sigmatcher is offline regex-over-smali, so it runs on the host). No new invariant broken: no APK in CI, none on device, no device network I/O.

Provisionally rejected: derive-at-build primary (forces the sigmatcher/decompile toolchain on every consumer); cache-only (keeps maps as a silent bottleneck, no escape hatch). The architect pass is explicitly tasked with stress-testing these.

Background (the analysis)

Signatures are version-independent knowledge; maps are version-pinned snapshots. A map is f(signatures @ rev R, APK @ version V); signatures grow monotonically while maps freeze at their authoring R. So the corpus is really a lazily-populated, partial cache of signature-application results that we'd been treating as a complete product. Two failure modes: (a) staleness is undetectable, (b) regeneration needs the APK, which is off-CI by Hard rule 3.

Consumer-visible symptom: a hook author bundles an older <version_code>.json, references a real name added to signatures later, and the resolver fails to resolve it — though the signature exists and the older APK contains the class. The map, not the knowledge, is the bottleneck.

Not pursuing: per-version map diffs/inheritance — breaks the settled flat-version_code O(1) selection model.

Candidate work items (pending the design)

• #36 — signatures-rev pin (prerequisite for staleness detection)
• CI staleness report + dashboard (metadata, non-blocking)
• rosetta regen / pull --from-signatures opt-in regeneration (rosetta-frida CLI; APK stays on the dev host)
• Document the "maps are a partial cache" contract for consumers

Related: #29, #28.

Begin with the provisional direction and prerequisite #36; review how signatures revisions and committed maps are currently represented. Assess the non-blocking CI metadata/dashboard and opt-in rosetta regen/pull flow against the stated constraints. Done is an agreed design and implementation scope, with the consumer contract documented if it remains in scope.