API reference

IntrospectionRegistry Object

In-process, pull-only, read-only introspection registry.

Subsystems publish Nodes exposing counters, gauges, and info strings under a hierarchical /aether/<subsystem>/... path. Consumers (dumpsys adapter, AI agents, tests) discover and read nodes by path or prefix.

Zero overhead on the update path. The registry holds only the Node.reader closure; subsystems own their storage and increment counters with no registry call. Reading is on demand.

Thread safety. Reads use a ConcurrentHashMap and never block writers. Concurrent register/unregister/read calls are safe. Iteration in IntrospectionRegistry.list / IntrospectionRegistry.snapshot uses ConcurrentHashMap's weakly consistent iterator — entries added during iteration may or may not be observed, which is acceptable for introspection (sample-in-time semantics).

Production gating.IntrospectionRegistry.productionMode is read once from BuildConfig.DEBUG at class load (or via IntrospectionRegistry.setProductionModeForTesting). When true, Visibility.Debug nodes are filtered out from all read APIs. Default visibility for new nodes is Visibility.Debug — production exposure is opt-in.

Path semantics. Subtree matching is path-segment-aware: prefix /aether/demo matches /aether/demo and /aether/demo/foo but NOT /aether/demo2. The match treats the prefix as a sequence of /-delimited segments; the next character of a candidate path after the prefix must be either end-of-string or /.

clearForTesting ()	Test-only: remove all registered nodes. Signature fun clearForTesting()
list ( pathPrefix )	List metadata for all nodes whose path is in the subtree rooted at IntrospectionRegistry.list. Defaults to `/` (everything). Filters out Visibility.Debug nodes when IntrospectionRegistry.productionMode is true. Signature fun list(pathPrefix: String = "/"): List<NodeMetadata> Parameters `pathPrefix: String` Returns `List`
read ( path )	Read the current value at IntrospectionRegistry.read. Returns `null` if no node exists at the path or the node is filtered out by visibility. Signature fun read(path: String): Value? Parameters `path: String` Returns `Value?`
register ( node )	Register a IntrospectionRegistry.register keyed by its Node.path. Returns a Handle whose Handle.close removes the node. Throws IllegalStateException if a node already exists at this path. Signature fun register(node: Node): Handle Parameters `node: Node` Returns `Handle`
setProductionModeForTesting ( value )	Test-only override of the production-mode flag. Production code reads the flag from `BuildConfig.DEBUG` once at class load. Signature fun setProductionModeForTesting(value: Boolean) Parameters `value: Boolean`
snapshot ( pathPrefix )	Snapshot the current values of all nodes whose path is in the subtree rooted at IntrospectionRegistry.snapshot. Defaults to `/` (everything). Filters out Visibility.Debug nodes when IntrospectionRegistry.productionMode is true. Each reader is invoked exactly once. The returned map is a fresh copy and is safe to iterate. Signature fun snapshot(pathPrefix: String = "/"): Map<String, Value> Parameters `pathPrefix: String` Returns `Map`
unregister ( path )	Remove a single leaf node by exact IntrospectionRegistry.unregister. Returns `true` if a node was removed, `false` if no node existed at this path. Signature fun unregister(path: String): Boolean Parameters `path: String` Returns `Boolean`
unregisterSubtree ( prefix )	Remove every node whose path is in the subtree rooted at IntrospectionRegistry.unregisterSubtree. Returns the number of nodes removed. Path-segment-aware: `/aether/demo` matches `/aether/demo` and `/aether/demo/foo` but NOT `/aether/demo2/foo`. Signature fun unregisterSubtree(prefix: String): Int Parameters `prefix: String` Returns `Int`

IntrospectionRegistry Object

Signature

Methods