@kumbatio/energy-system 0.2.1 → 0.4.0

package/README.md

@@ -30,10 +30,19 @@ This library gives applications a structured way to adapt to energy state instea
   - UI visibility
   - Notification filtering
   - Task complexity guidance
+  - Interaction forgiveness (undo windows, destructive-action confirmation)
+  - Energy-aware deferral ordering
+- **Presence annotation**: declare which energy levels a component/view belongs
+  to (`defineEnergyPresence`, `presenceAtOrAbove`, `<EnergyGate>`, `data-energy-min`)
+- **Focus sessions**: time-boxed suppression windows with auto-expiry and break nudges
+- **Notification gate**: a runtime that enforces `NotificationConfig`
+  (threshold, batching, defer-not-drop) instead of leaving it as guidance
+- **Deferral presets**: pure "not now" (`snooze`) computations with
+  energy-aware default ordering
 - DOM adapter (`data-energy-level` + CSS variables)
-- React provider, hooks, and headless render component
+- React provider, hooks, and headless render components
 - Persistence adapters (`localStorage`, in-memory)
-- Deterministic clock support for testing/simulation
+- Deterministic clock and timer support for testing/simulation
 - Optional external persistence observation (`observe`)
 - Derived metrics helper (`getEnergyMetrics`)
 - Compatibility helpers for non-native external level models
@@ -103,6 +112,133 @@ export function App() {
 }
 ```
 
+## Presence annotation (which energy states does this element belong to?)
+
+Every component/view can declare the energy levels it participates in. The
+declaration is a plain typed object — one presence (`'visible' | 'muted' |
+'hidden'`) per level — so the same annotation drives React, the engine, or
+plain CSS.
+
+```ts
+import {
+  defineEnergyPresence,
+  presenceAtOrAbove,
+  presenceAtOrBelow,
+  createPresenceStrategy,
+  resolveEnergyPresence,
+} from '@kumbatio/energy-system'
+
+// Explicit map: hide the AI chat at 50 and below, mute it at 75
+const aiChatPresence = defineEnergyPresence({
+  default: 'visible',
+  75: 'muted',
+  50: 'hidden',
+  25: 'hidden',
+  0: 'hidden',
+})
+
+// Shorthands
+const composerTools = presenceAtOrAbove(50) // hidden at 25 and 0
+const recoveryHint = presenceAtOrBelow(25) // low-energy-only affordance
+
+// Resolve anywhere
+resolveEnergyPresence(aiChatPresence, 50) // 'hidden'
+
+// Or lift into a strategy and resolve through the engine
+const aiChat = createPresenceStrategy('ai-chat', aiChatPresence)
+engine.resolve(aiChat) // 'visible' | 'muted' | 'hidden'
+```
+
+In React, `<EnergyGate>` applies a presence declaration to a subtree:
+
+```tsx
+import { EnergyGate } from '@kumbatio/energy-system/react'
+
+// Shorthand: needs at least 75 energy
+<EnergyGate min={75}>
+  <AiChatPanel />
+</EnergyGate>
+
+// Full map; function children receive the resolved presence so 'muted'
+// can style itself
+<EnergyGate presence={aiChatPresence} fallback={<QuietPlaceholder />}>
+  {(presence) => <AiChatPanel muted={presence === 'muted'} />}
+</EnergyGate>
+```
+
+CSS-only path — annotate elements with the range they belong to and the
+stylesheet handles hiding as `data-energy-level` changes:
+
+```html
+<div data-energy-min="75">AI chat — needs 75+ energy</div>
+<div data-energy-max="25">Recovery hint — low energy only</div>
+```
+
+## Focus sessions and the notification gate
+
+These are the runtime half of the model: strategies _describe_ behavior,
+the gate and session controller _enforce_ it.
+
+```ts
+import {
+  createEnergyEngine,
+  createNotificationGate,
+  createFocusSessionController,
+} from '@kumbatio/energy-system'
+
+const engine = createEnergyEngine({ initialLevel: 75 })
+
+// The gate enforces notificationStrategy: at 50 it batches every 5 minutes
+// and only lets 'high'+ through; at 0 everything is deferred, not dropped.
+const gate = createNotificationGate(engine, {
+  onDeliver({ notifications, reason, channels }) {
+    if (channels.visual) showToast(notifications, reason)
+  },
+})
+
+gate.publish({ priority: 'high', payload: { title: 'Build finished' } })
+
+// Focus sessions: time-boxed, auto-expiring suppression windows.
+const focus = createFocusSessionController({ engine, gate })
+focus.subscribe((event, session) => {
+  if (event === 'break') showBreakNudge()
+  if (event === 'end') showSessionSummary(session)
+})
+
+// Session length + break cadence default from the current energy level
+// (expected productivity window / task-complexity guidance).
+focus.start()
+```
+
+Two invariants are guaranteed by construction:
+
+1. **Nothing is silently dropped.** A notification the current level does not
+   admit is deferred and released when energy rises, suppression lifts, or the
+   gate is disposed.
+2. **Sessions always end.** Expiry is an emitted event (never a predicate you
+   must poll), and suppression is lifted _before_ the end event fires, so an
+   end-of-session notification can never be swallowed by the session itself.
+
+## Deferral ("not now")
+
+Deferring is an energy statement. Presets are pure `(now) => Date` functions;
+`deferralStrategy` orders them by level so the one-tap default matches
+capacity — at low energy the default is "tomorrow morning", not "in 1 hour".
+
+```ts
+import {
+  createDeferralPresets,
+  deferralStrategy,
+  resolveDeferral,
+  DEFERRAL_PRESET_IDS,
+} from '@kumbatio/energy-system'
+
+const presets = createDeferralPresets({ morningHour: 9, eveningHour: 18 })
+const { defaultPresetId, orderedPresetIds } = engine.resolve(deferralStrategy)
+
+const resurfaceAt = resolveDeferral(presets, defaultPresetId) // epoch ms
+```
+
 ## Quick start (DOM)
 
 ```ts
@@ -135,6 +271,16 @@ Then use classes like:
 - `.energy-toolbar`
 - `.energy-content`
 
+And presence attributes:
+
+- `data-energy-min="75"` — element hides whenever the current level is below 75
+- `data-energy-max="25"` — element hides whenever the current level is above 25
+- `data-energy-presence="muted" | "hidden"` — hooks for JS-resolved presence
+  (`--energy-muted-opacity` controls the muted treatment)
+
+The stylesheet honours `prefers-reduced-motion` for its own transitions; apps
+animating presence changes should do the same.
+
 ## API map
 
 ### Core package
@@ -146,8 +292,21 @@ Then use classes like:
 - `cycleDiscreteLevel(current, levels, fallback)`
 - `mapToNearestDiscreteLevel(value, levels, fallback)`
 - `mapToNearestEnergyLevel(value)`
-- Strategies: `uiVisibilityStrategy`, `notificationStrategy`, `taskComplexityStrategy`
-- Types: `EnergyLevel`, `EnergyState`, `AdaptationStrategy`, etc.
+- Strategies: `uiVisibilityStrategy`, `notificationStrategy`,
+  `taskComplexityStrategy`, `interactionForgivenessStrategy`, `deferralStrategy`
+- Presence: `defineEnergyPresence(spec)`, `presenceAtOrAbove(min, below?)`,
+  `presenceAtOrBelow(max, above?)`, `resolveEnergyPresence(map, level)`,
+  `isPresenceVisible(presence)`, `isEnergyPresence(value)`,
+  `createPresenceStrategy(name, map)`
+- Focus sessions: `createFocusSessionController(options?)`,
+  `sessionRemainingMs(session, now?)`, `isSessionExpired(session, now?)`
+- Notification gate: `createNotificationGate(engine, options)`,
+  `resolveNotificationOutcome(config, priority, suppressed)`,
+  `isNotificationPriority(value)`
+- Deferral: `createDeferralPresets(options?)`, `resolveDeferral(presets, id, now?)`,
+  `DEFERRAL_PRESET_IDS`
+- Types: `EnergyLevel`, `EnergyState`, `EnergyPresence`, `EnergyPresenceMap`,
+  `AdaptationStrategy`, `FocusSession`, `NotificationDelivery`, etc.
 
 ### `@kumbatio/energy-system/react`
 
@@ -157,6 +316,8 @@ Then use classes like:
 - `useEnergyLevelCycler()`
 - `useStrategy(strategy)`
 - `useEnergyGate(minLevel)`
+- `useEnergyPresence(presenceMap)`
+- `EnergyGate` (presence-gated subtree: `presence` map or `min`/`max` shorthand)
 - `EnergyIndicator`
 
 ### `@kumbatio/energy-system/persistence`
@@ -175,7 +336,12 @@ Then use classes like:
 - `createEnergyEngine({ clock })` - inject a deterministic time source
 - `createEnergyEngine({ originId })` - inject a deterministic producer identity for tests
 - `createEnergyEngine({ onPersistenceError })` - observe failed save attempts before retry
-- `engine.flush()` - wait until the current state version is durably persisted
+- `createEnergyEngine({ maxFutureSkewMs })` - reject hydrated/observed state stamped further
+  ahead of the local clock than this budget (default 5 minutes; `Number.POSITIVE_INFINITY`
+  accepts any finite timestamp). Guards reconciliation against contexts with bad clocks.
+- `engine.flush()` - wait until the current state version is durably persisted; rejects if the
+  engine is disposed or an unchanged initial state cannot be safely reconciled after a hydration
+  read failure
 - `engine.dispose()` - release engine-owned observation/subscription resources
 - `EnergyPersistence.observe(onState)` - subscribe to external state changes
 - `getEnergyMetrics(state, now?)` - derive productivity/break/task guidance metrics
@@ -232,7 +398,8 @@ clock timestamp. Local writes advance the logical revision when the clock does n
 
 `setLevel()` updates in-memory subscribers synchronously. Persistence runs in the background with
 bounded exponential backoff. Call `await engine.flush()` when a workflow must wait for durable
-storage before reporting completion.
+storage before reporting completion. An initial `flush()` waits for hydration before writing the
+default state, and rejects rather than overwriting unread storage if that hydration read failed.
 
 ## Development
 

package/dist/defer.d.ts

@@ -0,0 +1,40 @@
+import type { AdaptationStrategy } from './types.js';
+/** A named deferral option */
+export interface DeferralPreset {
+    readonly id: string;
+    readonly label: string;
+    /** Compute the resurface time from a reference moment */
+    compute(now: Date): Date;
+}
+export interface DeferralPresetOptions {
+    /** Hour (0-23) mornings resolve to. Default 9. */
+    morningHour?: number;
+    /** Hour (0-23) evenings resolve to. Default 18. */
+    eveningHour?: number;
+}
+/** Stable preset ids, exported so configs/strategies can reference them */
+export declare const DEFERRAL_PRESET_IDS: Readonly<{
+    readonly inOneHour: 'in-1-hour';
+    readonly thisEvening: 'this-evening';
+    readonly tomorrowMorning: 'tomorrow-morning';
+    readonly nextWorkday: 'next-workday';
+    readonly nextMonday: 'next-monday';
+}>;
+/**
+ * Build the standard deferral presets. Times are computed in local time —
+ * "tomorrow morning" means the user's morning.
+ */
+export declare function createDeferralPresets(options?: DeferralPresetOptions): readonly DeferralPreset[];
+/**
+ * Resolve a preset id to a resurface timestamp (epoch ms).
+ * Returns null for an unknown id — callers decide whether that is an error.
+ */
+export declare function resolveDeferral(presets: readonly DeferralPreset[], presetId: string, now?: Date): number | null;
+export interface DeferralConfig {
+    /** Preset ids in suggestion order for this level (first = most prominent) */
+    readonly orderedPresetIds: readonly string[];
+    /** The preset a one-tap "defer" action should use at this level */
+    readonly defaultPresetId: string;
+}
+export declare const deferralStrategy: AdaptationStrategy<DeferralConfig>;
+//# sourceMappingURL=defer.d.ts.map

package/dist/defer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defer.d.ts","sourceRoot":"","sources":["../src/defer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAe,MAAM,YAAY,CAAA;AAejE,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,yDAAyD;IACzD,OAAO,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB;wBACnB,WAAW;0BACT,cAAc;8BACV,kBAAkB;0BACtB,cAAc;yBACf,aAAa;EAChB,CAAA;AAmBX;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,qBAA0B,GAClC,SAAS,cAAc,EAAE,CA4D3B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,IAAiB,GACrB,MAAM,GAAG,IAAI,CAIf;AAID,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAyDD,eAAO,MAAM,gBAAgB,EAAE,kBAAkB,CAAC,cAAc,CAU/D,CAAA"}

package/dist/defer.js

@@ -0,0 +1,173 @@
+import { getEnergyLevel } from './levels.js';
+/**
+ * Deferral ("snooze") — the "not now" primitive. Deferring an item is an
+ * energy statement: it declares insufficient capacity for it right now and
+ * names when it should resurface. Presets are pure `(now) -> Date` functions;
+ * the energy-aware strategy orders them so the default suggestion matches
+ * current capacity (low energy -> longer deferrals, because items should
+ * resurface when capacity has plausibly recovered, not in an hour).
+ */
+function freezeObject(value) {
+    return Object.freeze(value);
+}
+/** Stable preset ids, exported so configs/strategies can reference them */
+export const DEFERRAL_PRESET_IDS = freezeObject({
+    inOneHour: 'in-1-hour',
+    thisEvening: 'this-evening',
+    tomorrowMorning: 'tomorrow-morning',
+    nextWorkday: 'next-workday',
+    nextMonday: 'next-monday',
+});
+function validateHour(name, value) {
+    if (!Number.isInteger(value) || value < 0 || value > 23) {
+        throw new Error(`Invalid ${name}: ${String(value)} (expected an integer hour 0-23)`);
+    }
+}
+function startOfDay(from) {
+    const day = new Date(from);
+    day.setHours(0, 0, 0, 0);
+    return day;
+}
+function isWeekend(day) {
+    const weekday = day.getDay();
+    return weekday === 0 || weekday === 6;
+}
+/**
+ * Build the standard deferral presets. Times are computed in local time —
+ * "tomorrow morning" means the user's morning.
+ */
+export function createDeferralPresets(options = {}) {
+    const { morningHour = 9, eveningHour = 18 } = options;
+    validateHour('morningHour', morningHour);
+    validateHour('eveningHour', eveningHour);
+    return Object.freeze([
+        freezeObject({
+            id: DEFERRAL_PRESET_IDS.inOneHour,
+            label: 'In 1 hour',
+            compute(now) {
+                return new Date(now.getTime() + 60 * 60_000);
+            },
+        }),
+        freezeObject({
+            id: DEFERRAL_PRESET_IDS.thisEvening,
+            label: `This evening (${eveningHour}:00)`,
+            compute(now) {
+                const evening = startOfDay(now);
+                evening.setHours(eveningHour);
+                if (evening.getTime() <= now.getTime()) {
+                    evening.setDate(evening.getDate() + 1);
+                }
+                return evening;
+            },
+        }),
+        freezeObject({
+            id: DEFERRAL_PRESET_IDS.tomorrowMorning,
+            label: `Tomorrow morning (${morningHour}:00)`,
+            compute(now) {
+                const morning = startOfDay(now);
+                morning.setDate(morning.getDate() + 1);
+                morning.setHours(morningHour);
+                return morning;
+            },
+        }),
+        freezeObject({
+            id: DEFERRAL_PRESET_IDS.nextWorkday,
+            label: `Next workday (${morningHour}:00)`,
+            compute(now) {
+                const day = startOfDay(now);
+                day.setDate(day.getDate() + 1);
+                while (isWeekend(day)) {
+                    day.setDate(day.getDate() + 1);
+                }
+                day.setHours(morningHour);
+                return day;
+            },
+        }),
+        freezeObject({
+            id: DEFERRAL_PRESET_IDS.nextMonday,
+            label: `Next Monday (${morningHour}:00)`,
+            compute(now) {
+                const day = startOfDay(now);
+                const delta = (1 - day.getDay() + 7) % 7 || 7;
+                day.setDate(day.getDate() + delta);
+                day.setHours(morningHour);
+                return day;
+            },
+        }),
+    ]);
+}
+/**
+ * Resolve a preset id to a resurface timestamp (epoch ms).
+ * Returns null for an unknown id — callers decide whether that is an error.
+ */
+export function resolveDeferral(presets, presetId, now = new Date()) {
+    const preset = presets.find((candidate) => candidate.id === presetId);
+    if (!preset)
+        return null;
+    return preset.compute(now).getTime();
+}
+const IDS = DEFERRAL_PRESET_IDS;
+const DEFERRAL_CONFIGS = freezeObject({
+    100: freezeObject({
+        orderedPresetIds: Object.freeze([
+            IDS.inOneHour,
+            IDS.thisEvening,
+            IDS.tomorrowMorning,
+            IDS.nextWorkday,
+            IDS.nextMonday,
+        ]),
+        defaultPresetId: IDS.inOneHour,
+    }),
+    75: freezeObject({
+        orderedPresetIds: Object.freeze([
+            IDS.inOneHour,
+            IDS.thisEvening,
+            IDS.tomorrowMorning,
+            IDS.nextWorkday,
+            IDS.nextMonday,
+        ]),
+        defaultPresetId: IDS.inOneHour,
+    }),
+    50: freezeObject({
+        orderedPresetIds: Object.freeze([
+            IDS.thisEvening,
+            IDS.tomorrowMorning,
+            IDS.inOneHour,
+            IDS.nextWorkday,
+            IDS.nextMonday,
+        ]),
+        defaultPresetId: IDS.thisEvening,
+    }),
+    25: freezeObject({
+        orderedPresetIds: Object.freeze([
+            IDS.tomorrowMorning,
+            IDS.nextWorkday,
+            IDS.thisEvening,
+            IDS.nextMonday,
+            IDS.inOneHour,
+        ]),
+        defaultPresetId: IDS.tomorrowMorning,
+    }),
+    0: freezeObject({
+        orderedPresetIds: Object.freeze([
+            IDS.tomorrowMorning,
+            IDS.nextMonday,
+            IDS.nextWorkday,
+            IDS.thisEvening,
+            IDS.inOneHour,
+        ]),
+        defaultPresetId: IDS.tomorrowMorning,
+    }),
+});
+export const deferralStrategy = {
+    name: 'deferral',
+    describe(level) {
+        const def = getEnergyLevel(level);
+        const config = DEFERRAL_CONFIGS[def.value];
+        return `${def.label}: default deferral is "${config.defaultPresetId}"`;
+    },
+    resolve(level) {
+        return DEFERRAL_CONFIGS[getEnergyLevel(level).value];
+    },
+};
+//# sourceMappingURL=defer.js.map

package/dist/defer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defer.js","sourceRoot":"","sources":["../src/defer.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -9,6 +9,14 @@ export interface EnergyEngineOptions {
     clock?: EnergyClock | (() => number);
     /** Stable producer identity for deterministic reconciliation. Primarily useful in tests. */
     originId?: string;
+    /**
+     * Maximum tolerated future clock skew (ms) for externally supplied state
+     * (hydration and cross-context observation). States stamped further ahead of
+     * the local clock are rejected so one bad clock cannot win reconciliation
+     * until its timestamp passes. Pass Number.POSITIVE_INFINITY to accept any
+     * finite timestamp. Default: 5 minutes.
+     */
+    maxFutureSkewMs?: number;
 }
 export interface EnergyEngine {
     /** Get current energy state */
@@ -23,7 +31,11 @@ export interface EnergyEngine {
     resolve<T>(strategy: AdaptationStrategy<T>): T;
     /** Load persisted state (called automatically, but can be called manually) */
     hydrate(): Promise<void>;
-    /** Wait until the current state version is durably persisted. */
+    /**
+     * Wait until the current state version is durably persisted.
+     * Rejects if the engine is disposed or an unchanged initial state cannot be
+     * reconciled because its persistence hydration read failed.
+     */
     flush(): Promise<void>;
     /** Release engine-owned subscriptions/resources */
     dispose(): void;

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,WAAW,CAAA;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IAC/B,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACjE,sDAAsD;IACtD,KAAK,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,MAAM,CAAC,CAAA;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,QAAQ,IAAI,WAAW,CAAA;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IACzD,iCAAiC;IACjC,UAAU,IAAI,IAAI,CAAA;IAClB,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAA;IACrD,sDAAsD;IACtD,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAC9C,8EAA8E;IAC9E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,mDAAmD;IACnD,OAAO,IAAI,IAAI,CAAA;CAChB;AAgFD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CA0QlF"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,WAAW,CAAA;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IAC/B,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACjE,sDAAsD;IACtD,KAAK,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,MAAM,CAAC,CAAA;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,QAAQ,IAAI,WAAW,CAAA;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IACzD,iCAAiC;IACjC,UAAU,IAAI,IAAI,CAAA;IAClB,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAA;IACrD,sDAAsD;IACtD,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAC9C,8EAA8E;IAC9E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,mDAAmD;IACnD,OAAO,IAAI,IAAI,CAAA;CAChB;AA2FD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAiUlF"}

package/dist/engine.js

@@ -4,6 +4,7 @@ function logEngineError(message, err) {
 }
 const PERSIST_RETRY_INITIAL_MS = 250;
 const PERSIST_RETRY_MAX_MS = 30_000;
+const DEFAULT_MAX_FUTURE_SKEW_MS = 5 * 60_000;
 function resolveNow(clock) {
     if (typeof clock === 'function')
         return clock;
@@ -48,17 +49,25 @@ function isPreferredExternalState(candidate, current) {
     }
     return false;
 }
-function normalizeState(candidate) {
+function normalizeState(candidate, nowMs, maxFutureSkewMs) {
     if (!isEnergyLevel(candidate.level)) {
         throw new Error(`Invalid energy level from persistence: ${String(candidate.level)}`);
     }
     if (!isEnergySource(candidate.source)) {
         throw new Error(`Invalid energy source from persistence: ${String(candidate.source)}`);
     }
+    if (candidate.timestamp - nowMs > maxFutureSkewMs) {
+        throw new Error(`Energy state timestamp ${String(candidate.timestamp)} exceeds local clock by more than ${String(maxFutureSkewMs)}ms`);
+    }
     return createEnergyState(candidate.level, candidate.source, candidate.timestamp, candidate.revision, candidate.origin);
 }
 export function createEnergyEngine(options = {}) {
-    const { initialLevel = 100, persistence, onChange, onPersistenceError, clock, originId = createEnergyOrigin(), } = options;
+    const { initialLevel = 100, persistence, onChange, onPersistenceError, clock, originId = createEnergyOrigin(), maxFutureSkewMs = DEFAULT_MAX_FUTURE_SKEW_MS, } = options;
+    if (typeof maxFutureSkewMs !== 'number' ||
+        (!Number.isFinite(maxFutureSkewMs) && maxFutureSkewMs !== Number.POSITIVE_INFINITY) ||
+        maxFutureSkewMs < 0) {
+        throw new Error(`Invalid maxFutureSkewMs: ${String(maxFutureSkewMs)}`);
+    }
     const now = resolveNow(clock);
     const listeners = new Set();
     const notificationQueue = [];
@@ -66,11 +75,17 @@ export function createEnergyEngine(options = {}) {
     let disposed = false;
     let isNotifying = false;
     let state = createEnergyState(initialLevel, 'manual', now(), 0, originId);
-    let persistedVersion = 0;
+    // Version 0 is the initial in-memory state, not proof that a persistence
+    // adapter has durably stored it. Starting below the version domain keeps
+    // flush() honest even before the first state transition.
+    let persistedVersion = -1;
     let requestedPersistVersion = 0;
     let persistTask;
     let persistRetryTimer;
     let persistRetryDelayMs = PERSIST_RETRY_INITIAL_MS;
+    let initialHydrationTask;
+    let hasCompletedPersistenceLoad = false;
+    let persistenceLoadError;
     const persistWaiters = [];
     function resolvePersistWaiters() {
         for (let index = persistWaiters.length - 1; index >= 0; index -= 1) {
@@ -180,12 +195,26 @@ export function createEnergyEngine(options = {}) {
             return state;
         },
         setLevel(level, source = 'manual') {
+            if (disposed)
+                return;
             const wallTime = now();
-            const timestamp = Math.max(wallTime, state.timestamp);
-            const revision = timestamp === state.timestamp ? state.revision + 1 : 0;
+            let timestamp = Math.max(wallTime, state.timestamp);
+            let revision = 0;
+            if (timestamp === state.timestamp) {
+                if (state.revision === Number.MAX_SAFE_INTEGER) {
+                    // Preserve a strictly newer ordering key without producing an
+                    // invalid revision when a deterministic/future clock cannot advance.
+                    timestamp += 1;
+                }
+                else {
+                    revision = state.revision + 1;
+                }
+            }
             applyState(createEnergyState(level, source, timestamp, revision, originId));
         },
         cycleLevel() {
+            if (disposed)
+                return;
             engine.setLevel(cycleEnergyLevel(state.level), 'manual');
         },
         subscribe(listener) {
@@ -207,8 +236,11 @@ export function createEnergyEngine(options = {}) {
             let stored;
             try {
                 stored = await persistence.load();
+                hasCompletedPersistenceLoad = true;
+                persistenceLoadError = undefined;
             }
             catch (err) {
+                persistenceLoadError = err;
                 logEngineError('Failed to load persisted energy state', err);
                 return;
             }
@@ -216,7 +248,7 @@ export function createEnergyEngine(options = {}) {
                 return;
             let normalized;
             try {
-                normalized = normalizeState(stored);
+                normalized = normalizeState(stored, now(), maxFutureSkewMs);
             }
             catch (err) {
                 logEngineError('Ignoring invalid persisted energy state', err);
@@ -234,6 +266,18 @@ export function createEnergyEngine(options = {}) {
             if (disposed) {
                 throw new Error('Cannot flush a disposed energy engine');
             }
+            // Do not persist the default state over an unread stored value. Once a
+            // local/external transition exists, that newer intent can persist
+            // immediately; an unchanged initial state must wait for auto-hydration.
+            if (stateVersion === 0 && initialHydrationTask) {
+                await initialHydrationTask;
+            }
+            if (disposed) {
+                throw new Error('Cannot flush a disposed energy engine');
+            }
+            if (stateVersion === 0 && !hasCompletedPersistenceLoad) {
+                throw new Error('Cannot flush the initial energy state because persistence hydration did not complete', { cause: persistenceLoadError });
+            }
             const targetVersion = stateVersion;
             if (persistedVersion >= targetVersion)
                 return;
@@ -248,7 +292,12 @@ export function createEnergyEngine(options = {}) {
             if (disposed)
                 return;
             disposed = true;
-            disposePersistenceObservation();
+            try {
+                disposePersistenceObservation();
+            }
+            catch (err) {
+                logEngineError('Failed to release persistence observation', err);
+            }
             if (persistRetryTimer) {
                 clearTimeout(persistRetryTimer);
                 persistRetryTimer = undefined;
@@ -263,7 +312,7 @@ export function createEnergyEngine(options = {}) {
     };
     // Auto-hydrate from persistence
     if (persistence) {
-        void engine.hydrate().catch((err) => {
+        initialHydrationTask = engine.hydrate().catch((err) => {
             logEngineError('Unexpected hydrate failure', err);
         });
     }
@@ -274,7 +323,7 @@ export function createEnergyEngine(options = {}) {
                     return;
                 let normalized;
                 try {
-                    normalized = normalizeState(externalState);
+                    normalized = normalizeState(externalState, now(), maxFutureSkewMs);
                 }
                 catch (err) {
                     logEngineError('Ignoring invalid observed energy state', err);