once_new 0.0.1

Run a block once, or at most once per hour / day / week / month / year / app version. The bookkeeping lives in SharedPreferences; there is nothing to initialize.

0.0.1

Initial release.

• Added Once.claim, the ask-and-record gate: the call that answers true also writes the mark, so there is no separate bookkeeping step to forget. Concurrent calls on the same key are serialized, so only one of them opens the gate.
• Added OncePolicy, a sealed set of typed policies: once(), every(Duration), everyDay(), everyMonth(), everyYear(), and onChange(token, runOnFirstSeen:). Calendar policies store a full yyyy-MM-dd / yyyy-MM / yyyy bucket, and onChange compares tokens for inequality, so a rolled-back version fires too.
• Added Once.warmUp() plus the synchronous Once.claimSync and Once.isDueSync, for deciding inside build without rendering a "don't know yet" frame. claimSync throws a StateError when the cache was never warmed instead of silently answering "not done".
• Added Once.run, returning OnceResult with a separate ran flag, so "the callback returned null" and "the gate was closed" are distinguishable.
• Added Once.markDone, Once.clear, and Once.clearAll. clearAll only removes keys under the once_new. prefix, matched with startsWith.
• Added Once.flush(). All persistence goes through a single queue, so the write claimSync fires off cannot land after a later clear and resurrect the record; flush awaits that queue when the disk needs to be settled.
• A policy that sees a key for the first time records its anchor even when it does not fire, so onChange(token, runOnFirstSeen: false) seeds the current token on a fresh install instead of staying in the "never seen" state forever.
• Added the OnceStore interface with SharedPreferencesOnceStore and MemoryOnceStore, plus Once.debugOverride / Once.debugReset for injecting a store and a clock, so the decision logic time-travels in plain unit tests.
• Records are persisted with the policy tag alongside the anchor, so changing a key's policy starts a new record instead of misreading the old one. Unparseable values are treated as "no record" rather than throwing.
• every(Duration) treats an anchor in the future as expired, so a backwards system clock or an NTP step doesn't lock the gate until real time catches up.
• Only depends on shared_preferences; version tokens are passed in by the caller rather than pulling in package_info_plus.