Core

import { DEFERRAL_PRESET_IDS, ENERGY_LEVEL_VALUES, ENERGY_PRESENCE_VALUES } from '@kumbatio/energy-system'

export declare function createDeferralPresets(options?: DeferralPresetOptions): readonly DeferralPreset[];

export declare function createEnergyEngine(options?: EnergyEngineOptions): EnergyEngine;

export declare function createEnergyOrigin(): string;

export declare function createEnergyState(level: EnergyLevel, source?: EnergySource, timestamp?: number, revision?: number, origin?: string): EnergyState;

export declare function createExternalLevelCompatibility<TExternal extends number>(options: ExternalLevelCompatibilityOptions<TExternal>): ExternalLevelCompatibility<TExternal>;

export declare function createFocusSessionController(options?: FocusSessionControllerOptions): FocusSessionController;

export declare function createNotificationGate(engine: EnergyEngine, options: NotificationGateOptions): NotificationGate;

export declare function createPresenceStrategy(name: string, presence: EnergyPresenceMap): AdaptationStrategy<EnergyPresence>;

const aiChat = createPresenceStrategy('ai-chat', presenceAtOrAbove(75))
engine.resolve(aiChat) // 'visible' | 'muted' | 'hidden'

export declare function cycleDiscreteLevel<TLevel extends number>(current: number, levels: readonly TLevel[], fallback: TLevel): TLevel;

export declare function cycleEnergyLevel(current: EnergyLevel): EnergyLevel;

export declare function defineEnergyPresence(spec?: EnergyPresenceSpec): EnergyPresenceMap;

// Hide the AI chat at 50 and below, keep it muted at 75:
const aiChatPresence = defineEnergyPresence({
  default: 'visible',
  75: 'muted',
  50: 'hidden',
  25: 'hidden',
  0: 'hidden',
})

export declare function getEnergyLevel(level: EnergyLevel): Readonly<EnergyLevelDefinition>;

export declare function getEnergyLevels(): ReadonlyArray<Readonly<EnergyLevelDefinition>>;

export declare function getEnergyMetrics(state: EnergyState, now?: number): EnergyMetrics;

export declare function isEnergyLevel(value: unknown): value is EnergyLevel;

export declare function isEnergyPresence(value: unknown): value is EnergyPresence;

export declare function isEnergySource(value: unknown): value is EnergySource;

export declare function isHigherEnergy(a: EnergyLevel, b: EnergyLevel): boolean;

export declare function isNotificationPriority(value: unknown): value is NotificationPriority;

export declare function isOriginatorTier(value: unknown): value is OriginatorTier;

export declare function isPreferredEnergyState(candidate: EnergyState, current: EnergyState): boolean;

export declare function isPresenceVisible(presence: EnergyPresence): boolean;

export declare function isSessionExpired(session: FocusSession, now?: number): boolean;

export declare function isUnproducedState(state: Pick<EnergyState, 'timestamp' | 'origin'>): boolean;

export declare function mapToNearestDiscreteLevel<TLevel extends number>(value: number, levels: readonly TLevel[], fallback: TLevel): TLevel;

export declare function mapToNearestEnergyLevel(value: number): EnergyLevel;

export declare function presenceAtOrAbove(min: EnergyLevel, below?: EnergyPresence): EnergyPresenceMap;

const composerToolbar = presenceAtOrAbove(50)          // hidden at 25 and 0
const aiSidebar = presenceAtOrAbove(75, 'muted')       // muted below 75

export declare function presenceAtOrBelow(max: EnergyLevel, above?: EnergyPresence): EnergyPresenceMap;

export declare function resolveDeferral(presets: readonly DeferralPreset[], presetId: string, now?: Date): number | null;

export declare function resolveDemandOutcome(config: DemandAdmissionConfig, autonomy: AutonomyConfig, demand: DemandInput): DemandOutcome;

export declare function resolveEnergyPresence(presence: EnergyPresenceMap, level: EnergyLevel): EnergyPresence;

export declare function resolveNotificationOutcome(config: NotificationConfig, priority: NotificationPriority, suppressed: boolean): PublishOutcome;

export declare function sessionRemainingMs(session: FocusSession, now?: number): number;

export declare const autonomyStrategy: AdaptationStrategy<AutonomyConfig>;

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';
}>;

export declare const deferralStrategy: AdaptationStrategy<DeferralConfig>;

export declare const demandAdmissionStrategy: AdaptationStrategy<DemandAdmissionConfig>;

export declare const ENERGY_LEVEL_VALUES: ReadonlySet<number>;

export declare const ENERGY_PRESENCE_VALUES: ReadonlySet<EnergyPresence>;

export declare const ENERGY_SOURCE_VALUES: ReadonlySet<EnergySource>;

export declare const interactionForgivenessStrategy: AdaptationStrategy<InteractionForgivenessConfig>;

export declare const notificationStrategy: AdaptationStrategy<NotificationConfig>;

export declare const taskComplexityStrategy: AdaptationStrategy<TaskComplexityConfig>;

export declare const uiVisibilityStrategy: AdaptationStrategy<UIVisibilityConfig>;

export declare const UNPRODUCED_ORIGIN = "0-initial";

export declare const UNPRODUCED_TIMESTAMP = 0;

export interface AdaptationStrategy<TConfig> {
    /** Unique name for this strategy */
    name: string;
    /** Human-readable description of what this strategy does at a given level */
    describe(level: EnergyLevel): string;
    /** Compute the configuration for a given energy level */
    resolve(level: EnergyLevel): TConfig;
}

export interface AutonomyConfig {
    /**
     * Minimum confidence (0–1) an automated decision needs before acting
     * unattended. `1` admits only certainty, which in practice means rule-based
     * actions and never a judgment call.
     */
    readonly confidenceThreshold: number;
    /** Whether automation may compose novel wording, or only fill fixed templates. */
    readonly allowGeneratedContent: boolean;
    /** How many automated steps may chain before control returns to the user. */
    readonly maxUnattendedSteps: number;
}

export interface CognitiveProfile {
    readonly decisionCapacity: DecisionCapacity;
    readonly focusDuration: FocusDuration;
    readonly taskComplexity: TaskComplexity;
    readonly interruptionTolerance: InterruptionTolerance;
}

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 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;
}

export interface DemandAcknowledgment {
    readonly detail: AcknowledgmentDetail;
    /** Whether the wording may be composed, or must come from a fixed template. */
    readonly allowGeneratedContent: boolean;
}

export interface DemandAdmissionConfig {
    /**
     * Lowest originator tier admitted live. Mirrors the notification gate's
     * `priorityThreshold`: `all` admits everyone, `none` admits no one.
     */
    readonly originatorThreshold: 'all' | 'known' | 'exempt' | 'none';
    /** Whether demand held back from the user is acknowledged to its originator. */
    readonly acknowledge: boolean;
    /** Ceiling on acknowledgment detail at this level. */
    readonly acknowledgmentDetail: AcknowledgmentDetail;
}

export interface DemandInput {
    readonly originatorTier: OriginatorTier;
    /**
     * Whether this demand asks something of the user. Informational mail - a
     * receipt, a newsletter, a build notification - is not this policy's
     * business and passes through untouched.
     */
    readonly bearsObligation: boolean;
    /**
     * Confidence (0–1) that the two classifications above are right. A
     * deterministic rule reports `1`; an LLM classifier reports what it reports.
     * Below the level's autonomy threshold, the demand is captured silently
     * rather than risking a wrong automated action on the user's worst day.
     * Defaults to `1`, so a caller with no classifier gets rule-based behavior.
     */
    readonly confidence?: number;
}

export interface DemandOutcome {
    readonly admission: DemandAdmission;
    /** The acknowledgment to send. Null unless `admission` is `acknowledge`. */
    readonly acknowledgment: DemandAcknowledgment | null;
    readonly reason: DemandOutcomeReason;
}

export interface EnergyClock {
    now(): number;
}

export interface EnergyEngine {
    /**
     * Begin hydration and cross-context observation. Idempotent, and a no-op on
     * a disposed engine. Only needed when the engine was created with
     * `autoStart: false`.
     */
    start(): void;
    /** Get current energy state */
    getState(): EnergyState;
    /** Set energy level with optional source */
    setLevel(level: EnergyLevel, source?: EnergySource): void;
    /** Cycle to next energy level */
    cycleLevel(): void;
    /** Subscribe to state changes. Returns unsubscribe function. */
    subscribe(listener: EnergyChangeListener): () => void;
    /** Resolve a strategy against current energy state */
    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.
     * 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;
}

export interface EnergyEngineOptions {
    initialLevel?: EnergyLevel;
    persistence?: EnergyPersistence;
    onChange?: EnergyChangeListener;
    /** Called when a persistence attempt fails before the engine schedules a retry. */
    onPersistenceError?: (error: unknown, state: EnergyState) => void;
    /** Deterministic time source for tests/simulations */
    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;
    /**
     * Whether construction immediately hydrates from persistence and subscribes
     * to cross-context updates. Default: true.
     *
     * Pass false when the engine is constructed somewhere that may never be
     * committed - a React render, most notably - and call `start()` from a
     * lifecycle that only runs for trees React kept. Without this, a discarded
     * render leaves an engine nobody will ever dispose, holding a live
     * cross-context observer (a `storage` listener, for the localStorage
     * adapter) for the lifetime of the page.
     */
    autoStart?: boolean;
}

export interface EnergyLevelDefinition {
    readonly value: EnergyLevel;
    readonly key: string;
    readonly label: string;
    readonly description: string;
    readonly cognitiveProfile: CognitiveProfile;
}

export interface EnergyMetrics {
    /** Milliseconds since this state was set */
    readonly stateAgeMs: number;
    /** Rounded minutes since this state was set */
    readonly stateAgeMinutes: number;
    /** Suggested focused-work window length */
    readonly expectedProductivityWindowMinutes: number;
    /** Suggested break cadence for the current level. 0 means no breaks are suggested (rest is already a break). */
    readonly suggestedBreakIntervalMinutes: number;
    /** Recommended task complexity based on cognitive profile */
    readonly recommendedTaskComplexity: TaskComplexity;
    /**
     * Heuristic signal for maintainability of this state.
     * True only for mid-range levels (25/50/75): peak (100) is a burst state
     * that depletes rather than holds, and rest (0) is recovery, not a working
     * state to maintain. Both extremes report false.
     */
    readonly sustainable: boolean;
    /** Optional guidance for recovery horizon */
    readonly recoveryHintMinutes?: number;
}

export interface EnergyNotification {
    readonly priority: NotificationPriority;
    readonly payload: unknown;
    /** When the intent was published (epoch ms, gate clock) */
    readonly createdAt: number;
}

export interface EnergyPersistence {
    load(): Promise<EnergyState | null>;
    save(state: EnergyState): Promise<void>;
    /**
     * Optional observer for externally persisted state updates (cross-tab, worker, etc.)
     */
    observe?(onState: (state: EnergyState) => void): () => void;
}

export interface EnergyState {
    /** Current cognitive capacity */
    readonly level: EnergyLevel;
    /** When this state was set (epoch ms) */
    readonly timestamp: number;
    /** How this state was determined */
    readonly source: EnergySource;
    /** Logical sequence for writes sharing the same timestamp */
    readonly revision: number;
    /** Stable identity of the engine/context that produced this state */
    readonly origin: string;
}

export interface ExternalLevelCompatibility<TExternal extends number> {
    levels: readonly TExternal[];
    fallbackLevel: TExternal;
    fallbackEnergyLevel: EnergyLevel;
    toEnergyLevel: (externalLevel: TExternal | number) => EnergyLevel;
    fromEnergyLevel: (level: EnergyLevel) => TExternal;
    cycleExternalLevel: (current: TExternal | number) => TExternal;
    cycleMappedEnergyLevel: (current: TExternal | number) => EnergyLevel;
}

export interface ExternalLevelCompatibilityOptions<TExternal extends number> {
    /**
     * External level cycle order (e.g. [100, 66, 33, 0]).
     */
    levels: readonly TExternal[];
    /**
     * Mapping from external level values to native package levels.
     */
    toEnergyLevel: Readonly<Record<TExternal, EnergyLevel>>;
    /**
     * Fallback external level when input is unknown.
     */
    fallbackLevel: TExternal;
    /**
     * Fallback native level when mapping is invalid or missing.
     * Defaults to the mapped value of fallbackLevel.
     */
    fallbackEnergyLevel?: EnergyLevel;
}

export interface FocusSession {
    /** When the session started (epoch ms) */
    readonly startedAt: number;
    /** When the session ends (epoch ms). Sessions are always bounded. */
    readonly endsAt: number;
    /** Break nudge cadence in ms. 0 = no break nudges. */
    readonly breakIntervalMs: number;
}

export interface FocusSessionController {
    /** Start a session (replacing any active one, which is stopped first). */
    start(options?: StartFocusSessionOptions): FocusSession;
    /** End the active session early. No-op when idle. */
    stop(): void;
    getSession(): FocusSession | null;
    /** Milliseconds left in the active session (0 when idle) */
    remainingMs(): number;
    /** Subscribe to session lifecycle events. Returns unsubscribe function. */
    subscribe(listener: FocusSessionListener): () => void;
    /** Stop any active session and release resources */
    dispose(): void;
}

export interface FocusSessionControllerOptions {
    /**
     * Engine used for energy-aware defaults: session length from the level's
     * expected productivity window, break cadence from the task-complexity
     * strategy. Optional - without it, defaults are 25 minutes / no breaks.
     */
    engine?: EnergyEngine;
    /**
     * Suppression target (typically a NotificationGate). Suppressed on start,
     * released on stop/end/dispose - the controller owns the flag for the
     * session's lifetime, so it can never be left stuck on.
     */
    gate?: FocusSuppressible;
    /** Deterministic time source for tests/simulations */
    clock?: EnergyEngineOptions['clock'];
    /** Deterministic timer source for tests/simulations */
    scheduler?: GateScheduler;
}

export interface FocusSuppressible {
    setSuppressed(suppressed: boolean): void;
}

export interface GateScheduler {
    setTimeout(callback: () => void, ms: number): unknown;
    clearTimeout(handle: unknown): void;
}

export interface InteractionForgivenessConfig {
    /** How long an undo affordance stays available after an action */
    readonly undoWindowMs: number;
    /** Whether destructive actions (delete, discard, overwrite) ask first */
    readonly confirmDestructive: boolean;
    /** Suggested autosave cadence for in-progress work */
    readonly autosaveIntervalMs: number;
}

export interface NotificationChannels {
    readonly visual: boolean;
    readonly sound: boolean;
    readonly vibration: boolean;
}

export interface NotificationConfig {
    /** Allow visual notifications (badges, toasts) */
    readonly allowVisual: boolean;
    /** Allow audio notifications */
    readonly allowSound: boolean;
    /** Allow haptic feedback */
    readonly allowVibration: boolean;
    /** Minimum ms between batched notifications (0 = immediate) */
    readonly batchInterval: number;
    /** Minimum priority to show */
    readonly priorityThreshold: 'all' | 'high' | 'critical' | 'none';
}

export interface NotificationDelivery {
    readonly notifications: readonly EnergyNotification[];
    readonly reason: NotificationDeliveryReason;
    readonly channels: NotificationChannels;
    readonly level: EnergyLevel;
}

export interface NotificationGate {
    /** Publish a notification intent. Returns what the gate did with it. */
    publish(input: {
        priority?: NotificationPriority;
        payload?: unknown;
    }): PublishOutcome;
    /**
     * Hard-suppress delivery (e.g. during a focus session). While suppressed,
     * every publish defers; lifting suppression releases the deferred queue.
     */
    setSuppressed(suppressed: boolean): void;
    isSuppressed(): boolean;
    /** Counts of undelivered notifications currently held by the gate */
    pendingCount(): {
        batched: number;
        deferred: number;
    };
    /** Deliver the open batch now and release any deferred items that qualify */
    flush(): void;
    /**
     * Release resources. Pending notifications are delivered as a final
     * 'released' delivery first - a disposed gate never swallows intents.
     */
    dispose(): void;
}

export interface NotificationGateOptions {
    /** Delivery sink. Called with everything the gate decides to surface. */
    onDeliver(delivery: NotificationDelivery): void;
    /** Strategy resolving level -> NotificationConfig. Default: `notificationStrategy`. */
    strategy?: AdaptationStrategy<NotificationConfig>;
    /** Deterministic time source for tests/simulations */
    clock?: EnergyEngineOptions['clock'];
    /** Deterministic timer source for tests/simulations */
    scheduler?: GateScheduler;
}

export interface StartFocusSessionOptions {
    /** Session length. Default: engine's expected productivity window, else 25. */
    durationMinutes?: number;
    /** Break nudge cadence. 0 disables. Default: engine's task-complexity guidance. */
    breakEveryMinutes?: number;
}

export interface TaskComplexityConfig {
    /** Maximum task complexity to surface */
    readonly maxComplexity: TaskComplexity;
    /** Whether to proactively suggest breaks */
    readonly suggestBreaks: boolean;
    /** Minutes between break suggestions (when enabled) */
    readonly breakIntervalMinutes: number;
}

export interface UIVisibilityConfig {
    readonly sidebar: boolean;
    readonly tabBar: boolean;
    readonly statusBar: boolean;
    readonly toolbar: boolean;
    readonly chromeOpacity: number;
    readonly chromeOpacityHover: number;
    readonly contentMaxWidth: string;
    readonly contentFontScale: number;
    readonly readOnlyCursor: boolean;
}

export type AcknowledgmentDetail = 'full' | 'brief' | 'minimal';

export type DecisionCapacity = 'high' | 'moderate' | 'low' | 'minimal' | 'none';

export type DemandAdmission = 'live' | 'acknowledge' | 'silent';

export type DemandOutcomeReason = 'exempt-originator' | 'tier-admitted' | 'no-obligation' | 'acknowledgment-disabled' | 'below-confidence' | 'acknowledged';

export type EnergyChangeListener = (state: EnergyState, prev: EnergyState) => void;

export type EnergyLevel = 0 | 25 | 50 | 75 | 100;

export type EnergyPresence = 'visible' | 'muted' | 'hidden';

export type EnergyPresenceMap = Readonly<Record<EnergyLevel, EnergyPresence>>;

export type EnergyPresenceSpec = Partial<Record<EnergyLevel, EnergyPresence>> & {
    default?: EnergyPresence;
};

export type EnergySource = 'manual' | 'scheduled' | 'inferred';

export type FocusDuration = 'extended' | 'moderate' | 'short' | 'minimal' | 'none';

export type FocusSessionEvent = 'start' | 'break' | 'end' | 'stop';

export type FocusSessionListener = (event: FocusSessionEvent, session: FocusSession) => void;

export type InterruptionTolerance = 'high' | 'moderate' | 'low' | 'minimal' | 'none';

export type NotificationDeliveryReason = 'immediate' | 'batch' | 'released';

export type NotificationPriority = 'normal' | 'high' | 'critical';

export type OriginatorTier = 'exempt' | 'known' | 'unknown';

export type PublishOutcome = 'delivered' | 'batched' | 'deferred';

export type TaskComplexity = 'complex' | 'moderate' | 'routine' | 'simple' | 'consumption';