# Wakey

Wakey models devices discovered on a local network and the control-plane view used to wake and manage them across agents.

## Language

**Device**:
An operator-facing aggregate that represents one discovered network identity candidate.
_Avoid_: Host, machine, route

**Device Summary**:
The derived names, MACs, IPs, and presence shown on a device aggregate.
_Avoid_: Source of truth, route data

**Endpoint**:
One observed network contact point for a device, including the agent/source, optional MAC, optional IP, presence, and observation time.
_Avoid_: Raw observation, route, IP row

**Endpoint Source**:
The typed origin of an endpoint, such as neighbor data, DHCP lease data, or a hotplug hook.
_Avoid_: String kind, source label

**Observation Fact**:
Debug evidence copied from local observation inputs before it is interpreted into endpoints.
_Avoid_: Endpoint, identifier, source of truth

**Presence**:
The current reachability interpretation for a device or endpoint.
_Avoid_: Endpoint state, status

**Wake Route**:
An endpoint that has enough information and agent availability to attempt waking a device.
_Avoid_: Device, endpoint when not wakeable

**Known Device**:
A device identity manually curated by the operator.
_Avoid_: Auto-pinned device, saved observation

**Identifier**:
A manually approved MAC or IP value that links an observed device or endpoint to a known device.
_Avoid_: Observation key, route id

**Endpoint Key**:
The typed identity of endpoint evidence, based on source and optional MAC/IP.
_Avoid_: Stringly typed route id

**Agent Endpoint Key**:
An endpoint key scoped to the agent that observed it.
_Avoid_: Concatenated agent/source/MAC/IP string

**Agent**:
A fleet member that observes local network state and sends device snapshots to the control plane.
_Avoid_: Router when referring to the software actor

**Agent Host**:
The machine running an agent, including host identity and runtime metadata.
_Avoid_: Device when referring to the agent machine

**Agent Capability**:
Something an agent host can observe or do on the network.
_Avoid_: Router flag

**Terminal Capability**:
An explicitly enabled agent capability that allows the agent host to create remote PTY sessions.
_Avoid_: Command runner, implicit root access

**Terminal Session**:
One operator attachment to one PTY process hosted by an agent.
_Avoid_: Command, SSH session, stored shell

**Terminal Relay**:
The control plane's in-memory pairing of one operator terminal socket with one outbound agent terminal socket.
_Avoid_: Terminal session storage, terminal emulator

**Interface Telemetry**:
Current operational measurements for a network interface visible to an agent.
_Avoid_: Endpoint state, device presence

## Relationships

- A **Device** has zero or more **Endpoints**.
- A **Device Summary** is derived from a **Device** and its **Endpoints**.
- Local source rows are grouped into **Devices** by endpoint-derived **DeviceId**, not by exact **Endpoint Key**.
- Within one complete local snapshot, MAC+IP endpoints may absorb IP-only endpoints with the same IP; this merge is not remembered across snapshots unless the operator creates an **Identifier**.
- An **Endpoint** belongs to exactly one **Agent**.
- An **Endpoint** has one **Endpoint Key**.
- An **Agent Endpoint Key** combines an **Agent** with an **Endpoint Key**.
- An **Endpoint** may have both MAC and IP, MAC only, or IP only.
- An **Endpoint** has exactly one **Endpoint Source**.
- An **Endpoint** has one **Presence**.
- An **Endpoint** may name the network interface where it was observed.
- An **Observation Fact** may explain why an **Endpoint** exists, but does not define identity or wakeability.
- A **Wake Route** is derived from exactly one **Endpoint**.
- A **Wake Route** may carry the interface from its source **Endpoint**.
- A **Known Device** has zero or more **Identifiers**.
- An **Identifier** can link observed **Devices** or **Endpoints** to one **Known Device**.
- An **Agent** runs on one **Agent Host**.
- An **Agent Capability** describes what an **Agent Host** can observe or do.
- **Terminal Capability** is an **Agent Capability** and must be explicitly enabled before an agent can host a **Terminal Session**.
- A **Terminal Session** owns one PTY and is independent of one-shot agent commands.
- A **Terminal Relay** pairs exactly one operator socket with exactly one agent socket for a **Terminal Session**.
- **Interface Telemetry** describes an **Agent Host** interface, not a **Device Endpoint**.

## Example dialogue

> **Dev:** "This **Device** has three IPs. Which one should the UI wake?"
> **Domain expert:** "Do not infer that from the **Device** summary. Use the **Wake Routes** derived from its **Endpoints**."

## Flagged ambiguities

- "route" was used for both observed network contact points and wakeable paths — resolved: use **Endpoint** for observed contact points and **Wake Route** only when the endpoint can be used for wake.
- "device" was used for both an identity aggregate and each MAC/IP pair — resolved: use **Device** for the aggregate and **Endpoint** for each observed MAC/IP/source/state tuple.
- `Device.ips` and `Device.macs` are true summary values, but they are not authoritative for wake, freshness, or per-IP state decisions — resolved: use **Endpoint** for those decisions.
- MAC-only and IP-only observations are still **Endpoints** — resolved: **Wake Routes** require a MAC and a connected **Agent**, while IP is optional route detail.
- Endpoint-specific states such as "removed" or "stale" are not separate concepts yet — resolved: use **Presence** until a distinction appears that presence cannot express cleanly.
- Endpoint origin is not a free string — resolved: use **Endpoint Source** for domain logic and reserve raw strings for debug facts only.
- Local observation file rows map naturally to **Observation Facts** — resolved: keep them for debugging, but do not use them as the operational model.
- Offline **Endpoints** remain part of the API model — resolved: UI may collapse them from the primary view, but the API should still expose them for details, copy, and debugging.
- **Device Summary** IPs come only from concrete live-ish sources such as neighbor table rows and current DHCP lease rows — resolved: hotplug hook memory creates **Endpoints** and **Observation Facts**, but does not directly inflate summary IPs.
- Router-ness is not a boolean domain concept — resolved: model **Agent Capabilities** and **Agent Host** metadata instead.
- **Presence** ordering should treat **Unknown** as non-voting/no evidence, weaker than **Offline** — resolved: concrete offline evidence should not be overridden by unknown hook or DHCP ambiguity.
- **Device** presence is derived from all **Endpoints**, not only summary-eligible endpoints.
- Current DHCP leases are summary-eligible **Endpoints** with **Unknown** presence; they may support wake when a MAC is present, but they do not prove reachability.
- DHCP hook events, including removal, indicate **Unknown** because they describe lease churn rather than reachability.
- Neighbor table and neighbor hook events may indicate **Offline** when they report failed or removed reachability.
- **Presence** and wakeability are separate: an **Offline** endpoint may still produce a **Wake Route** if it has a MAC and a connected **Agent**.
- **Endpoint** does not store wakeability; wakeability is derived from endpoint data plus **Agent** runtime and capability context.
- Preferred **Wake Routes** are ordered by connected agent, wakeability, having an IP, presence quality, recency, then source quality.
- **Endpoint** evidence preserves source-specific rows; equivalent **Wake Routes** may ignore source when they target the same agent, MAC, and IP.
- The control plane stores **Endpoints** as structured data so fleet search, identity matching, and wake route selection do not depend on parsing opaque device JSON.
- Summary MAC/IP collections are derived from **Endpoints**; separate MAC/IP storage should be removed or represented as views rather than maintained as independent truth.
- API arrays should be domain-sorted by default; UI may sort top-level fleet rows for presentation, but route ranking and recommended route selection are backend-owned.
- The main fleet API embeds **Endpoints** in each **Device** response; a separate endpoint API is unnecessary until payload size or access patterns require it.
- The control plane stores current per-agent endpoint snapshots, not endpoint event history.
- Agent-local hook memory is retained by local last-seen age policy, not by control-plane acknowledgement; default retention is 7 days unless configured otherwise.
- Live-source **Endpoints** use snapshot time as their observed time; hook-derived **Endpoints** use the hook row's recorded last-seen time.
- **DeviceId**, **Endpoint Key**, and **Agent Endpoint Key** are typed concepts; string keys are boundary serialization only.
- **DeviceId** is derived from a device's **Endpoints**: canonical MAC if any endpoint has a MAC, otherwise canonical IP, otherwise absent.
- Hostnames are endpoint evidence/display data, not part of **Endpoint Key** identity.
- Interface names are endpoint metadata, not part of **Endpoint Key** identity; multi-segment routers may require scoped endpoint identity later if the same source/MAC/IP has different meaning on different interfaces.
- An **Endpoint Key** must contain at least one network address value: MAC, IP, or both. Facts without MAC or IP remain **Observation Facts** only.
- **Identifiers** are source-independent ownership claims over MAC or permanent IP values, not claims over endpoint sources.
- IP **Identifiers** are explicit operator claims; Wakey does not infer whether an IP is permanent, static, or reserved.
- **Terminal Sessions** are not agent commands — resolved: command dispatch remains request/result, while terminals use dedicated streaming sockets.
- **Terminal Relay** is ephemeral control-plane state — resolved: terminal bytes and scrollback are not stored or audited.
- Terminal input, output, and terminal-generated control sequences are byte streams; only lifecycle and resize operations are structured terminal protocol messages.