model

type APIError struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id"`
}

type APIErrorResponse struct {
	Error APIError `json:"error"`
}

type AgentConfig struct {
	Debug AgentDebugConfig `json:"debug"`
	// LatticeIdentityUUID is the server-minted, stable node identity used by
	// line discovery metadata and cross-node line graph resolution. Empty means
	// the server has not minted one yet; old agents ignore this field.
	LatticeIdentityUUID string `json:"lattice_identity_uuid,omitempty"`
	// TerminalTransport is the server's per-node override for the agent terminal
	// transport: "poll" or "stream". Empty means "no override" — the agent keeps
	// its startup -terminal-transport / LATTICE_TERMINAL_TRANSPORT value. This is
	// the rollout lever for promoting streaming per node without a redeploy; it
	// affects only sessions opened after the change, never in-flight ones.
	TerminalTransport string `json:"terminal_transport,omitempty"`
	// IPConfig is the server's per-node override for public-IP discovery. nil
	// means "no override" — the agent keeps its startup -ip-mode/-ip-resolvers
	// flags. Old agents that do not know this field ignore it safely.
	IPConfig *NodeIPConfig `json:"ip_config,omitempty"`
}

type AgentDebugBatch struct {
	NodeID     string    `json:"node_id"`
	Lines      []string  `json:"lines"`
	CapturedAt time.Time `json:"captured_at"`
}

type AgentDebugConfig struct {
	Enabled       bool `json:"enabled"`
	Collect       bool `json:"collect"`
	MaxLineBytes  int  `json:"max_line_bytes,omitempty"`
	MaxBatchLines int  `json:"max_batch_lines,omitempty"`
}

type AgentDebugPolicy struct {
	Enabled   bool      `json:"enabled"`
	Collect   bool      `json:"collect"`
	UpdatedAt time.Time `json:"updated_at,omitempty"`
}

type AgentLaunchConfig struct {
	AllowExec             bool   `json:"allow_exec"`
	AllowRootExec         bool   `json:"allow_root_exec"`
	NoExec                bool   `json:"no_exec"`
	AllowTerminal         bool   `json:"allow_terminal"`
	TerminalTransport     string `json:"terminal_transport,omitempty"`
	SSHAlerts             bool   `json:"ssh_alerts"`
	SingBoxDiscover       bool   `json:"singbox_discover"`
	SingBoxBin            string `json:"singbox_bin,omitempty"`
	ProxyUsageFile        string `json:"proxy_usage_file,omitempty"`
	ProxyUsageURL         string `json:"proxy_usage_url,omitempty"`
	ProxyUsageXrayAPI     string `json:"proxy_usage_xray_api,omitempty"`
	ProxyUsageXrayBin     string `json:"proxy_usage_xray_bin,omitempty"`
	ProxyUsageXrayPattern string `json:"proxy_usage_xray_pattern,omitempty"`
	// SingBoxStatsAPI is the loopback host:port of the sing-box experimental
	// stats API (ADR-004); empty disables the singbox-stats collector.
	SingBoxStatsAPI string    `json:"singbox_stats_api,omitempty"`
	UpdatedAt       time.Time `json:"updated_at,omitempty"`
}

type AgentUpdatePolicy struct {
	NodeID             string    `json:"node_id"`
	Enabled            bool      `json:"enabled"`
	AutoPlan           bool      `json:"auto_plan"`
	TargetVersion      string    `json:"target_version"`
	BinaryURL          string    `json:"binary_url"`
	SHA256             string    `json:"sha256"`
	InstallPath        string    `json:"install_path"`
	ServiceName        string    `json:"service_name"`
	LastPlannedVersion string    `json:"last_planned_version,omitempty"`
	LastPlannedAt      time.Time `json:"last_planned_at,omitempty"`
	LastAppliedVersion string    `json:"last_applied_version,omitempty"`
	LastAppliedAt      time.Time `json:"last_applied_at,omitempty"`
	LastError          string    `json:"last_error,omitempty"`
	CreatedAt          time.Time `json:"created_at"`
	UpdatedAt          time.Time `json:"updated_at"`
}

type Approval struct {
	ID         string    `json:"id"`
	NodeID     string    `json:"node_id"`
	Plugin     string    `json:"plugin"`
	Action     string    `json:"action"`
	Plan       string    `json:"plan"`
	Status     string    `json:"status"`
	Reason     string    `json:"reason,omitempty"`
	Stale      bool      `json:"stale,omitempty"`
	StaleCode  string    `json:"stale_code,omitempty"`
	ActorID    string    `json:"actor_id"`
	ApprovedBy string    `json:"approved_by,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`

	// Operation binding (spec §9.3). When a plugin's plan-effect method produces a
	// host-risk plan, the approval records the exact code and inputs that produced it,
	// so execution can refuse to run against anything that has since changed. These are
	// typed columns rather than values buried in Plan: each is compared to live state at
	// execute time, and each is what the operator's review is accountable for.
	//
	// All omitempty, so an approval that is not a plugin operation (nft, dns, agent
	// update) serializes exactly as before.
	PluginVersion  string `json:"plugin_version,omitempty"`
	ArtifactDigest string `json:"artifact_digest,omitempty"`
	Service        string `json:"service,omitempty"`
	Method         string `json:"method,omitempty"`
	// RequestSHA256 hashes the request that produced the plan. Re-planning with
	// different inputs yields a different approval; an approval cannot be replayed
	// against a request the operator never saw.
	RequestSHA256 string `json:"request_sha256,omitempty"`
	// Targets is the full node set the operation would touch. NodeID stays as the first
	// target so the existing per-node approval machinery keeps working unchanged.
	Targets []string `json:"targets,omitempty"`
}

type AuditEvent struct {
	ID            string            `json:"id"`
	At            time.Time         `json:"at"`
	ActorID       string            `json:"actor_id"`
	TokenID       string            `json:"token_id"`
	NodeID        string            `json:"node_id"`
	Action        string            `json:"action"`
	Scope         string            `json:"scope"`
	Decision      string            `json:"decision"`
	Reason        string            `json:"reason"`
	CorrelationID string            `json:"correlation_id"`
	Metadata      map[string]string `json:"metadata,omitempty"`
}

type ConnRecord struct {
	// Identity of where it happened.
	NodeID      string `json:"node_id"`
	LineUUID    string `json:"line_uuid,omitempty"`
	LineHashID  string `json:"line_hash_id,omitempty"`
	InboundTag  string `json:"inbound_tag,omitempty"`
	InboundType string `json:"inbound_type,omitempty"`

	// Identity of who. UserName is what sing-box logged; UserID is the Lattice
	// user it was reversed to, empty unless UserKind is managed.
	UserName string `json:"user_name,omitempty"`
	UserID   string `json:"user_id,omitempty"`
	UserKind string `json:"user_kind,omitempty"`

	// The connection itself. LogID is sing-box's per-connection id: uint32 from
	// rand, unique enough within a process-lifetime window but NOT globally, so
	// it is a join key only together with NodeID and CoreGeneration.
	LogID   uint32 `json:"log_id"`
	Network string `json:"network,omitempty"` // tcp | udp
	SrcIP   string `json:"src_ip,omitempty"`
	SrcPort int    `json:"src_port,omitempty"`
	DstHost string `json:"dst_host,omitempty"` // as logged: hostname or ip
	DstIP   string `json:"dst_ip,omitempty"`   // resolved, when DNS lines were seen
	DstPort int    `json:"dst_port,omitempty"`

	// What the router decided.
	SniffedProtocol string `json:"sniffed_protocol,omitempty"`
	SniffedDomain   string `json:"sniffed_domain,omitempty"`
	RuleIndex       int    `json:"rule_index,omitempty"`
	RuleText        string `json:"rule_text,omitempty"`
	OutboundTag     string `json:"outbound_tag,omitempty"`
	OutboundType    string `json:"outbound_type,omitempty"`
	ChainEdgeUUID   string `json:"chain_edge_uuid,omitempty"`

	// Lifecycle.
	StartedAt time.Time `json:"started_at"`
	EndedAt   time.Time `json:"ended_at,omitzero"`
	// DurationMS comes from sing-box's own elapsed counter on the final line,
	// which is more trustworthy than subtracting two agent-side timestamps.
	DurationMS int64 `json:"duration_ms,omitempty"`
	// Open marks a periodic snapshot of a still-running connection. Snapshots
	// replace each other; only the final record has Open false.
	Open bool `json:"open,omitempty"`

	// Bytes, and whether they were ever actually measured. A short connection
	// dies between /connections samples and is never counted: BytesKnown false
	// means "we did not see", not "zero".
	Upload     int64 `json:"upload,omitempty"`
	Download   int64 `json:"download,omitempty"`
	BytesKnown bool  `json:"bytes_known,omitempty"`

	// How it ended, and whether it looked stuck. StalledAt is set when a
	// connection older than the stall floor went quiet in both directions;
	// cleared if it resumes. sing-box says nothing about a stalled TCP stream,
	// so this heuristic is the only signal there is.
	CloseReason string    `json:"close_reason,omitempty"`
	CloseError  string    `json:"close_error,omitempty"`
	StalledAt   time.Time `json:"stalled_at,omitzero"`

	// CoreGeneration changes when sing-box restarts. Records from a previous
	// generation that never closed are swept to CloseCoreRestart, and the count
	// is the blast radius of that restart.
	CoreGeneration uint64 `json:"core_generation,omitempty"`

	// SessionIDs are the trace sessions that captured this connection.
	SessionIDs []string `json:"session_ids,omitempty"`
	// HopPathID groups records stitched across machines.
	HopPathID string `json:"hop_path_id,omitempty"`
}

type ConnRecordKey struct {
	NodeID         string    `json:"node_id"`
	CoreGeneration uint64    `json:"core_generation"`
	LogID          uint32    `json:"log_id"`
	StartedAt      time.Time `json:"started_at,omitzero"`
}

type DDNSProfile struct {
	ID         string   `json:"id"`
	Name       string   `json:"name"`
	NodeID     string   `json:"node_id"`
	Provider   string   `json:"provider"`
	Domains    []string `json:"domains"`
	EnableIPv4 bool     `json:"enable_ipv4"`
	EnableIPv6 bool     `json:"enable_ipv6"`
	MaxRetries int      `json:"max_retries"`
	TTL        int      `json:"ttl"`
	// IntervalSeconds is how long the server waits between attempts for this
	// profile. A residential address wants minutes; a datacenter one that has
	// held the same IP for a year does not, and the interval is also what
	// spaces out retries when a provider is rejecting the write. Zero means the
	// server default.
	IntervalSeconds int `json:"interval_seconds,omitempty"`

	// Cloudflare provider
	CFAPIToken string `json:"cf_api_token,omitempty"`

	// Webhook provider. Body/URL support the templates #ip#, #domain#, #type#.
	WebhookURL     string `json:"webhook_url,omitempty"`
	WebhookMethod  string `json:"webhook_method,omitempty"`
	WebhookBody    string `json:"webhook_body,omitempty"`
	WebhookHeaders string `json:"webhook_headers,omitempty"`

	// Status (updated by the server after each run).
	LastIPv4  string    `json:"last_ipv4,omitempty"`
	LastIPv6  string    `json:"last_ipv6,omitempty"`
	LastRunAt time.Time `json:"last_run_at,omitempty"`
	LastError string    `json:"last_error,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type DNSDeployment struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	NodeID string `json:"node_id"`
	Engine string `json:"engine"`

	ListenPort int    `json:"listen_port"`
	EnableUDP  bool   `json:"enable_udp"`
	EnableTCP  bool   `json:"enable_tcp"`
	Exposure   string `json:"exposure"`

	Zones []DNSZone `json:"zones"`

	Hostname      string `json:"hostname,omitempty"`
	PublishIPv4   bool   `json:"publish_ipv4"`
	PublishIPv6   bool   `json:"publish_ipv6"`
	RecordTTL     int    `json:"record_ttl,omitempty"`
	CFAPIToken    string `json:"cf_api_token,omitempty"`
	DDNSProfileID string `json:"ddns_profile_id,omitempty"`

	Status           string    `json:"status"`
	EngineVersion    string    `json:"engine_version,omitempty"`
	LastIPv4         string    `json:"last_ipv4,omitempty"`
	LastIPv6         string    `json:"last_ipv6,omitempty"`
	LastAppliedAt    time.Time `json:"last_applied_at,omitempty"`
	LastError        string    `json:"last_error,omitempty"`
	LastPublishedAt  time.Time `json:"last_published_at,omitempty"`
	LastPublishError string    `json:"last_publish_error,omitempty"`
	Disabled         bool      `json:"disabled,omitempty"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

type DNSRecord struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Value string `json:"value"`
	TTL   int    `json:"ttl,omitempty"`
}

type DNSZone struct {
	Suffix    string      `json:"suffix"`
	Mode      string      `json:"mode"`
	Upstreams []string    `json:"upstreams,omitempty"`
	Records   []DNSRecord `json:"records,omitempty"`
}

type GeoRouting struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Hostname    string   `json:"hostname"`     // the geo apex, e.g. dns.roobli.org
	NodeIDs     []string `json:"node_ids"`     // participating targets (need NodeGeo + IP)
	DNSNodeIDs  []string `json:"dns_node_ids"` // authoritative DNS nodes (run self-host DNS)
	TTL         int      `json:"ttl,omitempty"`
	Strategy    string   `json:"strategy"`                // "geoip" | "all-healthy"
	GeoIPDBPath string   `json:"geoip_db_path,omitempty"` // GeoLite2 path on the node

	// Parent-zone NS delegation reuses the referenced DDNSProfile's CF token.
	PublishNS     bool   `json:"publish_ns,omitempty"`
	DDNSProfileID string `json:"ddns_profile_id,omitempty"`

	LastRenderedSHA string    `json:"last_rendered_sha,omitempty"`
	Status          string    `json:"status,omitempty"`
	LastAppliedAt   time.Time `json:"last_applied_at,omitempty"`
	LastDelegatedAt time.Time `json:"last_delegated_at,omitempty"`
	LastError       string    `json:"last_error,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
	UpdatedAt       time.Time `json:"updated_at"`
}

type Group struct {
	ID          string         `json:"id"`   // "grp_<ulid>"
	Name        string         `json:"name"` // unique, display
	Slug        string         `json:"slug"` // url/nft-safe, unique, immutable
	Description string         `json:"description,omitempty"`
	Color       string         `json:"color"`               // design-token name, never raw hex (CSP)
	Icon        string         `json:"icon,omitempty"`      // lucide icon name
	ParentID    string         `json:"parent_id,omitempty"` // single parent; "" = root
	Order       int            `json:"order"`               // sort weight within the parent
	Members     []string       `json:"members"`             // explicit operator-pinned node IDs
	Selector    *GroupSelector `json:"selector,omitempty"`  // dynamic smart-membership source
	// LeaderID is the operator-designated group leader. It must be an explicit
	// Member of the group (validated on upsert); empty means "no leader". This is
	// the real, first-class field that replaces the old role-name heuristic used
	// by the dashboard to mark a node as its group's leader.
	LeaderID  string    `json:"leader_id,omitempty"`
	System    bool      `json:"system,omitempty"` // built-in (e.g. "Ungrouped"); limited edits
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type GroupNetPolicy struct {
	ID           string         `json:"id"`             // "gnp_<ulid>"
	ScopeGroupID string         `json:"scope_group_id"` // applies to members of this group
	Rules        []GroupNetRule `json:"rules"`
	Enabled      bool           `json:"enabled"`
	Priority     int            `json:"priority"` // lower wins when a node is in 2+ scoped groups
	CreatedAt    time.Time      `json:"created_at"`
	UpdatedAt    time.Time      `json:"updated_at"`
}

type GroupNetRule struct {
	ID        string      `json:"id"`
	Comment   string      `json:"comment,omitempty"`
	Action    string      `json:"action"`
	Direction string      `json:"direction"`
	Protocol  string      `json:"protocol"`
	Ports     []int       `json:"ports,omitempty"`
	Remote    NetEndpoint `json:"remote"` // Kind may be NetRefGroup in addition to node|cidr|domain|any
	Disabled  bool        `json:"disabled,omitempty"`
}

type GroupSelector struct {
	MatchTagsAny   []string `json:"match_tags_any,omitempty"`
	MatchRoles     []string `json:"match_roles,omitempty"`
	MatchCountry   []string `json:"match_country,omitempty"`   // ISO-3166 alpha-2 codes
	MatchContinent []string `json:"match_continent,omitempty"` // AS/EU/NA/SA/AF/OC/AN
}

type GuardInterface struct {
	Name      string   `json:"name"`
	Addresses []string `json:"addresses,omitempty"`
	Up        bool     `json:"up,omitempty"`
}

type GuardListener struct {
	Protocol string `json:"protocol"` // tcp | udp
	Port     int    `json:"port"`
	Address  string `json:"address,omitempty"`
	Process  string `json:"process,omitempty"`
}

type GuardNodeReality struct {
	NodeID        string           `json:"node_id"`
	Listeners     []GuardListener  `json:"listeners,omitempty"`
	Interfaces    []GuardInterface `json:"interfaces,omitempty"`
	ManagedSHA    string           `json:"managed_sha,omitempty"`
	ForeignTables []string         `json:"foreign_tables,omitempty"`
	NFTVersion    string           `json:"nft_version,omitempty"`
	CollectedAt   time.Time        `json:"collected_at"`
}

type GuardPortRange struct {
	From int `json:"from"`
	To   int `json:"to"`
}

type GuardRule struct {
	ID        string           `json:"id"`
	Comment   string           `json:"comment,omitempty"`
	Action    string           `json:"action"`    // allow | deny
	Direction string           `json:"direction"` // ingress | egress
	Protocol  string           `json:"protocol"`  // tcp | udp | icmp | icmpv6 | any
	Ports     []GuardPortRange `json:"ports,omitempty"`
	Remote    NetEndpoint      `json:"remote"` // Kind may additionally be NetRefZone
	Log       bool             `json:"log,omitempty"`
	Disabled  bool             `json:"disabled,omitempty"`
}

type GuardZone struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	Builtin     bool      `json:"builtin,omitempty"`
	Interfaces  []string  `json:"interfaces,omitempty"`
	CIDRs       []string  `json:"cidrs,omitempty"`
	Description string    `json:"description,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type HopPath struct {
	ID         string `json:"id"`
	Confidence string `json:"confidence"`
	// RecordKeys are (node_id, core_generation, log_id) triples in hop order.
	RecordKeys []ConnRecordKey `json:"record_keys"`
	// Candidates is populated only when Confidence is ambiguous, so the operator
	// sees what the stitcher could not choose between rather than a guess.
	Candidates []ConnRecordKey `json:"candidates,omitempty"`
}

type HostFacts struct {
	Hostname        string    `json:"hostname,omitempty"`
	OS              string    `json:"os,omitempty"`
	Platform        string    `json:"platform,omitempty"`
	PlatformVersion string    `json:"platform_version,omitempty"`
	KernelVersion   string    `json:"kernel_version,omitempty"`
	Arch            string    `json:"arch,omitempty"`
	CPUCores        int       `json:"cpu_cores,omitempty"`
	CPUModel        string    `json:"cpu_model,omitempty"`
	MemoryTotal     uint64    `json:"memory_total,omitempty"`
	SwapTotal       uint64    `json:"swap_total,omitempty"`
	Virtualization  string    `json:"virtualization,omitempty"`
	BootTime        time.Time `json:"boot_time,omitempty"`
	ReportedAt      time.Time `json:"reported_at,omitempty"`
}

type KVEntry struct {
	Bucket    string    `json:"bucket"`
	Key       string    `json:"key"`
	Value     string    `json:"value"`
	UpdatedAt time.Time `json:"updated_at"`
}

type LogBatch struct {
	SourceID   string    `json:"source_id"`
	Path       string    `json:"path"`      // echoed for server cross-check vs the source record
	RotID      string    `json:"rot_id"`    // opaque per-file-incarnation id (inode/ctime)
	FirstOff   uint64    `json:"first_off"` // offset before the first line in this batch
	LastOff    uint64    `json:"last_off"`  // offset after the last line (== agent checkpoint)
	Dropped    uint64    `json:"dropped"`   // lines the agent dropped (backpressure) since last batch
	Lines      []string  `json:"lines"`     // raw lines, ordered, no trailing newline
	CapturedAt time.Time `json:"captured_at"`
}

type LogLine struct {
	SourceID  string    `json:"source_id"`
	NodeID    string    `json:"node_id"`
	Path      string    `json:"path"`
	Seq       uint64    `json:"seq"`
	Offset    uint64    `json:"offset"`
	At        time.Time `json:"at"`
	Line      string    `json:"line"`
	Truncated bool      `json:"truncated,omitempty"`
}

type LogSource struct {
	ID            string    `json:"id"`
	Name          string    `json:"name"`
	NodeID        string    `json:"node_id"`
	Path          string    `json:"path"`
	Enabled       bool      `json:"enabled"`
	MaxLineBytes  int       `json:"max_line_bytes"`  // truncate longer lines (server default 16384)
	MaxBatchLines int       `json:"max_batch_lines"` // agent batch cap (server default 500)
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

type MachineProfile struct {
	ID     string `json:"id"`
	NodeID string `json:"node_id"`
	Label  string `json:"label,omitempty"`

	Vendor     string `json:"vendor,omitempty"`
	ConsoleURL string `json:"console_url,omitempty"`
	DetailURL  string `json:"detail_url,omitempty"`
	Region     string `json:"region,omitempty"`
	Notes      string `json:"notes,omitempty"`

	PriceCents int64  `json:"price_cents,omitempty"`
	Currency   string `json:"currency,omitempty"`

	PurchasedAt  time.Time `json:"purchased_at,omitempty"`
	RenewalCycle string    `json:"renewal_cycle,omitempty"`
	CycleDays    int       `json:"cycle_days,omitempty"`
	NextRenewal  time.Time `json:"next_renewal,omitempty"`
	AutoRoll     bool      `json:"auto_roll"`

	RemindDaysBefore []int  `json:"remind_days_before,omitempty"`
	RemindersEnabled bool   `json:"reminders_enabled"`
	LastRemindedKey  string `json:"last_reminded_key,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type MachineVendor struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	URL         string    `json:"url,omitempty"`
	LogoURL     string    `json:"logo_url,omitempty"`
	Description string    `json:"description,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type Metrics struct {
	CPUPercent  float64 `json:"cpu_percent"`
	Load1       float64 `json:"load1"`
	Load5       float64 `json:"load5"`
	Load15      float64 `json:"load15"`
	MemoryUsed  uint64  `json:"memory_used"`
	MemoryTotal uint64  `json:"memory_total"`
	DiskUsed    uint64  `json:"disk_used"`
	DiskTotal   uint64  `json:"disk_total"`
	NetRxBytes  uint64  `json:"net_rx_bytes"`
	NetTxBytes  uint64  `json:"net_tx_bytes"`
	// NetRxSpeed / NetTxSpeed are bytes-per-second rates the agent derives from
	// the delta of the cumulative byte counters between two metrics cycles. The
	// first cycle after agent start (no prior sample) and any counter reset both
	// report 0. Dashboards read these for live bandwidth; the cumulative
	// NetRxBytes/NetTxBytes remain the source of truth.
	NetRxSpeed    float64   `json:"net_rx_speed"`
	NetTxSpeed    float64   `json:"net_tx_speed"`
	UptimeSeconds uint64    `json:"uptime_seconds"`
	CollectedAt   time.Time `json:"collected_at"`
}

type Monitor struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	Type        string    `json:"type"`
	Target      string    `json:"target"`
	IntervalSec int       `json:"interval_sec"`
	TimeoutSec  int       `json:"timeout_sec"`
	AssignAll   bool      `json:"assign_all"`
	NodeIDs     []string  `json:"node_ids,omitempty"`
	Enabled     bool      `json:"enabled"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type MonitorResult struct {
	MonitorID string    `json:"monitor_id"`
	NodeID    string    `json:"node_id"`
	At        time.Time `json:"at"`
	Success   bool      `json:"success"`
	LatencyMs float64   `json:"latency_ms"`
	Error     string    `json:"error,omitempty"`
}

type NFTInputs struct {
	ID     string `json:"id"`
	NodeID string `json:"node_id"`

	InterfaceName string `json:"interface_name,omitempty"`
	WireGuardCIDR string `json:"wireguard_cidr,omitempty"`

	PublicTCP    []int `json:"public_tcp,omitempty"`
	PublicUDP    []int `json:"public_udp,omitempty"`
	WireGuardTCP []int `json:"wireguard_tcp,omitempty"`
	WireGuardUDP []int `json:"wireguard_udp,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type NetEndpoint struct {
	Kind    string `json:"kind"`
	NodeID  string `json:"node_id,omitempty"`
	CIDR    string `json:"cidr,omitempty"`
	Domain  string `json:"domain,omitempty"`
	GroupID string `json:"group_id,omitempty"` // set when Kind == NetRefGroup; resolved to node refs before compile
	ZoneID  string `json:"zone_id,omitempty"`  // set when Kind == NetRefZone; resolved to iface/CIDR matches before compile
}

type NetPolicy struct {
	ID           string    `json:"id"`
	TargetNodeID string    `json:"target_node_id"`
	Rules        []NetRule `json:"rules"`
	Enabled      bool      `json:"enabled"`
	// GroupDerived marks a per-node policy materialized from one or more
	// GroupNetPolicy documents (server-side expansion). Manually-authored
	// per-node policies leave it false. Materialization refuses to overwrite a
	// manual policy, so the two authoring lanes never silently clobber.
	GroupDerived  bool      `json:"group_derived,omitempty"`
	LastPlanSHA   string    `json:"last_plan_sha,omitempty"`
	LastAppliedAt time.Time `json:"last_applied_at,omitempty"`
	LastError     string    `json:"last_error,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

type NetRule struct {
	ID        string      `json:"id"`
	Comment   string      `json:"comment,omitempty"`
	Action    string      `json:"action"`
	Direction string      `json:"direction"`
	Protocol  string      `json:"protocol"`
	Ports     []int       `json:"ports,omitempty"`
	Remote    NetEndpoint `json:"remote"`
	Disabled  bool        `json:"disabled,omitempty"`
}

type Node struct {
	ID                  string   `json:"id"`
	LatticeIdentityUUID string   `json:"lattice_identity_uuid,omitempty"`
	Name                string   `json:"name"`
	Comment             string   `json:"comment,omitempty"`
	TokenHash           string   `json:"token_hash"`
	Tags                []string `json:"tags"`
	Role                string   `json:"role"`
	// Inventory is operator-registered provenance/quality metadata (dashboard
	// fleet inventory). Operator-owned; agents never report or overwrite it.
	Inventory          *NodeInventory `json:"inventory,omitempty"`
	WireGuardIP        string         `json:"wireguard_ip"`
	WireGuardPublicKey string         `json:"wireguard_public_key,omitempty"`
	WireGuardEndpoint  string         `json:"wireguard_endpoint,omitempty"`
	WireGuardPort      int            `json:"wireguard_port,omitempty"`
	PublicIP           string         `json:"public_ip"`
	PublicIPv6         string         `json:"public_ipv6,omitempty"`
	// InternalIP / InternalIPv6 are the node's LAN/primary-interface addresses,
	// reported by the agent. Informational (not geocoded); private ranges allowed.
	InternalIP   string `json:"internal_ip,omitempty"`
	InternalIPv6 string `json:"internal_ipv6,omitempty"`
	AgentVersion string `json:"agent_version"`
	Online       bool   `json:"online"`
	Disabled     bool   `json:"disabled,omitempty"`
	// AgentSourceAllowlist optionally restricts node-agent bearer-token use to
	// exact source IPs or CIDR prefixes as resolved by the server's client-IP
	// trust policy. Empty means no source-address restriction.
	AgentSourceAllowlist []string `json:"agent_source_allowlist,omitempty"`
	// TokenLastUsedAt is coarse lifecycle telemetry for the node credential. It
	// is updated only after successful bearer-token authentication and may be
	// write-throttled by the server to avoid heartbeat write amplification.
	TokenLastUsedAt time.Time        `json:"token_last_used_at,omitempty"`
	LastSeen        time.Time        `json:"last_seen"`
	Metrics         Metrics          `json:"metrics"`
	HostFacts       HostFacts        `json:"host_facts"`
	Geo             *NodeGeo         `json:"geo,omitempty"`
	AgentDebug      AgentDebugPolicy `json:"agent_debug"`
	// Trace is this node's sing-box trace collection policy. It sits beside
	// AgentDebug rather than in its own map because it is node behaviour, not a
	// separate resource: it is audited but never goes through the approval
	// chain, since it changes what the agent subscribes to and never touches
	// the node's own configuration.
	Trace TracePolicy `json:"trace"`
	// AgentLaunch is the last operator-authored installer/startup profile used
	// to generate an enrollment or reconfigure command. It is advisory desired
	// state, not proof of the currently running process flags.
	AgentLaunch *AgentLaunchConfig `json:"agent_launch,omitempty"`
	// TerminalTransport is the operator-owned per-node terminal transport: "poll"
	// (default) or "stream". Empty is treated as the deployment default. It is the
	// rollout lever for promoting the streaming terminal one node at a time; the
	// agent reads it from its polled AgentConfig and applies it to new sessions.
	TerminalTransport string `json:"terminal_transport,omitempty"`
	// IPConfig is the operator-owned, per-node override for how the agent
	// discovers its public IPs (mirrors the agent's -ip-mode/-ip-resolvers
	// flags). nil means "no override" — the agent keeps its startup flags. It is
	// pushed down through the polled AgentConfig.
	IPConfig *NodeIPConfig `json:"ip_config,omitempty"`
	// GroupIDs is the node's resolved group memberships. It is a server-computed,
	// read-only convenience field (the union of every group whose explicit
	// Members or display Selector resolves this node); it is never authored by a
	// client and is not persisted as node intent. Tags/Role remain the underlying
	// facts that selectors read.
	GroupIDs  []string  `json:"group_ids,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type NodeGeo struct {
	Country   string    `json:"country,omitempty"`
	Region    string    `json:"region,omitempty"`
	City      string    `json:"city,omitempty"`
	Lat       float64   `json:"lat,omitempty"`
	Lon       float64   `json:"lon,omitempty"`
	IP        string    `json:"ip,omitempty"`
	ASN       int       `json:"asn,omitempty"`
	ASOrg     string    `json:"as_org,omitempty"`
	Provider  string    `json:"provider,omitempty"`
	Source    string    `json:"source,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitempty"`
}

type NodeGuardBinding struct {
	NodeID          string      `json:"node_id"`
	GroupIDs        []string    `json:"group_ids"`
	Overrides       []GuardRule `json:"overrides,omitempty"`
	ZoneIDs         []string    `json:"zone_ids,omitempty"`
	Managed         bool        `json:"managed"`
	Version         int64       `json:"version"`
	LastPlanSHA     string      `json:"last_plan_sha,omitempty"`
	LastAppliedAt   time.Time   `json:"last_applied_at,omitempty"`
	LastError       string      `json:"last_error,omitempty"`
	AppliedTableSHA string      `json:"applied_table_sha,omitempty"`
	CreatedAt       time.Time   `json:"created_at"`
	UpdatedAt       time.Time   `json:"updated_at"`
}

type NodeIPConfig struct {
	Mode         string    `json:"mode,omitempty"` // "" | auto | static | resolver | script
	StaticIPv4   string    `json:"static_ipv4,omitempty"`
	StaticIPv6   string    `json:"static_ipv6,omitempty"`
	Resolvers    []string  `json:"resolvers,omitempty"` // IP-echo URLs; empty = agent defaults
	Script       string    `json:"script,omitempty"`    // server->agent only; redact from node views
	ScriptSHA256 string    `json:"script_sha256,omitempty"`
	UpdatedAt    time.Time `json:"updated_at,omitempty"`
}

type NodeInventory struct {
	// PurityPercent is the operator-assessed IP purity score, 0-100.
	PurityPercent *int `json:"purity_percent,omitempty"`
	// Quality is a coarse grade such as "high", "medium", "low" (free-form, <=64 chars).
	Quality string `json:"quality,omitempty"`
	// Notes is free-form inventory context (<=2048 chars, matching MachineProfile.Notes).
	Notes string `json:"notes,omitempty"`
}

type NotifyChannel struct {
	ID        string            `json:"id"`
	Name      string            `json:"name"`
	Kind      string            `json:"kind"`
	Config    map[string]string `json:"config,omitempty"`
	Enabled   bool              `json:"enabled"`
	CreatedAt time.Time         `json:"created_at"`
	UpdatedAt time.Time         `json:"updated_at"`
}

type NotifyRule struct {
	ID            string    `json:"id"`
	Name          string    `json:"name"`
	EventTypes    []string  `json:"event_types,omitempty"`
	ChannelIDs    []string  `json:"channel_ids,omitempty"`
	TitleTemplate string    `json:"title_template,omitempty"`
	BodyTemplate  string    `json:"body_template,omitempty"`
	Enabled       bool      `json:"enabled"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

type OIDCIdentity struct {
	ProviderID string    `json:"provider_id"`
	Issuer     string    `json:"issuer"`
	Subject    string    `json:"subject"`
	UserID     string    `json:"user_id"`
	Email      string    `json:"email,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
}

type OIDCProvider struct {
	ID             string    `json:"id"`
	DisplayName    string    `json:"display_name"`
	Issuer         string    `json:"issuer"`
	ClientID       string    `json:"client_id"`
	ClientSecret   string    `json:"client_secret,omitempty"`
	Scopes         []string  `json:"scopes,omitempty"`
	AllowedDomains []string  `json:"allowed_domains,omitempty"`
	Enabled        bool      `json:"enabled"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

type PluginInstallation struct {
	ID             string    `json:"id"`
	Name           string    `json:"name"`
	Type           string    `json:"type"`
	Version        string    `json:"version,omitempty"`
	Entrypoint     string    `json:"entrypoint,omitempty"`
	Publisher      string    `json:"publisher,omitempty"`
	Capabilities   []string  `json:"capabilities"`
	ArtifactSHA256 string    `json:"artifact_sha256,omitempty"`
	BundlePath     string    `json:"bundle_path,omitempty"`
	Status         string    `json:"status"`
	VerifiedAt     time.Time `json:"verified_at,omitempty"`
	InstalledAt    time.Time `json:"installed_at,omitempty"`
	ActivatedAt    time.Time `json:"activated_at,omitempty"`
	DisabledAt     time.Time `json:"disabled_at,omitempty"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

type ProxyInbound struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Core     string `json:"core"`
	Protocol string `json:"protocol"`
	Listen   string `json:"listen,omitempty"`
	Port     int    `json:"port"`

	Transport string `json:"transport,omitempty"`
	Path      string `json:"path,omitempty"`
	Host      string `json:"host,omitempty"`

	Security    string   `json:"security,omitempty"`
	SNI         string   `json:"sni,omitempty"`
	ALPN        []string `json:"alpn,omitempty"`
	Fingerprint string   `json:"fingerprint,omitempty"`

	CertPath string `json:"cert_path,omitempty"`
	KeyPath  string `json:"key_path,omitempty"`

	RealityPrivateKey string   `json:"reality_private_key,omitempty"`
	RealityPublicKey  string   `json:"reality_public_key,omitempty"`
	RealityShortIDs   []string `json:"reality_short_ids,omitempty"`
	RealityDest       string   `json:"reality_dest,omitempty"`

	SSMethod string `json:"ss_method,omitempty"`

	Enabled   bool      `json:"enabled"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type ProxyNodeProfile struct {
	ID         string   `json:"id"`
	NodeID     string   `json:"node_id"`
	Core       string   `json:"core"`
	InboundIDs []string `json:"inbound_ids"`
	Hostname   string   `json:"hostname,omitempty"`
	ListenIP   string   `json:"listen_ip,omitempty"`

	ConfigPath string `json:"config_path,omitempty"`
	StatsAPI   string `json:"stats_api,omitempty"`

	// LogLevel is the sing-box log.level rendered into this node's config. It
	// governs only what lands on disk. The trace subscription level is separate
	// and independent (model.TracePolicy): sing-box emits to Clash API
	// subscribers without applying log.level, which is what lets verbosity
	// change without a restart. Empty renders the default.
	LogLevel string `json:"log_level,omitempty"`

	// ClashAPI is the loopback address of this node's sing-box Clash API, for
	// example "127.0.0.1:9090". Empty means the API is not rendered. It must be
	// a loopback address: the renderer rejects anything else, because this
	// endpoint exposes live connection data and log lines.
	ClashAPI string `json:"clash_api,omitempty"`

	// ClashAPISecret is the bearer token for ClashAPI. It is rendered into the
	// node config, which already carries user UUIDs and REALITY private keys and
	// is handled as a node-scoped secret-bearing artifact. The agent reads it
	// back out of the applied config on the node; it is never shipped to the
	// agent by any other path.
	ClashAPISecret string `json:"clash_api_secret,omitempty"`

	AppliedSHA256 string    `json:"applied_sha256,omitempty"`
	LastApplyAt   time.Time `json:"last_apply_at,omitempty"`
	LastError     string    `json:"last_error,omitempty"`

	// Usage collector health is agent-reported and server persisted for
	// operator visibility. It is not client-editable policy and must not affect
	// the server's monotonic usage accounting.
	UsageCollectorSource      string    `json:"usage_collector_source,omitempty"`
	UsageCollectorStatus      string    `json:"usage_collector_status,omitempty"`
	UsageCollectorCheckedAt   time.Time `json:"usage_collector_checked_at,omitempty"`
	UsageCollectorLastOKAt    time.Time `json:"usage_collector_last_ok_at,omitempty"`
	UsageCollectorLastError   string    `json:"usage_collector_last_error,omitempty"`
	UsageCollectorLastErrorAt time.Time `json:"usage_collector_last_error_at,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type ProxyUsageSnapshot struct {
	NodeID        string           `json:"node_id"`
	At            time.Time        `json:"at"`
	CoreUptimeSec uint64           `json:"core_uptime_sec"`
	UserBytes     map[string]int64 `json:"user_bytes"`
	// LineUserBytes optionally carries cumulative counters split by stable
	// line_hash_id and proxy user id. It is additive to UserBytes so old
	// collectors remain valid; if a collector sends only line_user_bytes, agents
	// and servers may derive user_bytes by summing per-user line counters.
	LineUserBytes map[string]map[string]int64 `json:"line_user_bytes,omitempty"`

	// Collector fields describe this collection attempt. They let the agent
	// report local collector errors without overwriting the previous accounting
	// baseline on the server.
	CollectorSource    string    `json:"collector_source,omitempty"` // file | http | future core transport
	CollectorStatus    string    `json:"collector_status,omitempty"` // ok | error
	CollectorError     string    `json:"collector_error,omitempty"`
	CollectorCheckedAt time.Time `json:"collector_checked_at,omitempty"`
}

type ProxyUser struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Enabled bool   `json:"enabled"`

	UUID     string `json:"uuid,omitempty"`
	Password string `json:"password,omitempty"`
	SubToken string `json:"sub_token,omitempty"`

	InboundIDs        []string  `json:"inbound_ids,omitempty"`
	TrafficLimitBytes int64     `json:"traffic_limit_bytes,omitempty"`
	ExpiresAt         time.Time `json:"expires_at,omitempty"`

	UsedBytes  int64     `json:"used_bytes"`
	LastSeenAt time.Time `json:"last_seen_at,omitempty"`
	Status     string    `json:"status"`

	// Server-managed notification cursors. They prevent repeated quota/expiry
	// alerts after the operator has already been notified for the current limit
	// or expiry date.
	LastQuotaNotifiedKey  string `json:"last_quota_notified_key,omitempty"`
	LastExpiryNotifiedKey string `json:"last_expiry_notified_key,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type SecurityGroup struct {
	ID          string      `json:"id"`
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Rules       []GuardRule `json:"rules"`
	Version     int64       `json:"version"`
	CreatedAt   time.Time   `json:"created_at"`
	UpdatedAt   time.Time   `json:"updated_at"`
}

type ShareSource struct {
	Kind           string `json:"kind"`
	PluginID       string `json:"plugin_id,omitempty"`
	SubscriptionID string `json:"subscription_id,omitempty"`
	ProxyUserID    string `json:"proxy_user_id,omitempty"`
}

type SingBoxInventory struct {
	NodeID      string        `json:"node_id"`
	At          time.Time     `json:"at"`
	CoreVersion string        `json:"core_version,omitempty"`
	Nodes       []SingBoxNode `json:"nodes"`
	// Network is how this node is reached: nat | direct. Declared by the node
	// itself, since whether a provider sits in front of it is not something the
	// control plane can infer from the outside.
	Network string `json:"network,omitempty"`
	// ProviderEdge is the hostname the outside world actually connects to when a
	// provider forwards into this node. It is not the node's own public host: a
	// relay elsewhere in the fleet points its outbound at the provider edge, so
	// without it a chain into a NAT node cannot be matched back to the line it
	// lands on. Declared by the node, for the same reason Network is.
	ProviderEdge string `json:"provider_edge,omitempty"`
	Status       string `json:"status,omitempty"` // ok | error
	Error        string `json:"error,omitempty"`
}

type SingBoxNode struct {
	Name             string `json:"name"`
	LineID           string `json:"line_id,omitempty"`
	LineUUID         string `json:"line_uuid,omitempty"` // design-15 D1: control-plane line identity from the sidecar
	NodeIdentityUUID string `json:"node_identity_uuid,omitempty"`
	Protocol         string `json:"protocol,omitempty"`
	Network          string `json:"network,omitempty"`
	Address          string `json:"address,omitempty"`
	Port             string `json:"port,omitempty"`
	SNI              string `json:"sni,omitempty"`
	Host             string `json:"host,omitempty"`
	ListenHost       string `json:"listen_host,omitempty"`
	// PublicPort is the port the outside world reaches this inbound on, when it
	// differs from the port sing-box listens on. A NAT node behind a provider
	// edge is the case that needs it: the box listens on 488 while the world
	// dials 50100. Empty means the listen port is also the public one.
	//
	// It comes from a node-owned endpoints file rather than from the running
	// config, because no amount of reading sing-box can reveal a mapping that
	// lives in someone else's router.
	PublicPort     string `json:"public_port,omitempty"`
	OutboundRef    string `json:"outbound_ref,omitempty"`
	OutboundServer string `json:"outbound_server,omitempty"`
	OutboundPort   string `json:"outbound_port,omitempty"`
	OutboundType   string `json:"outbound_type,omitempty"`
	// DownstreamLineUUID is the declared chain edge target (design-15 §6), read
	// from the sidecar chain block; empty when the line is single-exit or the
	// edge is only inferable from outbound host/port.
	DownstreamLineUUID string            `json:"downstream_line_uuid,omitempty"`
	UserCount          int               `json:"user_count,omitempty"`
	UserKnown          bool              `json:"user_known,omitempty"`
	Metadata           map[string]string `json:"metadata,omitempty"`
	PublicKey          string            `json:"public_key,omitempty"`
	ShareURL           string            `json:"share_url,omitempty"`
}

type StaticObject struct {
	Bucket      string    `json:"bucket"`
	Path        string    `json:"path"`
	Content     string    `json:"content"`
	ContentType string    `json:"content_type"`
	Size        int       `json:"size"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type StorageAccessToken struct {
	ID         string    `json:"id"`
	Name       string    `json:"name"`
	TokenHash  string    `json:"token_hash,omitempty"`
	Kind       string    `json:"kind"`
	Access     string    `json:"access"`
	Buckets    []string  `json:"buckets,omitempty"`
	RevokedAt  time.Time `json:"revoked_at,omitempty"`
	LastUsedAt time.Time `json:"last_used_at,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type StorageBinding struct {
	ID         string    `json:"id"`
	Kind       string    `json:"kind"`
	Bucket     string    `json:"bucket"`
	Hostname   string    `json:"hostname"`
	PathPrefix string    `json:"path_prefix,omitempty"`
	Enabled    bool      `json:"enabled"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type StorageBucket struct {
	ID               string    `json:"id"`
	Kind             string    `json:"kind"`
	Name             string    `json:"name"`
	DisplayName      string    `json:"display_name,omitempty"`
	Description      string    `json:"description,omitempty"`
	IndexDocument    string    `json:"index_document,omitempty"`
	NotFoundDocument string    `json:"not_found_document,omitempty"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

type SubscriptionShare struct {
	ID            string      `json:"id"`
	SchemaVersion int         `json:"schema_version"`
	Slug          string      `json:"slug"`
	Token         string      `json:"token"`
	Source        ShareSource `json:"source"`
	DefaultFormat string      `json:"default_format,omitempty"`
	Enabled       bool        `json:"enabled"`
	CreatedAt     time.Time   `json:"created_at"`
	UpdatedAt     time.Time   `json:"updated_at"`
	RotatedAt     *time.Time  `json:"rotated_at,omitempty"`
	ExpiresAt     *time.Time  `json:"expires_at,omitempty"`

	// Extra holds fields written by a newer schema version. It exists so a
	// rollback cannot silently delete data this version cannot interpret.
	Extra map[string]json.RawMessage `json:"-"`
}

type SubscriptionSnapshot struct {
	SchemaVersion int `json:"schema_version"`
	// PluginID and SubscriptionID together identify what this is a snapshot of.
	PluginID       string `json:"plugin_id"`
	SubscriptionID string `json:"subscription_id"`
	// Raw is the provider's response body exactly as the plugin received it.
	Raw string `json:"raw"`
	// SourceVersion identifies the exact secret-free source state used to render
	// Raw. SourceManifest is its canonical, map-free provenance document. Neither
	// field may contain credentials or rendered subscription URIs.
	SourceVersion  string          `json:"source_version,omitempty"`
	SourceManifest json.RawMessage `json:"source_manifest,omitempty"`
	// Userinfo is the provider's Subscription-Userinfo header, passed through to
	// the client so its traffic display stays truthful. Empty when the provider
	// sent none.
	Userinfo  string    `json:"userinfo,omitempty"`
	FetchedAt time.Time `json:"fetched_at"`
	// FetchError records why the most recent refresh failed while this snapshot
	// stayed in service. A snapshot with a non-empty FetchError is still served -
	// that is the point - but the operator needs to see that it is stale.
	FetchError    string    `json:"fetch_error,omitempty"`
	LastAttemptAt time.Time `json:"last_attempt_at,omitempty"`
	// Stale is explicit in v2. It is independent of FetchError so public serving
	// code never has to infer whether preserved last-good content is current.
	Stale bool `json:"stale"`
	// contains filtered or unexported fields
}

type SubscriptionSourceManifestEdge struct {
	Source              string `json:"source"`
	Target              string `json:"target"`
	Generation          uint64 `json:"generation"`
	ObservationRevision uint64 `json:"observation_revision"`
	Status              string `json:"status"`
}

type SubscriptionSourceManifestEndpoint struct {
	LineUUID    string   `json:"line_uuid"`
	NodeID      string   `json:"node_id"`
	Label       string   `json:"label"`
	Host        string   `json:"host"`
	Port        int      `json:"port"`
	SNI         string   `json:"sni"`
	Fingerprint string   `json:"fingerprint"`
	ALPN        []string `json:"alpn"`
	PublicKey   string   `json:"public_key"`
	ShortID     string   `json:"short_id"`
	Flow        string   `json:"flow"`
}

type SubscriptionSourceManifestEntry struct {
	Root     string                             `json:"root"`
	Endpoint SubscriptionSourceManifestEndpoint `json:"endpoint"`
	Path     []SubscriptionSourceManifestEdge   `json:"path"`
	Terminal SubscriptionSourceManifestTerminal `json:"terminal"`
}

type SubscriptionSourceManifestIdentity struct {
	ID         string `json:"id"`
	Generation uint64 `json:"generation"`
}

type SubscriptionSourceManifestTerminal struct {
	LineUUID            string `json:"line_uuid"`
	Generation          uint64 `json:"generation"`
	ObservationRevision uint64 `json:"observation_revision"`
	Status              string `json:"status"`
}

type SubscriptionSourceManifestV1 struct {
	Schema     string                             `json:"schema"`
	Renderer   string                             `json:"renderer"`
	Identity   SubscriptionSourceManifestIdentity `json:"identity"`
	EntryRoots []string                           `json:"entry_roots"`
	Entries    []SubscriptionSourceManifestEntry  `json:"entries"`
}

type Task struct {
	ID            string               `json:"id"`
	ApprovalID    string               `json:"approval_id,omitempty"`
	ActorID       string               `json:"actor_id"`
	TokenID       string               `json:"token_id"`
	Targets       []string             `json:"targets"`
	Interpreter   string               `json:"interpreter"`
	Script        string               `json:"script"`
	TimeoutSec    int                  `json:"timeout_sec"`
	OutputLimit   int                  `json:"output_limit"`
	Status        string               `json:"status"`
	LeaseID       string               `json:"lease_id,omitempty"`
	LeasedBy      string               `json:"leased_by,omitempty"`
	TargetLeases  map[string]TaskLease `json:"target_leases,omitempty"`
	RerunOfTaskID string               `json:"rerun_of_task_id,omitempty"`
	RerunOfNodeID string               `json:"rerun_of_node_id,omitempty"`
	CreatedAt     time.Time            `json:"created_at"`
	StartedAt     time.Time            `json:"started_at,omitempty"`
	FinishedAt    time.Time            `json:"finished_at,omitempty"`
}

type TaskLease struct {
	LeaseID   string    `json:"lease_id"`
	StartedAt time.Time `json:"started_at,omitempty"`
}

type TaskResult struct {
	TaskID     string    `json:"task_id"`
	LeaseID    string    `json:"lease_id,omitempty"`
	NodeID     string    `json:"node_id"`
	ExitCode   int       `json:"exit_code"`
	Stdout     string    `json:"stdout"`
	Stderr     string    `json:"stderr"`
	Error      string    `json:"error"`
	StartedAt  time.Time `json:"started_at"`
	FinishedAt time.Time `json:"finished_at"`
}

type TerminalEvent struct {
	Seq       int64     `json:"seq"`
	Kind      string    `json:"kind"`
	Data      string    `json:"data,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type TerminalInput struct {
	Seq       int64     `json:"seq"`
	Kind      string    `json:"kind"`
	Data      string    `json:"data,omitempty"`
	Cols      int       `json:"cols,omitempty"`
	Rows      int       `json:"rows,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type TerminalSession struct {
	ID        string    `json:"id"`
	NodeID    string    `json:"node_id"`
	ActorID   string    `json:"actor_id,omitempty"`
	TokenID   string    `json:"token_id,omitempty"`
	Shell     string    `json:"shell,omitempty"`
	Cols      int       `json:"cols,omitempty"`
	Rows      int       `json:"rows,omitempty"`
	Status    string    `json:"status"`
	Error     string    `json:"error,omitempty"`
	BytesIn   int64     `json:"bytes_in,omitempty"`
	BytesOut  int64     `json:"bytes_out,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	OpenedAt  time.Time `json:"opened_at,omitempty"`
	ClosedAt  time.Time `json:"closed_at,omitempty"`
	LastSeen  time.Time `json:"last_seen,omitempty"`
}

type Token struct {
	ID              string    `json:"id"`
	Name            string    `json:"name"`
	TokenHash       string    `json:"token_hash"`
	ActorID         string    `json:"actor_id"`
	Scopes          []string  `json:"scopes"`
	ServerAllowlist []string  `json:"server_allowlist"`
	RevokedAt       time.Time `json:"revoked_at,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
}

type TraceAgentConfig struct {
	Policy   TracePolicy         `json:"policy"`
	Sessions []TraceAgentSession `json:"sessions,omitempty"`
	// ServerTime lets the agent bound clock skew when enforcing TTLs.
	ServerTime time.Time `json:"server_time,omitzero"`
	// RawSourceID is the virtual log source that receives the node's ordinary
	// sing-box lines, the ones no capture session asked for. They go to the
	// existing bounded log store rather than the trace store, so the Logs view
	// keeps working and there is parser evidence to look at after the fact
	// instead of only assembled records. Empty means the server does not want
	// raw lines from this node.
	RawSourceID string `json:"raw_source_id,omitempty"`
}

type TraceAgentSession struct {
	ID        string     `json:"id"`
	Level     TraceLevel `json:"level"`
	ExpiresAt time.Time  `json:"expires_at"`
	// UserNames are sing-box inbound user names (u_<16hex>, or a legacy label).
	UserNames []string `json:"user_names,omitempty"`
	// InboundTags are sing-box inbound tags on THIS node.
	InboundTags []string `json:"inbound_tags,omitempty"`
	DstPatterns []string `json:"dst_patterns,omitempty"`
}

type TraceBatch struct {
	NodeID  string       `json:"node_id"`
	Records []ConnRecord `json:"records,omitempty"`
	Lines   []TraceLine  `json:"lines,omitempty"`
	// CoreGeneration and CoreStartedAt let the server detect a restart even if
	// it missed the records that the restart swept.
	CoreGeneration uint64    `json:"core_generation,omitempty"`
	CoreStartedAt  time.Time `json:"core_started_at,omitzero"`
	// Dropped counts what the agent discarded under budget since the last batch.
	Dropped uint64 `json:"dropped,omitempty"`
	// Unparsed counts lines the parser could not read. A rising number means
	// sing-box changed its format, which is the failure mode most likely to be
	// mistaken for "nothing is happening".
	Unparsed   uint64    `json:"unparsed,omitempty"`
	CapturedAt time.Time `json:"captured_at"`
}

type TraceFilter struct {
	UserIDs   []string `json:"user_ids,omitempty"`
	LineUUIDs []string `json:"line_uuids,omitempty"`
	NodeIDs   []string `json:"node_ids,omitempty"`
	// DstPatterns are case-insensitive substrings matched against the
	// destination host. Not globs: a substring is what an operator types.
	DstPatterns []string `json:"dst_patterns,omitempty"`
}

type TraceLevel string

type TraceLine struct {
	SessionID string    `json:"session_id"`
	NodeID    string    `json:"node_id"`
	Seq       uint64    `json:"seq"`
	At        time.Time `json:"at"`
	Level     string    `json:"level"`
	LogID     uint32    `json:"log_id,omitempty"`
	Tag       string    `json:"tag,omitempty"`
	Message   string    `json:"message"`
	// Raw is the payload exactly as sing-box sent it, kept so a parser bug can
	// never destroy the evidence it failed to read.
	Raw string `json:"raw,omitempty"`
}

type TraceMarker struct {
	Kind   string    `json:"kind"`
	At     time.Time `json:"at"`
	NodeID string    `json:"node_id,omitempty"`
	UserID string    `json:"user_id,omitempty"`
	Title  string    `json:"title"`
	Detail string    `json:"detail,omitempty"`
	// Count is the blast radius where one applies: connections closed by a
	// restart, nodes touched by an apply.
	Count         int    `json:"count,omitempty"`
	CorrelationID string `json:"correlation_id,omitempty"`
}

type TracePolicy struct {
	NodeID  string `json:"node_id"`
	Enabled bool   `json:"enabled"`
	// Level is the floor for this node. The agent subscribes at the max of this
	// and every running session's level.
	Level TraceLevel `json:"level"`
	// BudgetLinesPerSec caps ingest for this node. Over budget the agent drops
	// oldest and counts; the count is reported and displayed, never hidden.
	BudgetLinesPerSec int `json:"budget_lines_per_sec"`
	// ClashAPIAddr is the loopback address of the node's sing-box Clash API,
	// e.g. "127.0.0.1:9090". Never a routable address.
	ClashAPIAddr string `json:"clash_api_addr,omitempty"`
	// SecretPath is where the agent reads the Clash API secret on the node. The
	// secret itself never travels to the server and is never stored here.
	SecretPath string    `json:"secret_path,omitempty"`
	UpdatedAt  time.Time `json:"updated_at,omitzero"`

	// LastCoreGeneration and LastCoreStartedAt are the newest sing-box process
	// instance this node reported. A change is a restart, and recording it here
	// means a restart on an idle node is still visible even though it swept no
	// connections.
	LastCoreGeneration uint64    `json:"last_core_generation,omitempty"`
	LastCoreStartedAt  time.Time `json:"last_core_started_at,omitzero"`
}

type TraceSession struct {
	ID     string      `json:"id"`
	Name   string      `json:"name"`
	Filter TraceFilter `json:"filter"`
	Level  TraceLevel  `json:"level"`

	StartedAt time.Time `json:"started_at"`
	ExpiresAt time.Time `json:"expires_at"`
	EndedAt   time.Time `json:"ended_at,omitzero"`
	State     string    `json:"state"`

	StartedBy     string `json:"started_by"`
	CorrelationID string `json:"correlation_id,omitempty"`

	// Counters, reported back for display. Dropped is as load-bearing as Lines:
	// a capture that silently lost lines reads as a quiet network.
	Lines   uint64 `json:"lines"`
	Records uint64 `json:"records"`
	Dropped uint64 `json:"dropped"`
}

type TunnelIngress struct {
	Hostname string `json:"hostname"`
	Service  string `json:"service"`
	Path     string `json:"path,omitempty"`
}

type TunnelProfile struct {
	ID              string          `json:"id"`
	Name            string          `json:"name"`
	NodeID          string          `json:"node_id"`
	TunnelID        string          `json:"tunnel_id"`
	CredentialsFile string          `json:"credentials_file,omitempty"`
	Ingress         []TunnelIngress `json:"ingress"`
	CreatedAt       time.Time       `json:"created_at"`
	UpdatedAt       time.Time       `json:"updated_at"`
}

type User struct {
	ID           string   `json:"id"`
	Username     string   `json:"username"`
	PasswordHash string   `json:"password_hash"`
	Scopes       []string `json:"scopes"`
	// ServerAllowlist confines this operator to a set of nodes, exactly as the
	// same field on Token confines an API caller. Empty means every node, which
	// is what every existing account has and so preserves their access across
	// the upgrade. "*" is accepted as an explicit spelling of the same thing.
	//
	// Without this a human account could only be narrowed by scope, never by
	// node: the confinement machinery existed and was enforced everywhere, but
	// only an API token could express it.
	ServerAllowlist    []string `json:"server_allowlist,omitempty"`
	TOTPEnabled        bool     `json:"totp_enabled"`
	TOTPSecret         string   `json:"totp_secret,omitempty"`
	RecoveryCodeHashes []string `json:"recovery_code_hashes,omitempty"`
	// LastTOTPStep is the highest RFC-6238 counter accepted for this user. A
	// successful verification must present a strictly greater step, which makes
	// each code single-use and prevents replay within the validity window.
	LastTOTPStep uint64 `json:"last_totp_step,omitempty"`
	// SecurityEpoch is bumped on password change, 2FA disable, or admin revoke.
	// Sessions carry the epoch at which they were minted; a session whose epoch
	// is older than the user's current epoch is rejected, so privilege-reducing
	// events invalidate all existing sessions.
	SecurityEpoch uint64    `json:"security_epoch,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
}

type WGExternalPeer struct {
	ID           string    `json:"id"`
	NetworkID    string    `json:"network_id"`
	Name         string    `json:"name"`
	Address      string    `json:"address"`
	PublicKey    string    `json:"public_key"`
	AllowedIPs   []string  `json:"allowed_ips,omitempty"`
	LastIssuedAt time.Time `json:"last_issued_at,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
}

type WGMembership struct {
	NetworkID     string `json:"network_id"`
	NodeID        string `json:"node_id"`
	Address       string `json:"address"`
	Role          string `json:"role"` // hub | spoke | peer
	InterfaceName string `json:"interface_name,omitempty"`
	ListenPort    int    `json:"listen_port,omitempty"`
	// Endpoint is the peer dial address rendered into WireGuard configs. It must
	// be host:port, with IPv6 hosts bracketed as in net.JoinHostPort.
	Endpoint        string   `json:"endpoint,omitempty"`
	Keepalive       int      `json:"keepalive,omitempty"`
	MTU             int      `json:"mtu,omitempty"`
	ExtraAllowedIPs []string `json:"extra_allowed_ips,omitempty"`
	Version         int64    `json:"version"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type WGNetwork struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	CIDR        string   `json:"cidr"`
	Topology    string   `json:"topology"` // mesh | hub-and-spoke | custom
	ListenPort  int      `json:"listen_port,omitempty"`
	Keepalive   int      `json:"keepalive,omitempty"`
	MTU         int      `json:"mtu,omitempty"`
	DNS         []string `json:"dns,omitempty"`
	Description string   `json:"description,omitempty"`
	Version     int64    `json:"version"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type WorkerScript struct {
	ID           string    `json:"id"`
	Name         string    `json:"name"`
	Source       string    `json:"source"`
	Capabilities []string  `json:"capabilities"`
	Public       bool      `json:"public"`
	UpdatedAt    time.Time `json:"updated_at"`
}