Interface Graph<T>

Type Parameters:

T - model value type at the current graph placement

public interface Graph<T>

A typed view of one independently stored model and its lazily available relationship context.

Merely resolving a detached graph by ID does not load its model value. A typed ancestor can be resolved directly from relationship identities without loading either the source or intermediate parents. The source value, children, history and update context are loaded only when requested, at one pinned model-state boundary. Every returned child is itself a graph view, so root, parent, history and update operations remain available without exposing the persistence-only Entity wrapper.

When injected or synchronously loaded within a Model evaluation, inspected values and relationship collections become conflict dependencies on that evaluation's pinned boundary and owning repository/namespace. Empty child collections and examined/rejected filter candidates count too; merely loading a graph does not protect every descendant. Cached transformations retain their read evidence. Reads, including joined parallel scans, must finish within the synchronous evaluation. Explicit historical views and unrelated repository/search reads are not implicitly live dependencies. Membership protection is path-scoped (conservative across types); remapped paths protect all direct paths of their source. Matching relationship-read-capable SDK and Runtime versions are required. RETRY/FAIL validate the full evaluation readset; ACCEPT preserves only apply dependencies through rebase. Custom repositories must return SDK views (e.g. Graphs.compose(String, long, java.util.Map, java.util.List, io.fluxzero.sdk.persisting.repository.ModelRepository, boolean)) for transactional navigation. Opaque custom Graph implementations fail explicitly on that path; ordinary non-transactional reads remain supported.

As the single unqualified Graph parameter of an event or notification handler, optionally accompanied by Message and Metadata in any order, a graph subscribes to durable changes of that root and any descendant. The handler runs once per affected root and change boundary. previous() returns the graph directly before the change; a child move therefore invokes the handler once for the old root and once for the new root. One handler object may declare separate complete-change methods for different Graph<T> root types; each changed root is routed to its matching typed method. Cascaded deletions also reach a complete-change child-Graph handler, with an empty current root and its pre-deletion graph. Historical values require ModelPersistence.EVENT_SOURCED; ModelPersistence.DOCUMENT alone does not retain previous versions. Historical views use current DOCUMENT-only values when the historical version is unavailable. Use strict(true) or the application property fluxzero.model.graph.strict=true to require exact historical values.

A materialized graph retains the serialized type and revision of every root and descendant placement. The ordinary serializer upcasts each node independently and lazily when its value is accessed; there is no graph-wide revision or separate graph-upcaster contract. Returning a complete materialized graph from a @HandleDocument handler receiving Graph<T> can persist evolved schemas into verified current canonical nodes, including in GraphProjectionMode.NONE. Business values, relationships and history remain unchanged; affected projections follow durably. Select HandleDocument.graphMigration() with PROJECTION to migrate only a stored composition. NONE does not create a stored complete Graph. Metadata-first child selection does not reconstruct selected child values. The default repository also resolves lazy root aliases from head metadata without replay. Initial alias lookup uses the current alias table, including for historical reads; the resulting identity (or absence), values and relationships then stay pinned. Consumed alias lookups inside a Model mutation also participate in commit conflict detection, including missing aliases and metadata-only navigation. Exact-ID reads do not acquire alias dependencies. Custom repositories may retain value-based lookup. Remote alias navigation requires a Runtime transport that preserves canonical IDs in alias heads.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	Graph.Options	Optional caller-imposed graph reconstruction limits.

Method Summary

Modifier and Type	Method	Description
default Collection<?>	aliases()	Returns the model aliases without loading relationship context.
<A> Optional<Graph<A>>	ancestor(Class<A> ancestorType)	Returns the closest ancestor, including the current graph, assignable to the requested type.
default <A> Optional<A>	ancestorModel(Class<A> ancestorType)	Returns the value of the closest ancestor, including the current model, assignable to the requested type.
Graph<T>	apply(Message update)	Applies a complete message.
Graph<T>	apply(DeserializingMessage update)	Applies a deserializing message.
Graph<T>	apply(Object update)	Applies one update to this graph's current model and returns the staged resulting graph.
Graph<T>	apply(Object... updates)	Applies the supplied updates in order.
Graph<T>	apply(Object update, Metadata metadata)	Applies one update with explicit metadata.
Graph<T>	apply(Collection<?> updates)	Applies the supplied updates in order.
Graph<T>	assertAndApply(Object update)	Verifies and applies the supplied update.
default Graph<T>	assertAndApply(Object... updates)	Verifies and applies the supplied updates in order.
Graph<T>	assertAndApply(Object update, Metadata metadata)	Verifies and applies the supplied update with explicit metadata.
default Graph<T>	assertAndApply(Collection<?> updates)	Verifies and applies the supplied updates in order.
<E extends Exception> Graph<T>	assertLegal(Object update)	Verifies that the supplied update is legal and returns this graph.
Graph<T>	atStateIndex(long stateIndex)	Returns the same model graph reconstructed at the requested durable state boundary.
default <C> List<C>	childModels(Class<C> childType)	Returns direct child values of the requested type.
default <C> List<C>	childModels(String path, Class<C> childType)	Returns direct child values placed at the requested explicit relationship path.
default List<String>	childPaths()	Returns the declared serialized child paths in deterministic order, including paths that currently have no children.
List<Graph<?>>	children()	Returns all direct children in deterministic relationship-path order.
<C> List<Graph<C>>	children(Class<C> childType)	Returns direct children assignable to the requested locally known type, without reconstructing values.
default List<Graph<?>>	children(String path)	Returns locally known direct children at the exact relationship path; null selects pathless children.
default List<Graph<?>>	children(String path, boolean knownOnly)	Returns direct children at the exact relationship path without loading values.
<C> List<Graph<C>>	children(String path, Class<C> childType)	Returns direct children placed at the requested explicit relationship path.
default List<Graph<?>>	children(String path, String modelName)	Returns locally known direct children matching an exact relationship path and resolved logical Model name.
default List<Graph<?>>	children(String path, String modelName, boolean knownOnly)	Combines exact path and logical-name selection.
Graph<T>	commit()	Explicitly commits staged changes.
default boolean	compareAndSet(T replacement)	Replaces this existing Model only if this graph's revisionStateIndex() is still current.
default <C> Optional<C>	context(Class<C> contextType)	Returns response context assignable to the requested type, if attached to this graph view.
default Graph<T>	current()	Opens a new, deliberately current view of this Model using its exact repository identity and owning repository.
default Map<String, DeadlineInfo>	deadlines()	Returns the immutable deadline categories recorded with this Model revision.
default Graph<T>	delete()	Marks this model as deleted and returns the staged resulting graph.
default <D> List<D>	descendantModels(Class<D> descendantType)	Returns all descendant values assignable to the requested type.
default <D> List<D>	descendantModels(String path, Class<D> descendantType)	Returns descendant values reached through the requested relationship path.
<D> List<Graph<D>>	descendants(Class<D> descendantType)	Returns locally known assignable descendants in deterministic graph order without reconstructing values.
default List<Graph<?>>	descendants(String path)	Returns locally known descendants at the root-relative relationship path, excluding this node.
default List<Graph<?>>	descendants(String path, boolean knownOnly)	Selects descendants at a root-relative relationship path without reading values.
<D> List<Graph<D>>	descendants(String path, Class<D> descendantType)	Returns descendants reached through the requested relationship path.
default List<Graph<?>>	descendants(String path, String modelName)	Returns locally known descendants matching a root-relative path and exact resolved logical Model name.
default List<Graph<?>>	descendants(String path, String modelName, boolean knownOnly)	Combines descendant path and exact logical-name selection.
default Graph<T>	filterBranches(Predicate<? super Graph<?>> predicate)	Returns an immutable response view containing every matching placement, its complete descendant branch and the ancestors needed to preserve its serialized path.
default Optional<Graph<T>>	filterGraph(Predicate<? super Graph<T>> predicate)	Returns this graph when it matches the supplied condition.
default Graph<T>	filterNodes(Predicate<? super Graph<?>> predicate)	Returns an immutable, lazy view whose model values are retained only when the supplied predicate accepts their graph placement.
default Optional<Graph<T>>	filterPresent()	Returns this graph only when its current model value is present.
default Optional<Graph<?>>	find(Object idOrAlias)	Finds a graph by exact persisted identity or alias.
default <M> Optional<Graph<M>>	find(Object idOrAlias, Class<M> modelType)	Finds a graph by functional identity or alias and expected model type.
default <M> Optional<Graph<M>>	find(Object idOrAlias, Class<M> modelType, GraphLookupPolicy lookupPolicy)	Finds a graph by functional identity or alias and expected model type using the supplied ambiguity policy.
default Optional<Graph<?>>	find(Predicate<? super Graph<?>> predicate)	Finds the first graph in deterministic graph order matching the supplied condition.
default String	functionalId()	Returns the public functional identity from the current model value or, for a deleted model, its latest available historical value.
T	get()	Returns the current model value, or null for a missing or deleted model.
default Graph<T>	getAndUpdate(UnaryOperator<Graph<T>> update)	Equivalent to getAndUpdate(UnaryOperator, int) with no retries.
default Graph<T>	getAndUpdate(UnaryOperator<Graph<T>> update, int maxRetries)	Like updateAndGet(UnaryOperator, int), but returns the graph immediately before the successful attempt.
default boolean	hasChanged(Function<? super T, ?> selector)	Returns whether the selected value differs from the preceding revision.
default Long	highestEventIndex()	Returns the newest event index retained by this graph's revision history.
Object	id()	Returns the exact collision-safe repository identity of this model.
default Graph<T>	ifPresent(UnaryOperator<Graph<T>> operation)	Applies a graph operation only when a current model value is present.
default boolean	isEmpty()	Returns whether this graph currently represents a missing or deleted model.
default boolean	isPresent()	Returns whether this graph currently contains a model value.
default boolean	isRoot()	Returns whether this graph is the outer root of its current graph view.
default boolean	isStrict()	Returns this view's configured historical read policy without loading values or relationships.
default Optional<Class<T>>	knownType()	Returns the locally known Model class without loading its value, or an empty optional for an unknown node.
String	lastEventId()	Returns the last globally published event identifier visible to this model revision.
Long	lastEventIndex()	Returns the last globally published event index visible to this model revision.
default <R> Optional<R>	map(Function<? super T, ? extends R> mapper)	Maps the current model value when present without loading relationship context.
default <R> Optional<R>	mapGraph(Function<? super Graph<T>, ? extends R> mapper)	Maps this graph itself without loading relationship context.
default <R> Optional<R>	mapIfPresent(Function<? super Graph<T>, ? extends R> mapper)	Maps this graph only when its current model value is present.
default String	modelName()	Returns the resolved logical Model name, including its configured prefix.
default List<Graph<?>>	namedChildren(String modelName)	Returns locally known direct children with this exact resolved logical Model name, across all paths.
default List<Graph<?>>	namedChildren(String modelName, boolean knownOnly)	Selects a logical Model name across all direct paths.
default List<Graph<?>>	namedDescendants(String modelName)	Returns locally known descendants of this exact resolved logical Model name, across all paths.
default List<Graph<?>>	namedDescendants(String modelName, boolean knownOnly)	Selects descendants by logical Model name across every path, optionally including unknown metadata nodes.
default Optional<T>	optional()	Returns the current model value as an optional without loading relationship context.
default T	orElse(T fallback)	Returns the current model value or the supplied fallback.
default T	orElseGet(Supplier<? extends T> fallback)	Returns the current model value or obtains a fallback lazily.
default T	orElseThrow()	Returns the current model value or throws when this graph is empty.
default <X extends Throwable> T	orElseThrow(Supplier<? extends X> exceptionSupplier)	Returns the current model value or throws the supplied exception when this graph is empty.
Optional<Graph<?>>	parent()	Returns the parent of this concrete graph placement, if one exists.
<P> Optional<Graph<P>>	parent(Class<P> parentType)	Returns the closest parent assignable to the requested type.
default <P> Optional<P>	parentModel(Class<P> parentType)	Returns the value of the closest parent assignable to the requested type.
default List<Graph<?>>	parents()	Returns all direct parents of this model.
Optional<Graph<T>>	playBackToCondition(Predicate<Graph<T>> condition)	Plays back to the first retained revision matching the supplied condition.
Optional<Graph<T>>	playBackToEvent(Long eventIndex, String eventId)	Plays back to the first retained revision matching the supplied event boundary.
Graph<T>	previous()	Returns the preceding model revision as a lazy graph, or null when none is available.
default <V> V	previousValue(Function<? super T, V> selector)	Returns the selected value from the preceding revision, or null when unavailable.
default void	reindex()	Refreshes this Model node's canonical search source from current committed state, even on a historical view.
String	relationshipPath()	Returns the parent-relative relationship path, or null for a pathless, standalone, or root view.
default Stream<Graph<T>>	revisions()	Returns the current and preceding revisions, newest first, excluding the empty state before creation.
default long	revisionStateIndex()	Returns the namespace-wide state boundary at which this concrete model revision became current.
Graph<?>	root()	Returns the outer graph root.
default Graph<T>	selectPaths(String... paths)	Returns an immutable graph view containing only the selected serialized relationship paths, relative to this graph, and their ancestors.
default Graph<T>	selectPaths(Collection<String> paths)	See selectPaths(String...).
long	sequenceNumber()	Returns the model-local sequence number, using pinned head evidence without replay when available.
long	stateIndex()	Returns the pinned namespace-wide model-state boundary.
default Stream<Graph<?>>	stream()	Lazily traverses this graph in deterministic pre-order, including this graph itself.
default Graph<T>	strict(boolean strict)	Returns a view with the requested historical read policy, leaving this view unchanged.
Instant	timestamp()	Returns the timestamp of this model revision.
Class<T>	type()	Returns the concrete Model type, failing explicitly for an unknown metadata node.
Graph<T>	update(UnaryOperator<T> update)	Updates the current value directly.
default Graph<T>	updateAndGet(UnaryOperator<Graph<T>> update)	Equivalent to updateAndGet(UnaryOperator, int) with no retries.
default Graph<T>	updateAndGet(UnaryOperator<Graph<T>> update, int maxRetries)	Updates one existing Model from a fresh transactional Graph and returns its committed resulting view.
default Graph<T>	withContext(Object... values)	Returns an immutable graph view carrying typed response context for graph-derived properties.

Method Details

get

@Nullable
T get()

Returns the current model value, or null for a missing or deleted model. An unknown metadata node fails explicitly instead of masquerading as absent; inspect knownType() before accessing its value.

isPresent

default boolean isPresent()

Returns whether this graph currently contains a model value.

isEmpty

default boolean isEmpty()

Returns whether this graph currently represents a missing or deleted model.

optional

default Optional<T> optional()

Returns the current model value as an optional without loading relationship context.

mapGraph

default <R> Optional<R> mapGraph(Function<? super Graph<T>, ? extends R> mapper)

Maps this graph itself without loading relationship context.

filterGraph

default Optional<Graph<T>> filterGraph(Predicate<? super Graph<T>> predicate)

Returns this graph when it matches the supplied condition.

filterPresent

default Optional<Graph<T>> filterPresent()

Returns this graph only when its current model value is present.

withContext

default Graph<T> withContext(Object... values)

Returns an immutable graph view carrying typed response context for graph-derived properties.

Context is shared by the complete graph view, including its parents, children and historical revisions. It does not become part of model state and is not loaded or persisted by the SDK. This makes it suitable for one response-wide, already-batched lookup that several @GraphProperty methods consume without introducing per-node I/O.

context

default <C> Optional<C> context(Class<C> contextType)

Returns response context assignable to the requested type, if attached to this graph view.

mapIfPresent

default <R> Optional<R> mapIfPresent(Function<? super Graph<T>, ? extends R> mapper)

Maps this graph only when its current model value is present.

map

default <R> Optional<R> map(Function<? super T, ? extends R> mapper)

Maps the current model value when present without loading relationship context.

strict

default Graph<T> strict(boolean strict)

Returns a view with the requested historical read policy, leaving this view unchanged. True requires exact historical values and fails if a DOCUMENT-only revision is unavailable. False uses the current value of that ID when its historical revision is unavailable, including a recreation, or null after deletion. Historical relationships and proven absence remain pinned. Each value is retained after its first read; different nodes do not form an atomic current snapshot. The choice follows parents, children and previous views. Event-sourced replay errors remain errors; mutations, assertions and replay always stay strict. An older Runtime may still reject a historical read when it cannot return the required head metadata, regardless of this policy. Upgrading the SDK first does not require changing this view setting.

Parameters:

strict - whether the returned view requires exact historical values

Returns:

a view with the requested policy

isStrict

default boolean isStrict()

Returns this view's configured historical read policy without loading values or relationships. Mutations, assertions and replay always require strict reads, regardless of this view setting. Custom Graph implementations without a configurable policy remain strict by default.

orElse

default T orElse(T fallback)

Returns the current model value or the supplied fallback.

orElseGet

default T orElseGet(Supplier<? extends T> fallback)

Returns the current model value or obtains a fallback lazily.

orElseThrow

default T orElseThrow()

Returns the current model value or throws when this graph is empty.

orElseThrow

default <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier)
                                     throws X

Returns the current model value or throws the supplied exception when this graph is empty.

Throws:

X

ifPresent

default Graph<T> ifPresent(UnaryOperator<Graph<T>> operation)

Applies a graph operation only when a current model value is present.

id

Object id()

Returns the exact collision-safe repository identity of this model.

functionalId

@Nullable
default String functionalId()

Returns the public functional identity from the current model value or, for a deleted model, its latest available historical value.

This deliberately differs from id(), which can contain an EntityId prefix, postfix or parent scope used only for durable repository identity. A model that has never existed has no functional identity and returns null.

type

Class<T> type()

Returns the concrete Model type, failing explicitly for an unknown metadata node. See knownType().

modelName

default String modelName()

Returns the resolved logical Model name, including its configured prefix. Unlike type(), this is available for an unknown node returned by metadata navigation and does not require its Java contract.

knownType

default Optional<Class<T>> knownType()

Returns the locally known Model class without loading its value, or an empty optional for an unknown node. A known class does not guarantee that its historical event contracts or replay logic are available.

aliases

default Collection<?> aliases()

Returns the model aliases without loading relationship context.

relationshipPath

@Nullable
String relationshipPath()

Returns the parent-relative relationship path, or null for a pathless, standalone, or root view.

stateIndex

long stateIndex()

Returns the pinned namespace-wide model-state boundary.

revisionStateIndex

default long revisionStateIndex()

Returns the namespace-wide state boundary at which this concrete model revision became current.

Unlike stateIndex(), which describes the pinned boundary shared by the complete graph, this value can differ between nodes and therefore provides a stable ordering for otherwise ambiguous functional-ID lookups. For still-lazy persisted nodes, a metadata-capable repository can provide this from the pinned head without reconstructing the value. Pending and custom graph revisions retain their own version semantics.

lastEventId

@Nullable
String lastEventId()

Returns the last globally published event identifier visible to this model revision.

lastEventIndex

@Nullable
Long lastEventIndex()

Returns the last globally published event index visible to this model revision.

sequenceNumber

long sequenceNumber()

Returns the model-local sequence number, using pinned head evidence without replay when available.

deadlines

default Map<String, DeadlineInfo> deadlines()

Returns the immutable deadline categories recorded with this Model revision. Values describe planned times, not scheduler execution or external cancellation. Reading them never evaluates declarations or schedules work. Custom Graphs without deadline metadata return an empty map.

timestamp

Instant timestamp()

Returns the timestamp of this model revision.

root

Graph<?> root()

Returns the outer graph root. On a root graph this returns this.

isRoot

default boolean isRoot()

Returns whether this graph is the outer root of its current graph view.

parent

Optional<Graph<?>> parent()

Returns the parent of this concrete graph placement, if one exists.

parents

default List<Graph<?>> parents()

Returns all direct parents of this model. A concrete placement normally has one parent, while a directly loaded model may expose multiple declared Parent relationships.

parent

<P> Optional<Graph<P>> parent(Class<P> parentType)

Returns the closest parent assignable to the requested type.

parentModel

default <P> Optional<P> parentModel(Class<P> parentType)

Returns the value of the closest parent assignable to the requested type.

ancestor

<A> Optional<Graph<A>> ancestor(Class<A> ancestorType)

Returns the closest ancestor, including the current graph, assignable to the requested type. The concrete graph placement is searched before alternate parent branches.

ancestorModel

default <A> Optional<A> ancestorModel(Class<A> ancestorType)

Returns the value of the closest ancestor, including the current model, assignable to the requested type.

children

List<Graph<?>> children()

Returns all direct children in deterministic relationship-path order.

children

default List<Graph<?>> children(String path)

Returns locally known direct children at the exact relationship path; null selects pathless children.

children

default List<Graph<?>> children(String path,
 boolean knownOnly)

Returns direct children at the exact relationship path without loading values. knownOnly=true excludes locally unknown types and is not a complete count of all children. False includes unknown metadata nodes: their identity and relationships remain available, but get(), type() and mutations fail. A null path selects only pathless children. Inspected memberships, including empty results, are tracked.

children

default List<Graph<?>> children(String path,
 String modelName)

Returns locally known direct children matching an exact relationship path and resolved logical Model name.

children

default List<Graph<?>> children(String path,
 String modelName,
 boolean knownOnly)

Combines exact path and logical-name selection. Null names impose no name filter; null paths select pathless children. Names are already resolved, including any application prefix. See children(String, boolean).

namedChildren

default List<Graph<?>> namedChildren(String modelName)

Returns locally known direct children with this exact resolved logical Model name, across all paths.

namedChildren

default List<Graph<?>> namedChildren(String modelName,
 boolean knownOnly)

Selects a logical Model name across all direct paths. False also includes locally unknown metadata nodes.

descendants

default List<Graph<?>> descendants(String path)

Returns locally known descendants at the root-relative relationship path, excluding this node.

descendants

default List<Graph<?>> descendants(String path,
 boolean knownOnly)

Selects descendants at a root-relative relationship path without reading values. Unknown intermediate nodes do not hide reachable matches. True selects only locally known types; false also returns unknown nodes. A null path selects every reachable path. Membership reads remain pinned and conflict tracked.

descendants

default List<Graph<?>> descendants(String path,
 String modelName)

Returns locally known descendants matching a root-relative path and exact resolved logical Model name.

descendants

default List<Graph<?>> descendants(String path,
 String modelName,
 boolean knownOnly)

Combines descendant path and exact logical-name selection. See descendants(String, boolean).

namedDescendants

default List<Graph<?>> namedDescendants(String modelName)

Returns locally known descendants of this exact resolved logical Model name, across all paths.

namedDescendants

default List<Graph<?>> namedDescendants(String modelName,
 boolean knownOnly)

Selects descendants by logical Model name across every path, optionally including unknown metadata nodes.

childPaths

default List<String> childPaths()

Returns the declared serialized child paths in deterministic order, including paths that currently have no children. Pathless relationships are deliberately absent because they are graph context rather than JSON structure.

selectPaths

default Graph<T> selectPaths(String... paths)

Returns an immutable graph view containing only the selected serialized relationship paths, relative to this graph, and their ancestors. Model values and graph nodes are shared with this graph; no models are copied or loaded merely by creating the view. Metadata-capable repositories select paths before reconstructing any values. An empty selection returns this graph unchanged.

selectPaths

default Graph<T> selectPaths(Collection<String> paths)

See selectPaths(String...).

filterNodes

default Graph<T> filterNodes(Predicate<? super Graph<?>> predicate)

Returns an immutable, lazy view whose model values are retained only when the supplied predicate accepts their graph placement. Rejected descendants remain structurally addressable as empty graphs but are omitted during graph serialization; accepted values are shared and never copied. A caller that retains a deep descendant should also retain its serialized ancestors.

filterBranches

default Graph<T> filterBranches(Predicate<? super Graph<?>> predicate)

Returns an immutable response view containing every matching placement, its complete descendant branch and the ancestors needed to preserve its serialized path. This is useful for selecting independently addressed branches: matching a parent retains its whole subtree, while matching a leaf retains only that leaf and its ancestors. The graph is traversed once; retained model values are shared and never copied.

children

<C> List<Graph<C>> children(Class<C> childType)

Returns direct children assignable to the requested locally known type, without reconstructing values. Unknown logical types are not matches, including for Object.class. Multiple matching relationship paths require the explicit-path overload.

children

<C> List<Graph<C>> children(String path,
 Class<C> childType)

Returns direct children placed at the requested explicit relationship path.

childModels

default <C> List<C> childModels(Class<C> childType)

Returns direct child values of the requested type.

childModels

default <C> List<C> childModels(String path,
 Class<C> childType)

Returns direct child values placed at the requested explicit relationship path.

descendants

<D> List<Graph<D>> descendants(Class<D> descendantType)

Returns locally known assignable descendants in deterministic graph order without reconstructing values. Unknown intermediate nodes are traversed but are never type matches, including for Object.class.

descendants

<D> List<Graph<D>> descendants(String path,
 Class<D> descendantType)

Returns descendants reached through the requested relationship path.

descendantModels

default <D> List<D> descendantModels(Class<D> descendantType)

Returns all descendant values assignable to the requested type.

descendantModels

default <D> List<D> descendantModels(String path,
 Class<D> descendantType)

Returns descendant values reached through the requested relationship path.

stream

default Stream<Graph<?>> stream()

Lazily traverses this graph in deterministic pre-order, including this graph itself. Relationship context is loaded only when the returned stream is consumed.

find

default Optional<Graph<?>> find(Predicate<? super Graph<?>> predicate)

Finds the first graph in deterministic graph order matching the supplied condition.

find

default Optional<Graph<?>> find(Object idOrAlias)

Finds a graph by exact persisted identity or alias. Exact identities take precedence over aliases throughout the complete graph, even when an earlier graph owns a colliding alias. Metadata-capable repositories search identities before reading alias values. Unknown Model nodes can be found by exact identity; inspecting their aliases still requires their local contract.

find

default <M> Optional<Graph<M>> find(Object idOrAlias,
 Class<M> modelType)

Finds a graph by functional identity or alias and expected model type. The expected type applies the same EntityId and nested Id affixes as a typed model load. The expected type participates in local Model discovery; unrelated unknown types are excluded. Alias matching and parent-scoped functional-ID matching may require values of matching types, never unrelated model values.

find

default <M> Optional<Graph<M>> find(Object idOrAlias,
 Class<M> modelType,
 GraphLookupPolicy lookupPolicy)

Finds a graph by functional identity or alias and expected model type using the supplied ambiguity policy. Exact identities take precedence over aliases throughout the complete graph.

apply

Graph<T> apply(Object update)

Applies one update to this graph's current model and returns the staged resulting graph.

apply

Graph<T> apply(Object update,
 Metadata metadata)

Applies one update with explicit metadata.

apply

Graph<T> apply(DeserializingMessage update)

Applies a deserializing message.

apply

Graph<T> apply(Message update)

Applies a complete message.

apply

Graph<T> apply(Object... updates)

Applies the supplied updates in order.

apply

Graph<T> apply(Collection<?> updates)

Applies the supplied updates in order.

update

Graph<T> update(UnaryOperator<T> update)

Updates the current value directly. When returned by an apply interceptor, the staged update joins that interceptor's atomic model commit and is replayed against fresh state after an accepted conflict. The operator must therefore be deterministic and free of external side effects. Prefer apply(Object) for domain updates whose apply-specific event publication settings should govern the transition.

compareAndSet

default boolean compareAndSet(@Nullable
 T replacement)

Replaces this existing Model only if this graph's revisionStateIndex() is still current. A null replacement deletes the Model. Returns only after durable commit; false means the expected revision was absent or conflicted. Technical failures still propagate. No retry is performed. Even an equal replacement writes a new revision, so comparison is always verified by storage. This independent operation is not allowed inside a Model mutation or on a staged/custom Graph. Uses the application's configured namespace; consumer namespace overrides are not supported. This is a direct state replacement, not an invocation of payload apply handlers or their assertions.

updateAndGet

default Graph<T> updateAndGet(UnaryOperator<Graph<T>> update)

Equivalent to updateAndGet(UnaryOperator, int) with no retries.

updateAndGet

default Graph<T> updateAndGet(UnaryOperator<Graph<T>> update,
 int maxRetries)

Updates one existing Model from a fresh transactional Graph and returns its committed resulting view. The function must return a same-target graph produced with update(UnaryOperator) or delete(), or its input unchanged. All consumed Graph values and relationships participate in conflict validation. On a rejected storage commit the function may run again, at most maxRetries additional times; do not perform external effects in it. Application failures and unavailable pinned document history are not retried. An absent Model is never implicitly created. Equal values still write a checked revision. This is an independently durable operation, not a nested part of a surrounding Model mutation. It reads committed state, not provisional changes from other commands in the current batch. Uses the application's configured namespace; consumer namespace overrides are not supported. This directly replaces state; run required validation in the function, without nested writes. Return new immutable values: never modify a cached input value in place, even if the commit later fails. Returned root values and revisions are retained. Lazy related-state reads still require available history.

Parameters:

update - side-effect-free transformation of the fresh graph

maxRetries - maximum additional attempts after storage conflicts, nonnegative

Returns:

the exact successful commit's view, not a subsequent current load

Throws:

NoSuchElementException - if the selected Model is absent at an attempt's read boundary

getAndUpdate

default Graph<T> getAndUpdate(UnaryOperator<Graph<T>> update)

Equivalent to getAndUpdate(UnaryOperator, int) with no retries.

getAndUpdate

default Graph<T> getAndUpdate(UnaryOperator<Graph<T>> update,
 int maxRetries)

Like updateAndGet(UnaryOperator, int), but returns the graph immediately before the successful attempt. No old value is released before commit succeeds. This can implement consume-once with graph.getAndUpdate(Graph::delete); it does not make an external side effect atomic with deletion.

delete

default Graph<T> delete()

Marks this model as deleted and returns the staged resulting graph. Return it from model handling so it joins the surrounding commit, or call commit() for an explicit graph operation.

commit

Graph<T> commit()

Explicitly commits staged changes. Normal handler processing commits automatically.

reindex

default void reindex()

Refreshes this Model node's canonical search source from current committed state, even on a historical view. Descendants are selected separately by the caller. No business event, history, relationship or Model head changes. Staged changes in this Graph or handler are ignored. Missing/deleted Models are a no-op.

A bounded consumer's fixed maxIndexExclusive is used to skip sources stored on/after its time cutoff, before reconstructing the Model. Stop and drain old writers/materializations before choosing that cutoff; thereafter all writers must use the intended configuration and comparable clocks. Future/nonpositive cutoffs are rejected. Without a bounded consumer every call refreshes the source.

Completion confirms durable source storage and targeted projection invalidation. For affected AWAIT projections, including ancestor roots, it also waits until the updated projection is queryable, even when the cutoff skips the source write. Completion follows consumer, Model projection mode and application default precedence, just like a normal commit. Other derived work continues asynchronously. The wait holds no Model write lock. Conflicts retry a bounded number of times and then fail for caller retry. A compatible Runtime is required; unsupported servers fail rather than falling back to ordinary indexing.

assertLegal

<E extends Exception> Graph<T> assertLegal(Object update)
                                    throws E

Verifies that the supplied update is legal and returns this graph.

Throws:

E

assertAndApply

Graph<T> assertAndApply(Object update)

Verifies and applies the supplied update. For an independent Model, applies are restricted to the selected Model type and Model-owned handlers retain their target filtering. Assertions on the update payload run, including assertions that read other Models; their reads participate in the configured conflict policy. Returns after the selected model commit is durable; payload IDs do not replace this graph's explicit identity. Interceptor payload transformations retain that identity, while returning an explicit Message starts a separately routed update. Aggregate-backed graphs retain their surrounding aggregate lifecycle.

assertAndApply

Graph<T> assertAndApply(Object update,
 Metadata metadata)

Verifies and applies the supplied update with explicit metadata.

assertAndApply

default Graph<T> assertAndApply(Object... updates)

Verifies and applies the supplied updates in order.

assertAndApply

default Graph<T> assertAndApply(Collection<?> updates)

Verifies and applies the supplied updates in order.

current

default Graph<T> current()

Opens a new, deliberately current view of this Model using its exact repository identity and owning repository. The new namespace boundary is pinned during this call, ignoring an active event-handler boundary. Event-sourced values and relationships remain lazy; a DOCUMENT-only root is coherently read and retained during this call. Like Fluxzero.loadCurrentGraph(Object, Class), the view captures the current message-batch overlay. It is not a continuously updating view and does not modify this graph or commit its edits.

The result is rooted at this Model, even when this node was reached through a parent. Reparenting is reflected in its new navigation; a deleted Model has an empty value. View-only path selections, filters, mapped values and response context are not carried over: reapply those deliberately to the new view.

Requires a locally known Model type and repository support for exact-identity current reads. Custom Graphs may override this method; the default fails rather than silently switching repositories or read boundaries.

Within a mutation on this repository/namespace, the view joins that active attempt's pinned boundary, staged values and inspected read dependencies; it does not open a second snapshot. Outside mutations it has no transaction provenance and deliberately opens the fresh boundary described above.

Throws:

UnsupportedOperationException - if this Graph or its repository cannot open such a view

IllegalStateException - if this node's Model type is unknown locally

previous

@Nullable
Graph<T> previous()

Returns the preceding model revision as a lazy graph, or null when none is available. Ordinary history ends at the creation revision: the empty state before creation is not a revision. Deletion revisions remain available even though their value is null. This Graph contract does not change the legacy Entity.previous() contract. Surrounding models and relationships are resolved immediately before the current revision became effective. This keeps children added after the preceding root revision visible while excluding changes made by the update whose before-state is being observed. A complete-change handler's explicit before-state takes precedence over retained model revisions: creation has no previous graph, including when a deleted identity is recreated or a node is absent at that boundary.

Event-sourced history can reconstruct prior values independently of cache depth. DOCUMENT-only persistence stores current state, not document versions: it does not provide durable prior values after overwrite. A complete-change handler's explicit before-boundary cannot create missing history for any inspected node. Ordinary historical Graph reads traverse preceding DOCUMENT-only coordination revisions using the current value when an old version is unavailable; their values are not historical document versions. When an older Runtime reports that this preceding head is unavailable, the retained predecessor is used, or null when none is retained, preserving the behavior before metadata-based traversal.

If an event-sourced revision has no cached predecessor, the repository reconstructs its historical before-state lazily, including when the current revision was loaded from a snapshot. Custom repositories must support historical Graph reads for this fallback.

Throws:

UnsupportedOperationException - if reconstruction is needed but the repository does not support it

revisions

default Stream<Graph<T>> revisions()

Returns the current and preceding revisions, newest first, excluding the empty state before creation. An empty model that has never existed has no revisions; non-empty provisional views remain included. A deletion is a real revision whose value is null; it remains in the stream. Traversal is lazy and may reconstruct history independently of cache depth.

Stored revisions include SDK-owned metadata changes, such as an ancestor-triggered deadline cancellation, even when get() is unchanged. Use sequenceNumber() or revisionStateIndex() for revision identity, not an application-owned version property. To select a business history, filter with hasChanged(Function) on the relevant property before limiting the result. Such filtering may traverse more stored revisions than the number of returned rows.

highestEventIndex

@Nullable
default Long highestEventIndex()

Returns the newest event index retained by this graph's revision history.

atStateIndex

Graph<T> atStateIndex(long stateIndex)

Returns the same model graph reconstructed at the requested durable state boundary.

playBackToEvent

Optional<Graph<T>> playBackToEvent(Long eventIndex,
 String eventId)

Plays back to the first retained revision matching the supplied event boundary.

playBackToCondition

Optional<Graph<T>> playBackToCondition(Predicate<Graph<T>> condition)

Plays back to the first retained revision matching the supplied condition.

hasChanged

default boolean hasChanged(Function<? super T, ?> selector)

Returns whether the selected value differs from the preceding revision.

previousValue

@Nullable
default <V> V previousValue(Function<? super T, V> selector)

Returns the selected value from the preceding revision, or null when unavailable.