Reflection and hosts
Descriptors
DynamicObjects.property_descriptor Function
property_descriptor(T::Type, property::Symbol)Return a backward-safe, pure-data descriptor for one DynamicObjects property, or nothing when the type or property has no DO metadata. The result describes inputs/output, lifecycle semantics, option domains, and declared materialization without reading or computing an object property.
The descriptor's own domain is the domain of the property's value, and each entry of inputs carries the domain of that argument. Read the top-level one for a parameter a consumer sets — a fixed field, or an overrideable default like n_chain::Integer = 8, which is a computed property with no signature and therefore no inputs entry to hang a domain on. Every domain has one of three kinds:
:static— a finite domain the type proves (Bool, or anEnum), with the values inoptions.:declared— an@optionsdeclaration governs this parameter name; seeoption_declarations.domain.declarationis the record (declared expression, itsdependencies, andstatic);optionsis empty because reflection reports the declaration without running it. Callproperty_options(o, name)for the domain's actual value.:unrestricted— no domain is known; the type is the only constraint.
A domain's multiple is true exactly when the input is an AbstractVector (tags::Vector{String}): its value holds several elements, and the domain — declared or type-inferred — governs each ELEMENT. An @options(tags) declaration lists the allowed elements, and stages::Vector{Stage} for an Enum Stage reports the Stage instances as a :static domain. A consumer checks every element and offers a multiple-choice control.
DynamicObjects.property_descriptors Function
property_descriptors(T::Type)Return descriptors in declaration order. Duplicate property declarations are preserved so consumers can inspect multiple indexed signatures.
sourceDynamicObjects.type_descriptor Function
type_descriptor(T::Type)Type-level counterpart to property_descriptor: what a reflection consumer needs about the node as a whole, so "what is this thing called" has exactly one answer rather than one per consumer.
Returns (; type, name, description, options).
descriptionisT's own user-attached docstring, stripped, ornothingwhen none was attached. The auto-generated property-list docstring@dynamicstructinstalls as a?Tfallback is deliberately not reported: it is reference text, not a label.optionsisoption_declarations(T)— including any declaration whose parameter no input ofThappens to carry.
DynamicObjects.property_signature Function
property_signature(T::Type, prop::Symbol) -> Union{Nothing, NamedTuple}
property_signature(info::NamedTuple, mod::Module) -> NamedTupleStructured call signature for an indexed property, parsed from info.indices (the argument list the macro captured from the LHS call). The structured counterpart to property_source_info's stringy signature.
Two entry points:
property_signature(T, prop)— lookpropup inmeta(T)(first declaration, viametafirst) and parse it againstparentmodule(T). Returnsnothingifmeta(T)is undefined orpropisn't a property ofT.property_signature(info, mod)— parse an already-selectedmetainfo against modulemod, without re-looking it up. Use this when the caller holds a specific declaration. The key case is multi-verb / duplicate-name routes: several declarations can share one property name (e.g. a@getand a@postonuser), someta(T)carries duplicates andmetafirstwould collapse them to the first. Walkmetaall(T, prop)and call this per declaration. Always returns a (possibly empty)(; positional, kwargs).
Both yield (; positional, kwargs), where every entry is a NamedTuple (; name, type, required, default, vararg):
name::Union{Symbol,Nothing}— the argument name (nothingfor an anonymous::Tpositional).type::Union{Type,Nothing}— the annotation resolved againstmodbyDynamicObjects.resolve_annotation, ornothingwhen un-annotated OR unresolvable (e.g. a free static-parameter type-var like theVinVerb{V}). Consumers mapnothingto their permissive default (HTMXObjects →String). The answer is the same while a package image is written (a@compile_workload, or an__init__run while another package precompiles) as at run time, thoughmodis then closed to evaluation.required::Bool—trueunless the arg carries a default or is a vararg.default— the default-value expression whenrequired === false;nothing(and meaningless) whenrequired === true. A literalnothingdefault is told apart from "no default" only byrequired === false.vararg::Bool—truefor a splat (x.../x::T...), which is otherwise indistinguishable from a plain optional arg: both reportrequired=false. Consumers that build a call template need the difference (an open-endedpath...segment is not a single optionalpath).
A non-indexed property (no call signature) yields empty positional and kwargs. A vararg is unwrapped to its inner name/type with required=false and vararg=true.
Layering — intentionally verb-agnostic: this returns every positional arg, including any framework-injected leading arg (e.g. HTMXObjects' injected __verb__::Verb{V}). Filtering such args — and selecting which declaration a verb maps to — is the consumer's job. @param-derived properties are not indexed properties and carry no info.indices; their parsed shape lives in info.rhs and is the consumer's concern.
Pure data extraction. See also property_source_info.
DynamicObjects.property_source_info Function
property_source_info(T::Type, prop::Symbol)
-> Union{Nothing, NamedTuple{(:rhs_string, :signature, :macros, :dependson), …}}Extract a property's RHS expression, signature, macro chain, and dependson set from meta(T). Returns:
nothingifmeta(T)is undefined,(; rhs_string=:meta_missing, signature, …)if the prop isn't onT,otherwise a NamedTuple with:
rhs_string::String— the lnn-stripped expression as a string, or"(no rhs — forwarded/typed property)"ifinfo.rhs === nothing.signature::String—"name"or"name(arg, …)".macros::String—"@cached "etc. (trailing space if non-empty).dependson::Vector{Symbol}— sorted dependency names.
Pure data extraction. Renderers turn this into HTML / markdown / terminal output.
sourceDynamicObjects.property_doc Function
property_doc(info::NamedTuple)Return the property's declared docstring, or nothing. Obtain the declaration record with metafirst or metaall; this accessor computes no property value.
Domains
DynamicObjects.static_domain Function
static_domain(values; multiple=false, allow_custom=false)Normalize raw values or option records already available to a descriptor consumer. This is a framework-facing normalization helper, not an application authoring convention.
sourceDynamicObjects.option_declarations Function
option_declarations(::Type{T}) -> Vector{Pair{Symbol,NamedTuple}}Every @options(<parameter>) = <domain expression> declaration in T's body, in declaration order. A parameter may be declared only once: duplicate declarations are rejected where the @dynamicstruct is defined so reflection and the generated __options__(::Val{parameter}) method can never disagree.
@options declares which values a parameter may take. It is the one thing the structural descriptors cannot infer: a finite domain is proved by the type only for Bool and Enum, and a domain that depends on another input cannot be proved at all. Both spellings are accepted — @options(x) = … (the marker binds its parenthesized argument, so it sits on the assignment's LHS) and @options x = ….
A declaration lowers to the dunder indexed property __options__(::Val{x}), so the domain is an ordinary lazily computed DO value. Nothing is evaluated at macro-expansion time and nothing is evaluated by reflection: the expression runs only when a consumer asks for the value, via property_options. That is what lets a domain be written in terms of application functions and data DO knows nothing about, and it is why the value memoizes and invalidates like every other property.
This function reports the declarations. Each entry's NamedTuple carries:
parameter::Symbol— the input this domain governs. It is matched by name against every input ofT: a fixed field, a positional or keyword argument of an indexed property, or a fixed field promoted into an operation's:contextinputs. One declaration therefore covers every operation that takes that name.expression— the declared expression, verbatim and unevaluated.expression_string::String—string(expression), for display.dependencies::Vector{Symbol}— the sibling properties/fields the expression reads, from the samedependsonwalk every property RHS gets.static::Bool—isempty(dependencies):truewhen the domain is fixed for the type,falsewhen it is context-dependent and a consumer must re-read it whenever one ofdependencieschanges.source::Symbol— which declaration form produced this record (:options).lnn— the declaration'sLineNumberNode, ornothing.
The same records reach consumers through the descriptor graph: an input governed by a declaration reports domain.kind === :declared with the record under domain.declaration (see property_descriptor). Reading them here is for whole-type inspection — e.g. a declaration whose parameter no attached input happens to carry.
DynamicObjects.has_option_declaration Function
has_option_declaration(T::Type, parameter::Symbol) -> BoolWhether T declares an @options domain for parameter. The cheap check a consumer makes before property_options — it reads declarations only and never touches an object.
DynamicObjects.property_options Function
property_options(o, parameter::Symbol)The declared domain for parameter on this object — the value of the @options expression, computed against o and memoized like any other property. Returns nothing when no declaration governs parameter.
This is the evaluating half of the option contract, and it needs an object for the same reason a dependent domain exists at all: @options(model) = models_for(study) is only answerable once study is fixed, and study is fixed by o. Reflection (option_declarations, property_descriptor) reports the declaration without running it; this runs it.
A domain is any value supporting in — a vector of nodes, a range, an interval, a type. What a consumer does with it (membership check, control choice, rejecting a submission made against a stale domain) is the consumer's; DO neither interprets the value nor caches a rendering of it.
DynamicObjects.option_domain Function
option_domain(values)Wrap a finite collection as a domain with presentation metadata. Each entry may be a bare value, a value => label pair, or a record with value, label, group, help and disabled fields. Missing labels default to string(value). Membership is defined on the machine values, independently of their labels.
Use the result in an @options declaration. A dependent declaration recomputes when its inputs change. Reflection reports the declaration without evaluating it; read the evaluated domain through property_options, then use option_records for its per-value metadata.
DynamicObjects.option_records Function
option_records(domain) -> Vector{NamedTuple} or nothingThe option records of an evaluated domain — one (; value, label, group, help, disabled) per value, in domain order. Use these records to render an evaluated domain.
An option_domain returns its declared labels. Any other finite collection — a vector, tuple, range, or Set — is normalized with default labels (string(value)), so an unlabelled @options declaration still renders. Returns nothing for a domain that is not a finite collection (a type, an interval): there is no list to render, and the consumer falls back to a free input.
Structure
DynamicObjects.structure Function
structure(T::Type; max_depth=typemax(Int)) -> Node{:pre}Build a target-agnostic DOM-ish representation of T's DO/HTMXO tree. The root is a Node{:pre} so it renders as <pre class="do-structure">…</pre> in HTML, fenced ````` blocks in markdown, and bare indented text in the terminal. display(s) picks the right MIME for the active display.
DynamicObjects.print_structure Function
print_structure([io::IO=stdout,] T::Type; max_depth=typemax(Int))Convenience: show(io, MIME"text/plain"(), structure(T)). For markdown or HTML output, build the structure with structure(T) and show it under the desired MIME.
DynamicObjects.tree_children_map Function
tree_children_map(root::Type) -> Dict{Type, Vector{Tuple{Symbol, Type}}}Build a parent → [(prop_name, child_type), …] map for every DO/HTMXO type reachable from root. Children are sorted alphabetically by prop_name. The inverse of _build_parent_map. Pure data — no rendering.
DynamicObjects.lookup_type Function
lookup_type(root::Type, name::AbstractString) -> Union{Type, Nothing}Find a DO/HTMXO type in the tree rooted at root by its bare nameof string. Returns nothing if no match.
DynamicObjects.callers_by_name Function
callers_by_name(prop::Symbol, root::Type) -> Vector{Tuple{Type, Symbol, Vector{Any}}}Return every site (caller_type, caller_prop, arg_exprs) that calls a property named prop anywhere in the tree rooted at root. Matches by callee NAME, not by resolved owner type, so cross-type name collisions appear together. Backed by _build_call_index.
DynamicObjects.lint_index Function
lint_index(root::Type) -> Dict{Type, NamedTuple{(:warns, :errors, :msgs), …}}Group analyze_structure(root) output by LintMessage.type. Each entry carries warn/error counts and the underlying messages. Returns an empty Dict if analyze_structure throws (e.g. partially-defined tree).
DynamicObjects.LintMessage Type
LintMessageA declaration diagnostic returned by lint_index. Fields identify the type, optional prop, severity (:warn or :error), short and long messages, and optional source line node lnn. Rendering a structure exposes these diagnostics; defining a type does not print them automatically.
DynamicObjects.metafirst Function
metafirst(T, name::Symbol) -> Union{Nothing, NamedTuple}Return the first info for name in meta(T), or nothing if absent. Use when you expect at most one entry and don't care about duplicates.
DynamicObjects.metaall Function
metaall(T, name::Symbol) -> Vector{NamedTuple}Return all infos for name in meta(T) in declaration order. Empty if absent. Use when duplicates are expected (e.g. coexisting route + indexed include).
Declaration graphs
DynamicObjects.declaration_metadata Function
declaration_metadata(T::Type) -> NamedTuple
declaration_metadata(T::Type, ::Val{property}) -> NamedTuple
declaration_metadata(T::Type, ::Val{property}, ::Val{declaration}) -> NamedTupleExtension hook for declaration-site metadata that belongs on a type or property node in declaration_graph. The default is an empty NamedTuple.
A declaration macro in another package can emit a method beside the declaration it expands, just as a docstring attaches information to a binding. The three-argument form distinguishes duplicate declarations with the same property name; by default it falls back to the two-argument property method. Return only pure data. DynamicObjects stores the result verbatim under node.metadata.extensions and does not interpret its keys.
DynamicObjects.declaration_graph Function
declaration_graph(root::Type; contributions=())
declaration_graph(object; contributions=())Build a deterministic, non-evaluating application declaration graph from DynamicObjects metadata. The object overload reflects typeof(object); it does not read the object. The result is pure Julia data:
(; schema="dynamicobjects.declaration-graph/v1", root, nodes, edges, metadata)
root is the stable ID of the root :type node. Every node has at least (;id::String, kind::Symbol, label::String, metadata, fragment::String) and every edge at least (;id::String, kind::Symbol, from::String, to::String, metadata, fragment::String). DynamicObjects emits :type, :property, and :domain nodes, connected only by explicit :contains, direct :depends_on, and :describes relations. Property metadata includes its owner type ID, semantic name, duplicate-declaration occurrence, normalized semantic descriptor, structured signature, declaration extensions, and full captured source AST, code, and file/line provenance. Property and domain metadata also include dependency_analysis=(;opaque, missing, nested) for unresolved declared reads. Sibling dependency edges target every same-name declaration conservatively; the graph does not determine runtime dispatch. Use declaration_selection to select requirements and explicit boundaries without computing properties.
Each contribution is a pure-data (;namespace::String, nodes, edges) fragment using the same envelopes. Base DO data comes first; fragments and the node/edge vectors inside each fragment keep caller order. The namespace is recorded as fragment for provenance but never rewrites IDs. IDs must be globally unique across all nodes and edges; collisions (including with DO IDs) and dangling endpoints are rejected after every fragment is present, so cross-fragment edges may target later fragments.
Use declaration_node_id to connect external nodes to a DO declaration without depending on the spelling of DO IDs. Runtime state is deliberately not part of this graph; see declaration_observations.
DynamicObjects.declaration_node_id Function
declaration_node_id(graph, T::Type) -> Union{String,Nothing}
declaration_node_id(graph, T::Type, property::Symbol; declaration=1)
-> Union{String,Nothing}Look up stable DO node IDs without depending on their encoded spelling. The property form selects the one-based occurrence among same-name declarations.
sourceDynamicObjects.declaration_selection Function
declaration_selection(graph, roots; boundaries=())Select declarations without reading properties or executing their bodies. graph is a declaration_graph result; roots and boundaries are node ID strings (a single string is also accepted). Use declaration_node_id to identify DO declarations, and the contributed IDs for framework nodes.
Follow outgoing :depends_on and :describes edges. A reached explicit boundary is reported but its outgoing edges are not followed. For A → B → C, selecting A with boundary B requires A, reports B, and omits C; a separate local path to C still retains it. A root cannot also be a boundary. Boundary IDs which are not reached are omitted. Selections may overlap and need not exhaust the graph. Duplicate IDs in either input are harmless; unknown IDs are errors.
Return pure data with schema "dynamicobjects.declaration-selection/v1":
graph: the original graph's root ID;roots: normalized root IDs.required: IDs of the roots and their transitive local requirements.boundaries: IDs of the reached explicit boundaries, excluded fromrequired.context: additional ancestor IDs reached by following:containsbackwards. These preserve owner/mount context, not an assertion that their computations are selected. Containment never selects siblings or descendants, even for a type root. Select an owning/mount property as a root too when its computation must be included, rather than merely described.nodes: original records for the union of those three disjoint ID sets;edges: original edges whose endpoints are in that union. Their source, metadata and fragment provenance are preserved, with no rewriting of IDs.reasons:(;node, kind, from, edge)records for roots, traversed requirement edges, and containing context. A root hasfrom=edge=nothing; other reasons cite an original edge. These distinguish traversal from merely retained edges.unresolved:(;node, kind, dependency)diagnostics on local requirements. DO reports opaque self access, unrepresented dependency names, known nested/parent reads whose member-level requirements are not in the graph, and unavailable analysis from older graphs. Explicit boundaries suppress these diagnostics for the external node. Arbitrary helpers, runtime dispatch and effects are not inferred: an empty vector is not a proof of purity or whole-program completeness. Contributed nodes are governed by their supplied edges.
ID vectors, nodes and edges keep graph order, independent of input order. Reasons keep root order then edge order. Work is linear in graph size plus diagnostics; cycles terminate. Inputs are never mutated. Node and edge metadata remain shared read-only data; this is a plan, not executable source pruning or automatic remote-call rewriting. Same-name dependency declarations are retained conservatively because a declared edge does not determine runtime dispatch.
sourceDynamicObjects.declaration_observations Function
declaration_observations(
object, graph=declaration_graph(typeof(object)); calls=())Return a separate, non-computing runtime-state overlay:
(;schema="dynamicobjects.declaration-observations/v1", graph=graph.root, observations)
Each observation is keyed by a stable property node ID as (;node, call, observation). Fixed and scalar properties owned by the root type are observed automatically. Indexed properties are omitted unless calls contains an explicit (;node, args=(), kwargs=(;)) record; this avoids inventing a call key. Nodes owned by nested types and contributed nodes are omitted unless a future composer binds an object for them.
The implementation only calls materialization_observation, which inspects fields, memory caches, pending state, and existing disk paths without calling getproperty, an indexed property, or a property body.
DynamicObjects.materialization_observation Function
materialization_observation(object, property::Symbol, args...; kwargs...)Observe a property's current memory/disk/pending/progress state without computing that property. For disk-backed properties this resolves the ordinary DO cache path and inspects the file; it never creates or loads the target file.
sourceHost lifecycle
DynamicObjects.execute_materialization Function
execute_materialization(f, context, root)
execute_materialization(context, root) do
# explicitly selected DynamicObjects access mode
end
execute_materialization(context, root, target, property, args...; kwargs...)
execute_materialization(context, object, property, args...; kwargs...)Execute a DynamicObjects property under framework-owned storage governance. context is the pure-data (; scope, key, retention) record supplied by a semantic host; ordinary applications call their operations normally and never construct a store. root is the retained application root and target is the mounted object that owns property. For indexed properties, fetch selects synchronous or deferred execution; it reaches the property cache without entering the application argument key or automatic storage path.
The executor adds an active lease around the existing DO property machinery. For an ordinary property on a retained root it observes the actual result and automatically keeps small/cheap values in memory, serializes large or expensive values, and memory-maps large plain Arrays of supported isbits eltypes. Fresh request roots recompute across requests. The root's cache directory and its ownership marker are created only when a value is actually written to disk, so an execution that stores nothing — any fresh request root, the callback form, a result kept in memory — touches no files. Existing @fresh, @cached, and @mmap declarations remain compatibility overrides; applications do not need them for governed execution.
Governance covers exactly the executed property on target. Properties it reads while computing — siblings, nested DO objects, @struct children — run through their ordinary declaration-site semantics and are never automatically promoted; only the executed property's own returned value is observed.
The callback form applies the same active lease and root ownership while leaving value access to the semantic host. It performs no automatic storage read or write itself. Hosts use it with an explicit access mode such as fresh(property, args...) or maybeprogress!(progress, property, args...) when one operation must recompute without changing the property's declaration or its ordinary memoized value. The callback's return value is passed through, and its lease is released even if the callback throws.
DynamicObjects.release_materialization! Function
release_materialization!(context, root; reason=:released)Mark a retained semantic root as released by its provider. Cleanup is deferred until active executions finish and the root's shared cache becomes unreachable. An unknown or mismatched owner is reported as :unowned and nothing is deleted.
DynamicObjects.materialization_ownership Function
materialization_ownership(context, root)Inspect framework storage ownership without computing a property. Returns :unowned, :active, or :released, including lease/reachability and the derived cache identity/version used for fail-closed cleanup.
DynamicObjects.materialization_gc! Function
materialization_gc!()Collect storage owned by semantic roots that their provider has released and that are no longer reachable or executing. Framework lifecycle hooks call this opportunistically; applications do not need a cleanup loop. Cache directories that pre-date governance, are symlinks, or have conflicting ownership markers are preserved.
source