netdev

type AggregatedFinding struct {
	Key        string     `json:"key"` // Source or title
	Count      int        `json:"count"`
	Open       int        `json:"open"`     // active+ack
	Severity   string     `json:"severity"` // highest among members
	Devices    []string   `json:"devices"`
	Title      string     `json:"title"` // representative title
	Newest     time.Time  `json:"newest"`
	Members    []*Finding `json:"members,omitempty"` // newest first, capped
	Suppressed int        `json:"suppressed"`        // ≥2 = 此键已被误报学习降级
}

type AttackPath struct {
	ExposureDevice string           `json:"exposure_device"`
	Reason         string           `json:"reason"` // the finding that marks the exposure
	FindingID      string           `json:"finding_id,omitempty"`
	Steps          []AttackPathStep `json:"steps"`
	EndDevice      string           `json:"end_device"`
	EndRole        string           `json:"end_role,omitempty"`
	EndManaged     bool             `json:"end_managed"`
	Hops           int              `json:"hops"`
	Score          int              `json:"score"`
}

type AttackPathReport struct {
	GeneratedAt    string          `json:"generated_at"`
	Simulated      bool            `json:"simulated"` // constant true — 推演, not 实测
	EdgeSources    []string        `json:"edge_sources"`
	Nodes          int             `json:"nodes"`
	Edges          int             `json:"edges"`
	ExposurePoints []ExposurePoint `json:"exposure_points"`
	Paths          []AttackPath    `json:"paths"`
	Cuts           []CutSuggestion `json:"cut_suggestions"`
}

type AttackPathStep struct {
	From string `json:"from"`
	To   string `json:"to"`
	Via  string `json:"via"` // edge source: bastion | design | lldp | cdp
}

type Audit struct {
	Time        time.Time `json:"time"`
	Device      string    `json:"device"`
	Via         []string  `json:"via,omitempty"`
	Command     string    `json:"command"`
	Class       string    `json:"class"`  // read | write | dangerous | unknown (classifier verdict)
	Status      string    `json:"status"` // ok | device-error | refused | failure
	OutputBytes int       `json:"output_bytes,omitempty"`
	Error       string    `json:"error,omitempty"`
	// Hash chains entries (B-batch): sha256 over the previous entry's hash and
	// this entry's canonical JSON (hash field excluded). Any tampering with an
	// old line — or a line removed — breaks every later hash. Entries written
	// before the chain landed have empty hashes; the chain starts at the first
	// hashed entry.
	Hash string `json:"hash,omitempty"`
}

type AuditChainStatus struct {
	Total       int    `json:"total"`
	Chained     int    `json:"chained"`
	OK          bool   `json:"ok"`
	FirstBroken string `json:"firstBroken,omitempty"`
}

type AuditWindowStats struct {
	ByClass          map[string]int
	Read24h          int
	Write24h         int // write + proposal-write
	Guardrail24h     int
	ProposalWrites   int
	ProposalRollback int
	Entries          int // window size (honest denominator for the mix)
}

type BackupVersion struct {
	ID     string `json:"id"` // <device>@<unixnano>
	Device string `json:"device"`
	At     string `json:"at"`    // 01-02 15:04:05
	Bytes  int    `json:"bytes"` // redacted text length
	Lines  int    `json:"lines"`
}

type BannerInfo struct {
	// Kind: ssh | http | ftp | smtp | "" (other/unparsed).
	Kind string `json:"kind,omitempty"`
	// Product is the software token from the banner ("Huawei-1.0",
	// "OpenSSH_9.6", "nginx/1.24.0", "vsftpd 3.0.3").
	Product string `json:"product,omitempty"`
	// Version is the product's version when it splits cleanly.
	Version string `json:"version,omitempty"`
	// VendorHint: huawei | cisco | zte | hillstone | vmware | linux | "".
	VendorHint string `json:"vendor_hint,omitempty"`
	// RoleHint is a topology-role suggestion; only set when the banner
	// strongly implies a class (VMware → server). Network-vendor SSH banners
	// deliberately stay empty — Huawei ships the same SSH line on switches,
	// routers and firewalls, and a wrong icon is worse than none.
	RoleHint string `json:"role_hint,omitempty"`
}

type BaselineAggView struct {
	Devices int    `json:"devices"`
	Checked int    `json:"checked"`
	Rules   int    `json:"rules"`
	Hits    int    `json:"hits"`
	At      string `json:"at"`
}

type BaselineSummary struct {
	Devices int    `json:"devices"`
	Checked int    `json:"checked"` // devices whose config was actually read
	Rules   int    `json:"rules"`   // applicable rule count across devices
	Hits    int    `json:"hits"`    // total violations
	At      string `json:"at"`
}

type BaselineViolation struct {
	Rule       string   `json:"rule"`
	Title      string   `json:"title"`
	Severity   string   `json:"severity"`
	Suggestion string   `json:"suggestion,omitempty"`
	Evidence   []string `json:"evidence"`
}

type CVEEntry struct {
	ID       string   `json:"id"` // CVE-2024-xxxx
	Desc     string   `json:"desc"`
	Products []string `json:"products"` // lowercase vendor/product substrings
	Severity string   `json:"severity"` // critical | high | medium | low
}

type CVEMatch struct {
	Device   string `json:"device"`
	CVEID    string `json:"cve_id"`
	Desc     string `json:"desc"`
	Severity string `json:"severity"`
	Product  string `json:"product"` // matched product substring
}

type CaseEntry struct {
	Time   time.Time `json:"time"`
	Kind   string    `json:"kind"` // finding | log | audit | triage | note
	Device string    `json:"device,omitempty"`
	Text   string    `json:"text"`
	Ref    string    `json:"ref,omitempty"` // e.g. finding id
}

type CaseIOC struct {
	Value   string    `json:"value"`
	Type    string    `json:"type"` // ip | hash | domain | keyword
	Note    string    `json:"note,omitempty"`
	AddedAt time.Time `json:"added_at"`
}

type ChainEdge struct {
	From  string `json:"from"`
	To    string `json:"to"`
	Label string `json:"label"`
}

type ChainNode struct {
	ID     string `json:"id"`
	Kind   string `json:"kind"`
	Label  string `json:"label"`
	Device string `json:"device,omitempty"`
	At     string `json:"at,omitempty"`
	// RefType/RefID deep-link the card to its source row (finding/audit/
	// proposal/case-entry); the dash never carries the full text.
	RefType string `json:"ref_type,omitempty"`
	RefID   string `json:"ref_id,omitempty"`
	Status  string `json:"status,omitempty"` // finding severity | proposal status
	// Group>0 marks a collapsed sibling group ("N× 命令采集").
	Group int `json:"group,omitempty"`
}

type CutSuggestion struct {
	From         string `json:"from"`
	To           string `json:"to"`
	Via          string `json:"via"`
	PathsRemoved int    `json:"paths_removed"`
}

type CutoverBoard struct {
	ID            string               `json:"id"`
	Name          string               `json:"name"`
	Status        string               `json:"status"`
	Deadline      string               `json:"deadline,omitempty"`
	RemainingSec  int64                `json:"remaining_sec"` // >0 running; <=0 window over
	Frozen        int                  `json:"frozen"`        // affected device count
	Steps         []CutoverBoardStep   `json:"steps"`
	Devices       []CutoverBoardDevice `json:"devices"`
	RollbackReady bool                 `json:"rollback_ready"`
	RollbackNote  string               `json:"rollback_note,omitempty"`
	Jobs          []CutoverBoardJob    `json:"jobs"`
	Audit         []CutoverBoardAudit  `json:"audit"`
	Report        string               `json:"report,omitempty"`
	HasActive     bool                 `json:"has_active"` // any running/hold cutover exists
	Found         bool                 `json:"found"`      // false = no cutover at all → empty state
}

type CutoverBoardAudit struct {
	Time    string `json:"time"`
	Device  string `json:"device"`
	Command string `json:"command"`
	Status  string `json:"status"`
}

type CutoverBoardDevice struct {
	Device        string `json:"device"`
	Status        string `json:"status"` // done | running | pending | mixed
	RollbackReady bool   `json:"rollback_ready"`
}

type CutoverBoardJob struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Status      string `json:"status"`
	ActiveMS    int64  `json:"active_ms"`
	Commands    int    `json:"commands"`
	MaxWallSec  int    `json:"max_wall_sec,omitempty"`
	MaxCommands int    `json:"max_commands,omitempty"`
}

type CutoverBoardStep struct {
	Label      string `json:"label"`
	Status     string `json:"status"`
	Device     string `json:"device,omitempty"`
	ProposalID string `json:"proposal_id,omitempty"`
	Gate       bool   `json:"gate,omitempty"`
	Decision   bool   `json:"decision_point,omitempty"`
	EstSec     int    `json:"est_sec,omitempty"`
	StartedAt  string `json:"started_at,omitempty"`
	EndedAt    string `json:"ended_at,omitempty"`
}

type CutoverGate struct {
	Device     string `json:"device"`
	Command    string `json:"command"`
	Expect     string `json:"expect"`
	SustainSec int    `json:"sustain_sec,omitempty"` // default 30
	TimeoutSec int    `json:"timeout_sec,omitempty"` // default 2×sustain+90
}

type CutoverRun struct {
	ID       string        `json:"id"`
	Name     string        `json:"name"`
	Deadline time.Time     `json:"deadline"` // 总倒计时（割接窗口结束）
	Steps    []CutoverStep `json:"steps"`
	Status   string        `json:"status"`
	HoldNote string        `json:"hold_note,omitempty"`
	Cursor   int           `json:"cursor"`

	// 割接前后基线快照（device → backup id）+ 对比报告。
	PreSnapshot  map[string]string `json:"pre_snapshot,omitempty"`
	PostSnapshot map[string]string `json:"post_snapshot,omitempty"`
	Report       string            `json:"report,omitempty"`

	CreatedAt time.Time  `json:"created_at"`
	StartedAt *time.Time `json:"started_at,omitempty"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
}

type CutoverStep struct {
	Label         string       `json:"label"`
	EstSec        int          `json:"est_sec,omitempty"`     // 预计耗时（倒计时排程显示）
	ProposalID    string       `json:"proposal_id,omitempty"` // execute an APPROVED proposal
	Device        string       `json:"device,omitempty"`      // …or one sealed read command
	Command       string       `json:"command,omitempty"`
	Gate          *CutoverGate `json:"gate,omitempty"`           // post-step verification gate
	DecisionPoint bool         `json:"decision_point,omitempty"` // 回退决策点：完成后 hold 等人
	Impact        string       `json:"impact,omitempty"`         // 影响描述（决策点并列展示）

	Status    string     `json:"status"`
	StartedAt *time.Time `json:"started_at,omitempty"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
	Output    string     `json:"output,omitempty"`
	Error     string     `json:"error,omitempty"`
}

type DeviceHealth struct {
	Device     string     `json:"device"`
	Time       time.Time  `json:"time"`
	Reachable  bool       `json:"reachable"`
	UptimeSec  int64      `json:"uptimeSec"`
	Interfaces []IfHealth `json:"interfaces"`
	LastError  string     `json:"lastError,omitempty"`
	// 水位（SNMP OID 扩展）：0 = 未采集到（厂商 OID 不适用或设备不答）。
	CpuPct int `json:"cpuPct,omitempty"`
	MemPct int `json:"memPct,omitempty"`
	// 接口 octets 计数器累计和（读取端差分成 bps；0 = 未采集）。
	InOct  uint64 `json:"inOct,omitempty"`
	OutOct uint64 `json:"outOct,omitempty"`
}

type DiscoverHostResult struct {
	IP    string              `json:"ip"`
	Ports []DiscoverPortProbe `json:"ports"`
}

type DiscoverPlan struct {
	Vantage  string     `json:"vantage"`
	Steps    []PlanStep `json:"steps"`
	ArpKnown int        `json:"arp_known"`
	Warnings []string   `json:"warnings"`
}

type DiscoverPortProbe struct {
	Port   int    `json:"port"`
	Open   bool   `json:"open"`
	Banner string `json:"banner,omitempty"` // first bytes, e.g. "SSH-2.0-..."
}

type DiscoveredHost struct {
	IP         string           `json:"ip"`
	Hostname   string           `json:"hostname,omitempty"`
	VendorHint string           `json:"vendor_hint,omitempty"`
	RoleHint   string           `json:"role_hint,omitempty"`
	FirstSeen  time.Time        `json:"first_seen"`
	LastSeen   time.Time        `json:"last_seen"`
	Sources    []string         `json:"sources"`
	Ports      []DiscoveredPort `json:"ports"`
	// Vantage records which managed device saw this lead (F4 provenance —
	// the human-driven recursion's audit trail); Layer is the recursion depth
	// it was found at (inventory vantage → 1).
	Vantage string `json:"vantage,omitempty"`
	Layer   int    `json:"layer,omitempty"`
}

type DiscoveredPort struct {
	Port   int        `json:"port"`
	Banner string     `json:"banner,omitempty"`
	Parsed BannerInfo `json:"parsed,omitempty"`
	// HTTP carries F3's opt-in application fingerprint (title/Server/cert)
	// when http_probe is enabled and the port answered one standard GET.
	HTTP *HTTPFingerprint `json:"http,omitempty"`
	At   time.Time        `json:"at"`
	// FirstSeen stamps the port's first observation (R2 journal basis:
	// newly-opened/newly-closed events are the diff between sweeps).
	FirstSeen time.Time `json:"first_seen,omitempty"`
}

type DiscoveryBoard struct {
	Leads         int `json:"leads"`
	Fingerprinted int `json:"fingerprinted"`
	Pending       int `json:"pending"`
	Promoted      int `json:"promoted"`
	Managed       int `json:"managed"`

	SubnetsDone  int `json:"subnets_done"`
	SubnetsTotal int `json:"subnets_total"`
	LayerDepth   int `json:"layer_depth"`
	MaxHops      int `json:"max_hops"`

	RunStatus    string `json:"run_status,omitempty"`
	RunVantage   string `json:"run_vantage,omitempty"`
	RunUpdatedAt string `json:"run_updated_at,omitempty"`

	Funnel     []DiscoveryFunnelStep `json:"funnel"`
	Layers     []DiscoveryLayerRow   `json:"layers"`
	TriSource  TriSourceAgg          `json:"tri_source"`
	PortEvents []PortEvent           `json:"port_events"`
}

type DiscoveryFunnelStep struct {
	Key   string `json:"key"`
	Count int    `json:"count"`
}

type DiscoveryLayerRow struct {
	Layer int    `json:"layer"`
	Label string `json:"label"`
	Note  string `json:"note,omitempty"`
}

type DiscoveryRunState struct {
	ID        string   `json:"id"`
	Vantage   string   `json:"vantage"`
	Ports     []int    `json:"ports,omitempty"`
	Cidrs     []string `json:"cidrs"`
	DoneCidrs []string `json:"done_cidrs"`
	// Status: running | paused | done.
	Status     string `json:"status"`
	StartedAt  string `json:"started_at"`
	UpdatedAt  string `json:"updated_at"`
	FoundSoFar int    `json:"found_so_far"`
}

type Evidence struct {
	Device  string `json:"device"`
	Command string `json:"command"`
	Output  string `json:"output"` // redacted excerpt
}

type ExecResult struct {
	Device  string `json:"device"`
	Command string `json:"command"`
	Class   string `json:"class"`
	Output  string `json:"output"`
	IsError bool   `json:"is_error"`
	Refused bool   `json:"refused,omitempty"`
	Refusal string `json:"refusal,omitempty"`
}

type ExpectedStateView struct {
	Total     int            `json:"total"` // 有采集面的设备数
	Reachable int            `json:"reachable"`
	Missing   []DeviceHealth `json:"missing"` // 期望在线但不可达
	NoProbe   []string       `json:"noProbe"` // 清单里暂无健康采集面的设备
}

type ExposureBoard struct {
	Simulated      bool                `json:"simulated"` // constant true — 推演角标
	GeneratedAt    string              `json:"generated_at"`
	Critical       int                 `json:"critical"`
	Warning        int                 `json:"warning"`
	Paths          []AttackPath        `json:"paths"`           // top 50 by score
	Cuts           []CutSuggestion     `json:"cut_suggestions"` // top 10
	ExposurePoints []ExposurePoint     `json:"exposure_points"`
	Matrix         []ExposureMatrixRow `json:"matrix"`
	CVEBySeverity  map[string]int      `json:"cve_by_severity,omitempty"`
	CVENeedsFeed   bool                `json:"cve_needs_feed"`
	UnmanagedEnds  int                 `json:"unmanaged_ends"`
	MaxHops        int                 `json:"max_hops"`
}

type ExposureMatrixRow struct {
	Device      string `json:"device"`
	Critical    int    `json:"critical"`
	Warning     int    `json:"warning"`
	Info        int    `json:"info"`
	CveCritical int    `json:"cve_critical"`
	CveHigh     int    `json:"cve_high"`
	Managed     bool   `json:"managed"`
}

type ExposurePoint struct {
	Device    string `json:"device"`
	FindingID string `json:"finding_id,omitempty"`
	Reason    string `json:"reason"`
	Paths     int    `json:"paths"`
}

type Finding struct {
	ID         string     `json:"id"`
	Title      string     `json:"title"`
	Severity   string     `json:"severity"`
	Devices    []string   `json:"devices"`
	Detail     string     `json:"detail"`
	Evidence   []Evidence `json:"evidence"`
	Suggestion string     `json:"suggestion,omitempty"` // what change to draft (netdev_propose), if any
	CreatedAt  time.Time  `json:"created_at"`
	// Source marks the automatic origin ("alert:<rule>:<device>",
	// "syslog:<device>:<class>") — auto-findings dedup and auto-resolve by it;
	// human/AI findings leave it empty.
	Source string `json:"source,omitempty"`
	// Status is the alert lifecycle: "" (human/AI finding) | active | resolved.
	Status     string     `json:"status,omitempty"`
	ResolvedAt *time.Time `json:"resolvedAt,omitempty"`
	// Project is the site-scope snapshot stamped at save time: the project
	// whose groups own the most of this finding's devices (ProjectForDevices).
	// "" = 未分组 — such findings (unknown-source syslog, "(all)" sweeps,
	// pre-Project legacy files) stay visible in EVERY project view so the
	// blind-spot rule holds: alerts that match no project are never hidden.
	// Stamped only when empty — a re-save keeps the original stamp; group
	// membership is a view concern, the stamp is audit history.
	Project string `json:"project,omitempty"`
}

type GoldenDrift struct {
	Device  string
	Extra   []string // in running, not in golden (意外配置)
	Missing []string // in golden, not in running (丢失配置)
	Note    string   // e.g. offline fallback marker
}

type GoldenInfo struct {
	Set   bool   `json:"set"`
	At    string `json:"at"`
	Lines int    `json:"lines"`
}

type HTTPFingerprint struct {
	Title   string `json:"title,omitempty"`
	Server  string `json:"server,omitempty"`
	CertCN  string `json:"cert_cn,omitempty"`
	CertSAN string `json:"cert_san,omitempty"`
}

type HealthSnapshot struct {
	PollIntervalSeconds int            `json:"pollIntervalSeconds"`
	Devices             []DeviceHealth `json:"devices"`
}

type HumanTTYRecording struct {
	Device string `json:"device"`
	Path   string `json:"path"`
	At     string `json:"at"` // yyyymmdd-hhmmss
	Bytes  int64  `json:"bytes"`
}

type HumanTTYState struct {
	Device    string    `json:"device"`
	Connected bool      `json:"connected"`
	StartedAt time.Time `json:"started_at"`
	Bytes     int64     `json:"bytes"` // total output bytes (for audit)
	Error     string    `json:"error,omitempty"`
}

type IfBriefCounts struct {
	Up   int `json:"up"`
	Down int `json:"down"`
}

type IfHealth struct {
	Name    string `json:"name"`
	AdminUp bool   `json:"adminUp"`
	OperUp  bool   `json:"operUp"`
}

type ImportDBSource struct {
	Name string   `json:"name"`
	Type string   `json:"type"`
	Host string   `json:"host"`
	Port int      `json:"port"`
	Via  []string `json:"via"`
}

type ImportDevice struct {
	Name    string   `json:"name"`
	Vendor  string   `json:"vendor"`
	Kind    string   `json:"kind"`
	Address string   `json:"address"`
	Group   string   `json:"group"`
	Via     []string `json:"via"`
}

type ImportDeviceConflict struct {
	Imported ImportDevice `json:"imported"`
	Local    ImportDevice `json:"local"`
}

type ImportPreview struct {
	// NewDevices would be ADDED (name not in current inventory).
	NewDevices []ImportDevice `json:"new_devices"`
	// ConflictDevices exist by name — their address/vendor may differ; the
	// user decides keep-local vs take-imported per device.
	ConflictDevices []ImportDeviceConflict `json:"conflict_devices"`
	// DBNew / DBOverride mirror the same split for db_sources.
	DBNew     []ImportDBSource `json:"db_new"`
	DBOverlap []string         `json:"db_overlap"`
	// SkippedCounts are informational: findings/series/audit tails are
	// import-read-only (the local audit chain stays append-only).
	FindingsSeen int    `json:"findings_seen"`
	ExportedAt   string `json:"exported_at"`
	Source       string `json:"source"`
}

type ImportTopoPreview struct {
	Graph    TopologyGraph   `json:"graph"`
	Stats    TopoImportStats `json:"stats"`
	Warnings []string        `json:"warnings"`
}

type IncidentCase struct {
	ID        string      `json:"id"`
	Title     string      `json:"title"`
	Status    string      `json:"status"` // open | closed
	Devices   []string    `json:"devices,omitempty"`
	Entries   []CaseEntry `json:"entries,omitempty"`
	IOCs      []CaseIOC   `json:"iocs,omitempty"`
	CreatedAt time.Time   `json:"created_at"`
	UpdatedAt time.Time   `json:"updated_at"`
}

type InspectionJournalRow struct {
	At           string                   `json:"at"`   // 2006-01-02T15:04:05
	Kind         string                   `json:"kind"` // inspection | baseline
	Devices      int                      `json:"devices"`
	Checked      int                      `json:"checked"`
	Critical     int                      `json:"critical"` // open tallies at run end — the risk-score trend source
	Warning      int                      `json:"warning"`
	Info         int                      `json:"info"`
	BaselineHits int                      `json:"baseline_hits,omitempty"`
	IfBrief      map[string]IfBriefCounts `json:"if_brief,omitempty"`
}

type InvestigationChain struct {
	CaseID    string `json:"case_id,omitempty"`
	CaseTitle string `json:"case_title,omitempty"`
	HasCase   bool   `json:"has_case"`
	FindingID string `json:"finding_id,omitempty"`
	// Counts carries per-kind node tallies — the inline stats row; the
	// denominators are the node counts themselves (可查 via deep links).
	Counts    map[string]int  `json:"counts"`
	Nodes     []ChainNode     `json:"nodes"`
	Edges     []ChainEdge     `json:"edges"`
	Timeline  []TimelineEvent `json:"timeline,omitempty"`
	Truncated bool            `json:"truncated"`
}

type Job struct {
	ID        string         `json:"id"`
	Name      string         `json:"name"`
	Steps     []JobStep      `json:"steps"`
	StepState []JobStepState `json:"step_state"`
	Status    string         `json:"status"`
	Budget    JobBudget      `json:"budget"`

	CreatedAt time.Time  `json:"created_at"`
	StartedAt *time.Time `json:"started_at,omitempty"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`

	ActiveMS     int64  `json:"active_ms"`            // wall clock actually spent running (pauses excluded)
	Commands     int    `json:"commands"`             // attempts executed against the budget
	Cursor       int    `json:"cursor"`               // next step index (断点续跑 anchor)
	BreakpointOK int    `json:"breakpoint_ok"`        // cursor whose PauseBefore was human-confirmed
	PauseNote    string `json:"pause_note,omitempty"` // why it paused — shown to the human
	CreatedBy    string `json:"created_by,omitempty"`
}

type JobBudget struct {
	MaxWallSec  int `json:"max_wall_sec,omitempty"` // default 1800
	MaxCommands int `json:"max_commands,omitempty"` // default 200
	FailStreak  int `json:"fail_streak,omitempty"`  // default 3 consecutive failures → circuit-break pause
}

type JobStep struct {
	Name        string `json:"name"`
	Device      string `json:"device"`
	Command     string `json:"command"`
	Expect      string `json:"expect,omitempty"`       // regex that must appear in the output within the timeout
	TimeoutSec  int    `json:"timeout_sec,omitempty"`  // per attempt (default 60)
	Retries     int    `json:"retries,omitempty"`      // extra attempts after the first failure (≤4)
	OnFail      string `json:"on_fail,omitempty"`      // pause | abort | continue (default pause)
	PauseBefore bool   `json:"pause_before,omitempty"` // 断点：human confirms before this step runs
}

type JobStepState struct {
	Status    string     `json:"status"`
	Attempts  int        `json:"attempts,omitempty"`
	Output    string     `json:"output,omitempty"` // last attempt tail, already redacted by Exec
	Error     string     `json:"error,omitempty"`
	StartedAt *time.Time `json:"started_at,omitempty"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
}

type LiveDeviceState struct {
	Device    string `json:"device"`
	Vendor    string `json:"vendor"`
	OS        string `json:"os,omitempty"`
	Group     string `json:"group,omitempty"`
	Connected bool   `json:"connected"`
	VTYUse    int    `json:"vtyUse"`
	VTYCap    int    `json:"vtyCap"`
}

type LiveEvent struct {
	Kind   string `json:"kind"`
	Device string `json:"device"`
	Time   int64  `json:"time"` // unix milliseconds

	// LiveConn
	State  string `json:"state,omitempty"`
	VTYUse int    `json:"vtyUse,omitempty"` // sessions currently held on the device
	VTYCap int    `json:"vtyCap,omitempty"` // max_sessions_per_device (0 = unset)

	// LiveCmdStart / LiveCmdEnd / LiveCmdRefused
	Command string `json:"command,omitempty"`
	Class   string `json:"class,omitempty"` // read | write | dangerous | unknown | guardrail

	// LiveCmdOutput
	Chunk string `json:"chunk,omitempty"`

	// LiveCmdEnd / LiveCmdRefused
	Status string `json:"status,omitempty"` // ok | device-error | refused | failure
	MS     int64  `json:"ms,omitempty"`     // wall-clock duration of the command
	Bytes  int    `json:"bytes,omitempty"`  // redacted output size
	Reason string `json:"reason,omitempty"` // refusal / failure reason
}

type LiveSnapshot struct {
	Devices []LiveDeviceState `json:"devices"`
	Spent   int               `json:"spent"`  // commands spent this turn
	Budget  int               `json:"budget"` // turn_command_budget (0 = unlimited)
}

type LocateHit struct {
	Device    string `json:"device"`
	Interface string `json:"interface,omitempty"`
	Line      string `json:"line"`
}

type LocateResult struct {
	Target     string      `json:"target"`
	Hits       []LocateHit `json:"hits"`
	Devices    []string    `json:"searched"`
	Skipped    []string    `json:"skipped,omitempty"`
	Covered    int         `json:"covered_devices"`
	Total      int         `json:"total_devices"`
	BudgetStop bool        `json:"budget_stopped"`
	Note       string      `json:"note,omitempty"`
}

type LogFollowEvent struct {
	Device string `json:"device"`
	Source string `json:"source"`
	Chunk  string `json:"chunk,omitempty"`
	Done   bool   `json:"done,omitempty"`
	Reason string `json:"reason,omitempty"`
}

type LogSearchHit struct {
	Device  string   `json:"device"`
	Source  string   `json:"source"`
	Line    string   `json:"line"`
	Context []string `json:"context,omitempty"`
}

type LogSearchResult struct {
	Pattern    string         `json:"pattern"`
	Hits       []LogSearchHit `json:"hits"`
	Devices    []string       `json:"devices_searched"`
	Skipped    []string       `json:"skipped"` // device — reason strings
	Covered    int            `json:"covered_devices"`
	Total      int            `json:"total_devices"`
	HitDevice  int            `json:"devices_with_hits"`
	BudgetStop bool           `json:"budget_stopped"`
	Note       string         `json:"note,omitempty"`
}

type LogSourceProbe struct {
	Device     string      `json:"device"`
	Services   []string    `json:"services"`
	Containers []string    `json:"containers"`
	Files      []ProbeFile `json:"files"`
	Errors     []string    `json:"errors"`
}

type Manager struct {
	// contains filtered or unexported fields
}

type MetricPoint struct {
	Time      time.Time `json:"time"`
	Reachable bool      `json:"up"`
	UptimeSec int64     `json:"us"`
	IfUp      int       `json:"iu"`
	IfDown    int       `json:"id"`
	// 水位（DASHBOARD spec §7.3 SNMP OID 扩展）：cpu/mem 为百分比，octets
	// 为 ifTable 计数器累计和——速率（bps）由读取端按相邻点差分计算。
	Cpu    int    `json:"cu,omitempty"`
	Mem    int    `json:"me,omitempty"`
	InOct  uint64 `json:"io,omitempty"`
	OutOct uint64 `json:"oo,omitempty"`
}

type NetDevEvent struct {
	Time time.Time
	Text string
}

type NetprobeHost struct {
	IP    string `json:"ip"`
	ICMP  bool   `json:"icmp"`
	Ports []struct {
		Port   int    `json:"port"`
		Open   bool   `json:"open"`
		Banner string `json:"banner,omitempty"`
	} `json:"ports"`
}

type NetprobeSweepResult struct {
	CIDR      string         `json:"cidr"`
	ICMP      bool           `json:"icmp"`
	Alive     int            `json:"alive"`
	WithPorts int            `json:"with_ports"`
	Results   []NetprobeHost `json:"results"`
	Command   string         `json:"command"`
	Duration  string         `json:"duration"`
}

type NmapHost struct {
	IP       string            `json:"ip"`
	Hostname string            `json:"hostname,omitempty"`
	Services []NmapHostService `json:"services"`
}

type NmapHostService struct {
	Port    int    `json:"port"`
	Proto   string `json:"proto,omitempty"`
	Service string `json:"service,omitempty"` // name, e.g. ssh/http/redis
	Product string `json:"product,omitempty"` // e.g. OpenSSH / nginx
	Version string `json:"version,omitempty"`
}

type NmapSweepResult struct {
	CIDR      string     `json:"cidr"`
	Hosts     int        `json:"hosts"`
	OpenPorts int        `json:"open_ports"`
	Results   []NmapHost `json:"results"`
	Command   string     `json:"command"`
	Duration  string     `json:"duration"`
}

type NotifyPusher interface {
	Push(ctx context.Context, dest, text string) error
}

type PlanStep struct {
	CIDR      string `json:"cidr"`
	Class     string `json:"class"`
	Hosts     int    `json:"hosts"`
	DefaultOn bool   `json:"default_on"`
}

type PortEvent struct {
	At   string `json:"at"`
	IP   string `json:"ip"`
	Port int    `json:"port"`
	Kind string `json:"kind"` // newly-opened | newly-closed
}

type PrecheckResult struct {
	Vantage       string        `json:"vantage"`
	Vendor        string        `json:"vendor,omitempty"`
	Interfaces    []string      `json:"interfaces"` // name/ip/mask rows (display)
	DirectSubnets []SubnetClass `json:"direct_subnets"`
	RoutedSubnets []SubnetClass `json:"routed_subnets"`
	ArpKnownIPs   []string      `json:"arp_known_ips"`
	Uncovered     string        `json:"uncovered_note,omitempty"` // aggregates beyond coverage
	Warnings      []string      `json:"warnings"`
	At            string        `json:"at"`
}

type ProbeFile struct {
	Name    string `json:"name"`    // messages
	Path    string `json:"path"`    // /var/log/messages
	Size    string `json:"size"`    // 2.1M (from ls -lh; "" = unknown)
	Allowed bool   `json:"allowed"` // readable via file: as-is
}

type Proposal struct {
	ID     string         `json:"id"`
	Intent string         `json:"intent"`
	Status string         `json:"status"`
	Steps  []ProposalStep `json:"steps"`
	// 恢复提案来源（备份→恢复闭环）：从备份版本起草的恢复提案记录来源
	// 版本 ID（device@nanos）；审计与前端据此回放「恢复自哪一版」。
	RestoreFrom string    `json:"restore_from,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	ApprovedAt  time.Time `json:"approved_at,omitempty"`
	ExecutedAt  time.Time `json:"executed_at,omitempty"`
	Approver    string    `json:"approver,omitempty"`
	Confirm2    bool      `json:"confirm2"`       // secondary confirmation for proposal+confirm2 groups
	Note        string    `json:"note,omitempty"` // freeze/rollback reason trail
	// 驳回（completion-spec §4.1）：draft/approved 可被人否决；Reason 随变更
	// 持久化，agent 下一轮读到变更即见被拒原因。
	RejectedAt   time.Time `json:"rejected_at,omitempty"`
	RejectReason string    `json:"reject_reason,omitempty"`
	// 观察期（§7.1）：done → watching（默认 30 分钟）→ closed；劣化触发 Finding。
	WatchUntil *time.Time `json:"watch_until,omitempty"`
	WatchNote  string     `json:"watch_note,omitempty"`
	// HealthBase is the ifDown count per target device at watch start（-1 =
	// 当时不可达）——观察期劣化检测（健康轮询对比）的基线。仅 SNMP 配置
	// 设备有信号；其余设备跳过对比。
	HealthBase map[string]int `json:"health_base,omitempty"`
}

type ProposalStep struct {
	Device   string   `json:"device"`
	Type     string   `json:"type,omitempty"`     // "" | cli | k8s-apply | sql-migration | file-upload | cert-replace
	Commands []string `json:"commands"`           // cli: the change, in order
	Rollback []string `json:"rollback,omitempty"` // cli: reverse commands, authored with the change

	// Structured payloads (§7.1) — only the fields of the step's type matter.
	YAML          string `json:"yaml,omitempty"`           // k8s-apply: full manifest
	UpSQL         string `json:"up_sql,omitempty"`         // sql-migration
	DownSQL       string `json:"down_sql,omitempty"`       // sql-migration — REQUIRED (missing ⇒ not submittable)
	LocalPath     string `json:"local_path,omitempty"`     // file-upload / cert-replace: local cert file
	RemotePath    string `json:"remote_path,omitempty"`    // file-upload / cert-replace: absolute target path
	KeyLocalPath  string `json:"key_local_path,omitempty"` // cert-replace: local private key file
	KeyRemotePath string `json:"key_remote_path,omitempty"`
	Checksum      string `json:"checksum,omitempty"`   // optional sha256 the uploaded bytes must match
	ReloadCmd     string `json:"reload_cmd,omitempty"` // cert-replace: service reload after the swap
	// restore-verify（§7.3 备份恢复演练）: restore a config snapshot to a
	// STAGING target and run the verify read. Device = receiver.
	RestoreDevice  string `json:"restore_device,omitempty"`  // snapshot source device
	RestoreVersion string `json:"restore_version,omitempty"` // snapshot id; "" = latest at execute time
	VerifyCmd      string `json:"verify_cmd,omitempty"`      // e.g. `nginx -t`

	Backup    string `json:"backup,omitempty"` // captured pre-change state (redacted)
	Applied   bool   `json:"applied"`
	Error     string `json:"error,omitempty"`
	Dangerous bool   `json:"dangerous,omitempty"` // destructive verb scan ⇒ forces confirm2 (§7.1)
}

type Result struct {
	Command string
	Output  string // cleaned text: echo and trailing prompt removed
	IsError bool   // a driver error pattern matched
}

type SSHClient interface {
	NewSession() (*ssh.Session, error)
}

type ScheduleStamp struct {
	At    string `json:"at"`   // 2006-01-02T15:04:05
	Kind  string `json:"kind"` // inspection
	Ok    bool   `json:"ok"`
	Title string `json:"title,omitempty"` // the filed Finding's title
	Note  string `json:"note,omitempty"`  // failure note
}

type SeriesPoint struct {
	T      int64   `json:"t"` // unix seconds
	Device string  `json:"d"`
	Metric string  `json:"m"`
	Value  float64 `json:"v"`
}

type Session struct {
	// contains filtered or unexported fields
}

type SrvConfDriftRow struct {
	Device string `json:"device"`
	Group  string `json:"group"`
	Status string `json:"status"` // same | drift | error | absent
	Diff   string `json:"diff,omitempty"`
	Error  string `json:"error,omitempty"`
}

type SrvConfVersion struct {
	ID     string `json:"id"`
	Device string `json:"device"`
	Path   string `json:"path"`
	At     string `json:"at"`
	Bytes  int    `json:"bytes"`
	Lines  int    `json:"lines"`
}

type StateEventMeta struct {
	ID         int               `json:"id"`
	Time       time.Time         `json:"time"`
	Kind       string            `json:"kind"`
	Entity     string            `json:"entity,omitempty"`
	Actor      string            `json:"actor"`
	Paths      []string          `json:"paths"`
	Live       []StateLiveEntity `json:"live,omitempty"`
	CanRestore bool              `json:"canRestore"`
	CanRedo    bool              `json:"canRedo"`
}

type StateLiveEntity struct {
	Type   string `json:"type"`   // proposal | job | cutover
	ID     string `json:"id"`     // entity id
	Status string `json:"status"` // why it is live (executing / running / hold…)
}

type StateRestoreResult struct {
	Written        []string `json:"written"`
	Deleted        []string `json:"deleted"`
	ReverseEventID int      `json:"reverseEventId"`
}

type SubnetClass struct {
	CIDR      string `json:"cidr"`
	Class     string `json:"class"` // direct-small | routed-small | medium | large
	Hosts     int    `json:"hosts"`
	DefaultOn bool   `json:"default_on"`
}

type SyslogCountRow struct {
	Hour   string `json:"hour"` // YYYY-MM-DDTHH
	Device string `json:"device"`
	Class  string `json:"class"`
	N      int    `json:"n"`
}

type SyslogStatusView struct {
	Listening bool `json:"listening"`
	Port      int  `json:"port"`
	Buffered  int  `json:"buffered"`
}

type Template struct {
	ID        string         `json:"id"`
	Name      string         `json:"name"`
	Intent    string         `json:"intent"`
	Vars      []string       `json:"vars,omitempty"` // user-supplied variable names
	Steps     []TemplateStep `json:"steps"`          // per-device command templates
	Targets   []string       `json:"targets"`        // explicit device names
	CreatedAt time.Time      `json:"created_at"`
}

type TemplatePreviewDevice struct {
	Device    string                `json:"device"`
	Available bool                  `json:"available"` // device exists & not read-only-group
	Reason    string                `json:"reason,omitempty"`
	Steps     []TemplatePreviewStep `json:"steps"`
}

type TemplatePreviewStep struct {
	Commands  []string `json:"commands"`
	Rollback  []string `json:"rollback"`
	Classes   []string `json:"classes"`   // per rendered command: read|write|dangerous|unknown
	Dangerous bool     `json:"dangerous"` // verb scan hit — confirm2 forced on apply
}

type TemplateStep struct {
	Commands []string `json:"commands"`
	Rollback []string `json:"rollback"`
}

type TestResult struct {
	Device      string `json:"device"`
	Status      string `json:"status"` // ok | unknown-host-key | auth-failed | refused-by-classifier | error
	Detail      string `json:"detail,omitempty"`
	Host        string `json:"host,omitempty"`
	KeyType     string `json:"keyType,omitempty"`
	Fingerprint string `json:"fingerprint,omitempty"`
}

type TimelineEvent struct {
	Time   time.Time `json:"time"`
	Kind   string    `json:"kind"` // change | finding | event
	Device string    `json:"device"`
	Title  string    `json:"title"`
	Detail string    `json:"detail,omitempty"`
}

type TopoImportStats struct {
	Total          int    `json:"total"`
	Managed        int    `json:"managed"`
	NewNodes       int    `json:"new_nodes"`
	UnresolvedRole int    `json:"unresolved_role"`
	Pages          int    `json:"pages"`
	UsedPage       string `json:"used_page"`
}

type TopoReconcile struct {
	Tri       TriSourceAgg   `json:"tri"`
	Platforms map[string]int `json:"platforms"` // edge source → count (lldp/cdp/design/bastion)
}

type TopologyDesign struct {
	ImportedAt string        `json:"imported_at"`
	SourceFile string        `json:"source_file"`
	Graph      TopologyGraph `json:"graph"`
}

type TopologyEdge struct {
	LocalDevice  string `json:"local_device"`
	LocalPort    string `json:"local_port"`
	RemoteDevice string `json:"remote_device"`
	RemotePort   string `json:"remote_port,omitempty"`
	RemoteIP     string `json:"remote_ip,omitempty"`
	Source       string `json:"source"` // lldp | cdp
	// Platform is the neighbor's self-described platform/model (F2): CDP
	// "Platform:" line or LLDP "System description" — vendor/model words that
	// feed role inference and the 待确认区 hints. Free text from the wire,
	// display-only.
	Platform string `json:"platform,omitempty"`
}

type TopologyGraph struct {
	Nodes []TopologyNode `json:"nodes"`
	Edges []TopologyEdge `json:"edges"`
	At    string         `json:"at"`
}

type TopologyNode struct {
	Name     string `json:"name"`
	Managed  bool   `json:"managed"`
	DeviceIP string `json:"device_ip,omitempty"`
	// Subnet annotates the local IP-plan view (the /24 the address lives in).
	Subnet string `json:"subnet,omitempty"`
	// Tier is the LOCAL inference's band (0 core / 1 agg / 2 access / 3
	// unmanaged) from group words, name conventions, or subnet ordering —
	// present only in the IP-plan view; the LLDP snapshot leaves it at -1
	// and the map falls back to its degree heuristic.
	Tier int `json:"tier"`
	// Role is the device-class icon key (router/switch/firewall/ips/vpn/
	// bastion/server/ap/cloud; "" = unknown), ORTHOGONAL to tier: tier picks
	// the band, role picks the icon, health keeps stroke color, managed keeps
	// solid/dashed. RoleSource records the provenance (config|kind|group|
	// model|vendor|label|none) for the tooltip's confidence hint.
	Role       string `json:"role,omitempty"`
	RoleSource string `json:"role_source,omitempty"`
}

type TriSourceAgg struct {
	Design     int `json:"design"`
	Plan       int `json:"plan"`
	Matched    int `json:"matched"`
	OnlyDesign int `json:"only_design"`
	OnlyPlan   int `json:"only_plan"`
}

type TriageReport struct {
	Device    string          `json:"device"`
	Vendor    string          `json:"vendor"`
	Sections  []TriageSection `json:"sections"`
	Anomalies []string        `json:"anomalies,omitempty"`
	Summary   string          `json:"summary"`
	CreatedAt time.Time       `json:"created_at"`
}

type TriageSection struct {
	Name    string   `json:"name"`
	Command string   `json:"command"`
	Ok      bool     `json:"ok"`
	Refused string   `json:"refused,omitempty"`
	Lines   []string `json:"lines,omitempty"`
}

type WeakCredResult struct {
	Device   string `json:"device"`
	Tier     string `json:"tier"`
	Weak     bool   `json:"weak"`
	Attempts int    `json:"attempts"`
	Budget   int    `json:"budget"`
	Detail   string `json:"detail,omitempty"`
}