fleetd/bridged/src/main/java/dev/ltms/fleet/peer/PeerHandle.java

package dev.ltms.fleet.peer;

/**
 * An opaque handle returned by {@link PeerLauncher#spawn(SpawnRequest)}. The core routes on
 * {@link #id()} (the registry/routing key) and uses {@link #terminalId()} for session tracking;
 * launcher-private coordinates beyond these are reachable through the concrete implementation.
 *
 * <p>A {@link PeerHandle} is returned <em>after</em> the peer process is live — the launcher
 * has already completed subscription-guarded env/vfs setup, process start, and placement. The
 * handle is a ticket the core exchanges for the running peer, not a lazy/delayed reference.
 */
public interface PeerHandle {

    /**
     * The registry/routing key — an opaque, launcher-assigned identifier (CB-519). Multiple
     * daemon processes may run on one host, so the contract is <em>host-unique</em>, not merely
     * process-unique: the herdr-backed launcher mints a fresh UUID per spawn, and a non-herdr
     * launcher is likewise expected to return an identifier that cannot collide across processes
     * on the same host. This id is the routing key and is deliberately decoupled from any launcher
     * transport coordinate (e.g. a herdr pane id), which stays launcher-private. Guaranteed to be
     * non-null and unique among live peers on the host.
     */
    String id();

    /**
     * The transport-level session identifier used for message routing and presence tracking.
     * For the herdr launcher this is the herdr terminal UUID. A non-herdr launcher may return
     * its own analogous identifier, or {@code null} if the concept does not apply.
     */
    default String terminalId() {
        return null;
    }

    /**
     * The worker profile that spawned this peer, if the launcher resolved one. A launcher that
     * performs dynamic profile selection (e.g. CB-518 weighted placement) sets this so the
     * session registry records the actual profile rather than the requested/default one.
     *
     * @return the profile name, or {@code null} when the launcher leaves it unspecified
     */
    default String profile() {
        return null;
    }

    /**
     * The bridge's logical name for this session, as assigned at spawn
     * ({@link SpawnRequest#sessionName()}). Stable across restarts and meaningful to an operator,
     * unlike the transport identifiers above; a launch with no name leaves the peer's display
     * identity to the launcher to derive.
     *
     * @return the bridge-assigned logical session name, or {@code null} if none was assigned
     */
    default String sessionName() {
        return null;
    }

    /**
     * The peer's OWN session id — the handle that resumes this conversation later (the id a
     * later {@link Capability#SESSION_RESUME resume} spawn would pass back). Null when the adapter
     * cannot determine it — the contract for an adapter that declines
     * {@link Capability#SESSION_RESUME}; an adapter that declares that capability returns this
     * non-null for a spawn that requested session identity, because it knows the id before the
     * peer has written anything.
     *
     * <p>Deliberately not a {@code default} (CB-584, the same fix CB-571 made for
     * {@link #charterReceipt()} one method below): a decorator that forgets to override this
     * silently answers {@code null} for a question it has no basis to answer, and the gap surfaces
     * only as a resume that quietly starts a cold session, not a compile error. Every
     * implementation must answer explicitly.
     *
     * @return the peer's own session id, or {@code null} when not determinable
     */
    String agentSessionId();

    /**
     * The charter receipt (CB-571) for this peer's launch — the fingerprint of the exact charter
     * bytes it was started with. {@code null} when the launcher records none (a non-instrumented
     * adapter, or a launcher before this field); the session registry stores it so the spawn result
     * and the roster row can show an operator which charter a member actually got.
     *
     * <p>Deliberately not a {@code default}: a decorator that forgets to override this silently
     * answers {@code null} for a question it has no basis to answer, and the gap surfaces only as
     * a missing roster field, not a compile error. Every implementation must answer explicitly.
     *
     * @return the fingerprint, or {@code null} when the launcher carries none
     */
    CharterReceipt charterReceipt();
}