endpoint

type ACLLister interface {
	ListACL(ctx context.Context, fabricIndex uint8) ([]store.ACLEntry, error)
}

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

type AuxiliaryACLLister interface {
	AuxiliaryACL(ctx context.Context, fabricIndex uint8) ([]store.ACLEntry, error)
}

type AvailabilityProbe func() bool

type ClusterShape struct {
	FeatureMap    uint32
	FeaturesKnown bool

	Attributes      []uint32
	AttributesKnown bool

	AcceptedCommands []uint32
	CommandsKnown    bool

	Events      []uint32
	EventsKnown bool
}

type Config struct {
	// VendorID is the bridge's IANA-assigned vendor identifier.
	VendorID uint16
	// ProductID is the bridge's vendor-assigned product identifier.
	ProductID uint16
	// NodeLabel is the user-visible bridge label.
	NodeLabel string
	// VendorName is the node's own BasicInformation VendorName. A bridged
	// endpoint whose [Spec.VendorName] is empty serves it as its
	// BridgedDeviceBasicInformation VendorName, so the vendor fields
	// controllers rely on stay filled; empty as well, the attribute is not
	// served — matter.js's default for a bridged device, where vendorName
	// is optional and its bridge example sets none.
	VendorName string
	// Groups is the node's group state. When set, every bridged endpoint
	// whose device type mandates the Groups cluster (on-off-light,
	// on-off-plug-in-unit, … — schema.DeviceTypeRequiresServerCluster)
	// serves a real Groups server over it, and a Groups server a source
	// supplies itself is replaced by one: group membership is stack state,
	// as in matter.js (GroupsServer keeps it in the root's
	// GroupKeyManagementServer). nil keeps whatever the source supplies.
	Groups *groups.Manager
	// OnNodeLabelWritten fires after a controller wrote a bridged
	// endpoint's BridgedDeviceBasicInformation NodeLabel, with the
	// endpoint's stable key and the new label, so the host can persist it
	// and hand it back as [Spec.NodeLabel] after a restart — matter.js
	// keeps a written nodeLabel in the endpoint's persisted state. nil
	// keeps the label for the life of the process only.
	OnNodeLabelWritten func(key SourceKey, label string)
	// Scenes persists the scene tables of the endpoints that serve
	// ScenesManagement (see [ScenesStore]). With Groups set, every bridged
	// endpoint whose device type mandates ScenesManagement (the light
	// device types) serves the stack's ScenesManagement server, in place
	// of any a source supplies — as matter.js mounts ScenesManagementServer
	// for those device types. nil keeps the tables for the life of the
	// process.
	Scenes ScenesStore
	// RootDeviceConditions are the device-type conditions the host states
	// for the root endpoint ([Endpoint.DeviceConditions]) — the node's own
	// facts no topology shows, such as LanguageLocale, TimeLocale or
	// UnitLocale. nil states none.
	RootDeviceConditions []string
	// Clock is the time source of the stateful servers the assembler
	// builds per bridged endpoint — the Identify server's IdentifyTime
	// countdown (cluster/core.Identify.SetClock); nil is [clock.System].
	// A node passes its own (node.Config.Clock).
	Clock clock.Clock
}

type DeviceTypeConformanceError struct {
	Violations []DeviceTypeViolation
}

type DeviceTypeSubject interface {
	// EndpointNumber is the endpoint number.
	EndpointNumber() uint16
	// DeviceTypeIDs are the device types the endpoint lists (its
	// Descriptor's DeviceTypeList), the ones the model does not define
	// included (DeviceTypeFacts.ts:33-36).
	DeviceTypeIDs() []uint32
	// ServerClusterIDs are the endpoint's server clusters (its ServerList).
	ServerClusterIDs() []uint32
	// ClientClusterIDs are the endpoint's client clusters (its ClientList).
	ClientClusterIDs() []uint32
	// ServerClusterShape is what the endpoint's server cluster reports of
	// itself; ok false while its shape is not known, and then nothing
	// nested in a requirement of the cluster is judged.
	ServerClusterShape(cluster uint32) (shape ClusterShape, ok bool)
	// StatedConditions are the condition names stated for the endpoint, as
	// spelled (DeviceTypeFacts.ts:54-57).
	StatedConditions() []string
	// PartNumbers are the endpoint's direct children (DeviceTypeFacts.ts:
	// 22-25); a number the tree does not hold is ignored.
	PartNumbers() []uint16
}

type DeviceTypeTree struct {
	// Endpoints are the tree's endpoints; a nil entry is skipped.
	Endpoints []DeviceTypeSubject
	// NodeConditions answers the conditions the configuration of the node
	// whose node endpoint is nodeEndpoint makes true, beyond those derived
	// from the tree (DeviceTypeFacts.ts:59-63); nil answers none.
	NodeConditions func(nodeEndpoint uint16) []string
}

type DeviceTypeValidationMode int

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

type DeviceTypeVerdict struct {
	// Violations are every current violation, by endpoint in topology
	// order.
	Violations []DeviceTypeViolation
	// Fresh are those not reported by an earlier validation — what
	// matter.js logs, once, as a warning.
	Fresh []DeviceTypeViolation
}

type DeviceTypeViolation struct {
	// Endpoint is the endpoint that departs.
	Endpoint uint16
	// DeviceType names the device type whose requirement is violated: one
	// the endpoint lists, "Base", the device type declaring a misplaced
	// singleton, the composing device type of a component, or the
	// asserting device type of a Descendant condition count.
	DeviceType string
	// DeviceTypeID is that device type's id; zero for Base and where the
	// violation names none.
	DeviceTypeID uint32
	// Requirement is matter.js's requirement path: "Identify", "OnOff.LT",
	// "client:OnOff", "Identify.TriggerEffect", "device:PowerSource",
	// "device:ElectricalSensor#2", "condition:Cooler", or the stated
	// condition name of an unknown condition.
	Requirement string
	Kind        ViolationKind
	// Detail describes the departure for a developer, as matter.js words it.
	Detail string

	// Cluster is the cluster the requirement concerns, where it concerns
	// one (HasCluster).
	Cluster    uint32
	HasCluster bool
	// Element is the kind of an element requirement (feature, attribute,
	// command, event); empty for a cluster, component or condition
	// requirement. ElementName is the feature code or element name,
	// ElementID the attribute, command or event id.
	Element     schema.RequirementElement
	ElementName string
	ElementID   uint32
	// Conformance is the requirement's conformance as matter.js prints it;
	// empty when it states none.
	Conformance string
	// Conditions are the names in that conformance that held for the
	// endpoint — the conditions (and features) that made it apply.
	Conditions []string
}

type Endpoint struct {
	// ID is the Matter endpoint identifier. 0 = root, 1 = aggregator,
	// 2..65534 = bridged.
	ID uint16
	// DeviceType is the Matter Device Type ID this endpoint
	// advertises (e.g. 0x010A OnOffPlugInUnit, 0x0301 Thermostat,
	// 0x000E AggregatorEndpoint for the root).
	DeviceType uint16
	// Reachable mirrors the underlying device's availability. Maps
	// to BridgedDeviceBasicInformation.Reachable (Matter §9.13.3).
	// Always true for the root endpoint.
	Reachable bool
	// FriendlyName is the human-readable label used by
	// BridgedDeviceBasicInformation.NodeLabel. Empty for the root
	// endpoint (the root carries the bridge's NodeLabel directly,
	// supplied via Config).
	FriendlyName string
	// Availability probes the source's LIVE reachability, or is nil on
	// the root endpoint and on any endpoint with no live source. The
	// bridged cluster surface is rebuilt on every dispatch and re-reads
	// it there, so a source that dies after assembly stops advertising
	// Reachable=true instead of keeping the topology-time reading
	// forever. Reachable above carries that reading for callers that
	// only inspect the assembled topology.
	Availability AvailabilityProbe
	// ChannelAddress is the source's address in the owner's own
	// namespace, carried through from [Spec.ChannelAddress] for
	// diagnostics. Empty for the root endpoint.
	ChannelAddress string
	// Source is the rich-model implementation of the cluster
	// surface. nil for the root endpoint and for measurement-only
	// sub-endpoints (which use Measurement instead).
	Source contract.EndpointSource
	// Measurement is set on sensor endpoints assembled from
	// MatterMeasurementSource implementers. nil otherwise. With Source
	// also set, its clusters follow the source's ([ClusterServers]).
	Measurement contract.MeasurementSource
	// PowerSource carries the device's battery reading on exactly one of
	// the device's endpoints, so the PowerSource cluster (0x002F) is served
	// where BridgedNode (0x0013) specifies it rather than on an endpoint of
	// its own with no device type. nil on every other endpoint, and on
	// mains-powered devices. Set by [attachPowerSource].
	PowerSource contract.MeasurementSource
	// SourceKey is the persisted endpoint identity, rendered by the
	// owner. Empty for the root and aggregator endpoints.
	SourceKey SourceKey
	// Scope is the [Snapshot.Scope] the endpoint was assembled from.
	// Empty for the root and aggregator endpoints.
	Scope string
	// DeviceAddress is the address of the PHYSICAL device behind this
	// endpoint, in the owner's own namespace. Several endpoints of one
	// device share it, which is what lets a device-level signal —
	// reachability above all — be fanned out to all of them
	// ([Bridge.NotifyDeviceReachable]). Empty when the owner has no
	// such notion, and on the root and aggregator endpoints.
	DeviceAddress string

	// BridgeVendorID / BridgeProductID carry the bridge-wide VID/PID
	// the assembler copies from the topology. The bridged-endpoint
	// BridgedDeviceBasicInformation cluster server reports these so an
	// operator-supplied production VID/PID surfaces on every bridged
	// endpoint instead of the CSA test pair (0xFFF1/0x8001). Zero
	// values trigger the test-pair fallback for the dev workflow.
	BridgeVendorID  uint16
	BridgeProductID uint16
	// BridgeVendorName is the node's own VendorName ([Config.VendorName]),
	// stamped like BridgeVendorID: the BridgedDeviceBasicInformation
	// VendorName of a bridged endpoint without one of its own.
	BridgeVendorName string
	// VendorName is the bridged device's own manufacturer
	// ([Spec.VendorName]); empty falls back to BridgeVendorName.
	VendorName string

	// ParentEndpointID is the Matter endpoint ID of the parent
	// endpoint in the bridge hierarchy. For bridged endpoints (ID ≥ 2)
	// the parent is always the Aggregator (ID 1). For the root (ID 0)
	// and Aggregator (ID 1) themselves it is 0 (no parent).
	//
	// chip bridge-app sets parentEndpointId = 1 for every bridged
	// endpoint via AddDeviceEndpoint(..., parentEndpointId). matter.js
	// establishes the same relationship via aggregator.add(child).
	// Per Matter §9.5.3, ParentEndpoint is optional for flat bridges
	// (all bridged directly under Aggregator) but chip populates it
	// for every bridged endpoint. We mirror chip's behaviour.
	// Mirrors chip examples/bridge-app/linux/main.cpp:261-276
	// AddDeviceEndpoint(..., parentEndpointId=1).
	ParentEndpointID uint16
	// HasParentEndpointID is true when ParentEndpointID carries a
	// meaningful value (i.e. for any bridged endpoint with ID ≥ 2).
	HasParentEndpointID bool

	// Part is true for an endpoint assembled from a [Spec.Parts] entry: a
	// component of the endpoint ParentEndpointID names, not a bridged node
	// of its own (no BridgedNode device type, no
	// BridgedDeviceBasicInformation).
	Part bool
	// PartIDs are the endpoint's Descriptor PartsList, ascending: every
	// descendant ([Spec.Parts], recursively) when one of its listed device
	// types composes its full family — a bridged node, BridgedNode being
	// full-family — and its direct parts otherwise. Mirrors matter.js
	// packages/node/src/behaviors/descriptor/DescriptorServer.ts:227-254
	// (#currentPartsListNumbers).
	PartIDs []uint16

	// DeviceConditions are the device-type conditions the host states for
	// this endpoint (Core § 9.2.6), as declared ("PhysicalInputs",
	// "LanguageLocale"): what describes the product rather than the
	// topology, so [ValidateDeviceTypes] cannot derive it. Stating one
	// makes it true, which can make a requirement mandatory; a name that
	// names no condition in the endpoint's scope is reported. Carried from
	// [Spec.DeviceConditions], and on the root from
	// [Config.RootDeviceConditions]. Mirrors matter.js
	// Endpoint.Options.deviceConditions.
	DeviceConditions []string

	// ClientClusters are the client clusters the endpoint declares, served
	// as its Descriptor ClientList. Carried from [Spec.ClientClusters].
	ClientClusters []uint32

	// OptIn are the stack-mounted optional server clusters the endpoint
	// opts into (Groups, ScenesManagement). Carried from [Spec.OptIn].
	OptIn []uint32
	// contains filtered or unexported fields
}

type Record struct {
	Key SourceKey
	// Scope is the [Snapshot.Scope] the source belongs to. Carried
	// because garbage collection lists one scope at a time and the key
	// is opaque here, so a store has no other way to answer
	// ListEndpoints. A store whose own key type already names the scope
	// should read it from there and reject a Scope that disagrees,
	// rather than keep two unchecked sources for one column.
	Scope      string
	EndpointID uint16
	DeviceType uint16
}

type ScenesStore interface {
	LoadScenes(key SourceKey) []byte
	SaveScenes(key SourceKey, table []byte)
}

type Snapshot struct {
	// Scope names the owner-side partition these endpoints come from —
	// one controller, one site, one upstream hub. The assembler treats
	// it as an opaque label: it garbage-collects persisted identities
	// one scope at a time, so a partition that has not loaded yet
	// cannot delete another's rows. An owner with a single partition
	// may use any non-empty constant.
	Scope string
	// Endpoints describes every bridged endpoint this central
	// contributes. nil-safe — an empty slice produces zero endpoints.
	Endpoints []Spec
	// ModelComplete reports whether this scope's initial source load
	// has finished, i.e. Endpoints is the authoritative full fleet
	// rather than a boot-time (still-empty or partially loaded) view. The
	// assembler only garbage-collects persisted endpoint-ID rows for
	// model-complete snapshots: the topology is first assembled at
	// daemon start, before the readiness-gated source load, and a
	// scope that has not loaded yet must keep every persisted
	// endpoint number so its bridged endpoints reappear under their old
	// IDs once the load completes. Mirrors matter.js, which reserves
	// every persisted endpoint number at node initialization
	// (packages/node/src/storage/server/ServerEndpointStores.ts,
	// assignNumber + the load() pre-allocation pass) and releases one
	// only on explicit endpoint deletion
	// (packages/node/src/node/server/ServerEndpointInitializer.ts,
	// eraseDescendant) — never because state has not been populated yet.
	// See BD-Matter-EndpointID-Persistent in notes/parity/by_design.md.
	ModelComplete bool
}

type SourceKey interface {
	fmt.Stringer
}

type Spec struct {
	// StableKey identifies the source across reassemblies and daemon
	// restarts. It is the owner's persisted endpoint-identity key, so
	// it decides which endpoint id the endpoint gets back, which
	// per-endpoint state it reuses, and which UniqueID it publishes.
	// Two specs must never share one key. See [SourceKey] for the
	// stability the rendering owes a paired controller.
	StableKey SourceKey
	// DeviceAddress names the physical device this endpoint belongs to,
	// in the owner's own namespace. Carried through to
	// [Endpoint.DeviceAddress], where it is what
	// [Bridge.NotifyDeviceReachable] fans a device-level signal out
	// over. Empty when the owner has no such notion.
	DeviceAddress string
	// DeviceType is the Matter Device Type ID the endpoint advertises
	// as its primary type (e.g. 0x010A OnOffPlugInUnit).
	DeviceType uint16
	// VendorName is the bridged device's manufacturer, served as its
	// BridgedDeviceBasicInformation VendorName (capped at the attribute's
	// 32 bytes). The vendor is the host's knowledge, never the module's.
	// Empty serves the node's own VendorName ([Config.VendorName]).
	VendorName string
	// FriendlyName is the finished BridgedDeviceBasicInformation
	// NodeLabel. The assembly caps it at the Matter 32-byte maximum but
	// never derives it — naming is the owner's authority.
	FriendlyName string
	// ChannelAddress is the source's address in the owner's own
	// namespace, carried through verbatim for diagnostics
	// ([Endpoint.ChannelAddress]). Empty when the owner has no such
	// notion.
	ChannelAddress string
	// Availability probes the source's live reachability. nil reads as
	// permanently reachable.
	Availability AvailabilityProbe
	// Source is the rich-model implementation of the endpoint's cluster
	// surface. nil for measurement-only endpoints, which carry
	// Measurement instead.
	Source contract.EndpointSource
	// Measurement is set on sensor endpoints assembled from a
	// measurement source. nil otherwise. With Source also set (a
	// device-layer device built with device.WithMeasurement), the
	// clusters it materialises follow the source's own.
	Measurement contract.MeasurementSource
	// NodeLabel is a BridgedDeviceBasicInformation NodeLabel a controller
	// wrote in an earlier run and the host persisted through
	// [Config.OnNodeLabelWritten]. Empty serves FriendlyName until a
	// controller writes one.
	NodeLabel string
	// ConfigurationVersion is the bridged device's
	// BridgedDeviceBasicInformation ConfigurationVersion as the host last
	// persisted it ([Endpoint.IncreaseConfigurationVersion] returns each new
	// value). Zero serves 1. The version may never decrease, so a host that
	// raises it keeps it across restarts — matter.js persists it as state.
	ConfigurationVersion uint32
	// PowerSource carries a battery reading to be served by the
	// PowerSource cluster (0x002F) on this endpoint. At most one
	// endpoint per physical device sets it — see the assembly's
	// power-source placement rule.
	PowerSource contract.MeasurementSource
	// DeviceConditions are the device-type conditions the host states for
	// the endpoint ([Endpoint.DeviceConditions]); nil states none.
	DeviceConditions []string
	// ClientClusters are the client clusters the endpoint declares: the
	// Descriptor's ClientList, as matter.js MutableEndpoint.ts:53-61
	// registers a type's mandatory client clusters and
	// DescriptorServer.ts:290-296 lists them. nil declares none.
	ClientClusters []uint32
	// OptIn names the stack-mounted optional server clusters the endpoint
	// opts into: Groups (0x0004) and ScenesManagement (0x0062), which the
	// assembler mounts where the device type mandates them and, with this,
	// where the device type allows them as optional — matter.js's
	// `MutableEndpoint.with(GroupsServer)` adds a behavior to any endpoint
	// type (packages/node/src/endpoint/type/MutableEndpoint.ts:95-112). An
	// id the device type does not allow as a server cluster, and any other
	// id, is ignored. nil opts into nothing.
	OptIn []uint32
	// Parts are the endpoint's child endpoints — matter.js Endpoint
	// `parts` — such as the PowerSource (0x0011) component a SmokeCoAlarm
	// requires (matter.js examples/device-smoke-co-alarm). Each part is an
	// endpoint of its own: its StableKey (unique like any other) persists
	// its number, it sits in this endpoint's Descriptor PartsList and in
	// the Aggregator's full-family one, and its ParentEndpoint is this
	// endpoint. A part is a component, not a bridged node: its Descriptor
	// lists its DeviceType alone, it serves no BridgedDeviceBasicInformation,
	// and Identify only when its device type mandates it. Parts may carry
	// parts; FriendlyName, VendorName, NodeLabel and ConfigurationVersion
	// of a part are not served.
	Parts []Spec
}

type Store interface {
	// GetEndpoint returns the record for key, or [ErrNotFound].
	GetEndpoint(ctx context.Context, key SourceKey) (Record, error)
	// UpsertEndpointAssigning writes rec, allocating a fresh endpoint id
	// when rec.EndpointID is 0, and returns the effective id.
	UpsertEndpointAssigning(ctx context.Context, rec Record) (uint16, error)
	// ListEndpoints returns every record in scope, ascending by endpoint
	// id. An empty scope means "every scope".
	ListEndpoints(ctx context.Context, scope string) ([]Record, error)
	// RemoveEndpoint deletes the record for key. Idempotent: a missing
	// row is not an error, because the assembler's garbage collection
	// does not coordinate with concurrent removals.
	RemoveEndpoint(ctx context.Context, key SourceKey) error
}

type StringKey string

type Topology struct {
	// Endpoints is the assembled list. Index 0 is always the root
	// bridge endpoint; the rest are bridged endpoints sorted by
	// endpoint_id ascending.
	Endpoints []*Endpoint
	// VendorID is the bridge's IANA-assigned vendor identifier
	// (BasicInformation.VendorID, Matter §11.1.5.2).
	VendorID uint16
	// ProductID is the bridge's vendor-assigned product identifier
	// (BasicInformation.ProductID, Matter §11.1.5.4).
	ProductID uint16
	// NodeLabel is the bridge's user-visible label
	// (BasicInformation.NodeLabel, Matter §11.1.5.6).
	NodeLabel string
	// VendorName is the node's BasicInformation VendorName
	// ([Config.VendorName]).
	VendorName string
}

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

type UnenforcedACL struct{}

type ViolationKind string