namespace Statum {

    /**
     * One-way realtime push service for slot updates.
     *
     * {@link StateService} injects a {@link ChannelService} (the singleton
     * {@link ChannelEndpoint}) so that every state mutation auto-pushes the
     * resulting frame to any channels subscribed to that slot. The dependency is
     * deliberately one-way: a {@link ChannelService} never injects
     * {@link StateService}, so there is no DI cycle.
     *
     * The push is a no-op when no stream is subscribed to `key`, so selective
     * fan-out emerges naturally from subscriptions. The low-level
     * {@link ChannelEndpoint.push_set}/{@link ChannelEndpoint.push_clear} remain
     * callable directly for advanced cases.
     */
    public interface ChannelService : Object {

        /**
         * Pushes a `set` event carrying `frame_json` to every channel subscribed
         * to `key`. No-op when nothing is subscribed.
         */
        public abstract async void push_set(string key, string frame_json);

        /**
         * Pushes a `clear` event for `key` to every channel subscribed to it.
         * No-op when nothing is subscribed.
         */
        public abstract async void push_clear(string key);

    }

}