# Starfall Haven 0.4.0 Chronicle Contract

## Identity
- Package: `space.animefu.starfallhaven`
- Version code/name: `4` / `0.4.0`
- Landscape, minSdk 23, targetSdk 35.
- Preserve qualified 0.1→0.2→0.3 signing and save lineage.

## Original system
The feature is named the **Chronicle Director**. It must not copy another game's storyteller identities, terminology, pacing presets, prose, UI, balance, or event implementation.

## Authority boundary
- The deterministic local director is authoritative for event eligibility, weighting, cooldowns, tension, consequences, and save state.
- The only executable consequences are audited event-catalog operations implemented in local Java.
- Grok receives a bounded summary only after a catalog event exists.
- Grok may return `title`, `story`, and `tone`; it cannot return commands or mutate the colony.
- A failed, offline, malformed, oversized, or rate-limited request keeps the local narrative and never blocks simulation.

## Secret boundary
- Never embed the OpenRouter token in Java, resources, APK assets, source archives, logs, screenshots, or generated manifests.
- Android calls `https://animefu.space/api/starfall-chronicle` without credentials.
- The proxy stores the token at `/opt/starfall-chronicle/openrouter.token`, mode `0600`, and pins `x-ai/grok-4.6`.
- Proxy accepts only known catalog event IDs, bounded numeric colony facts, and a short local context string.
- Proxy uses strict structured output and rate/request/response limits.

## Persistence
Version 4 saves must preserve enough local Chronicle state to reproduce future scheduling and history: director seed/state, tension, next eligible day, cooldown/history records, local narrative, and any accepted Grok narrative. v1/v2/v3 saves migrate deterministically without rewriting frozen fixtures.

## Verification
- deterministic director tests
- event eligibility/cooldown/consequence-bound tests
- malformed/oversized/offline narrative fallback tests
- live proxy health, invalid-event rejection, and real Grok structured narration
- no main-thread network access
- signed 0.3→0.4 upgrade and v3 save migration
- fresh and migrated emulator interaction through the Chronicle panel
- final APK/source credential scan
