A Graph Lens provides an interpretive view of a Pattern as a graph structure.

The lens consists of: * scopePattern: The Pattern that defines the boundary for all graph operations. Only direct elements of this pattern are considered for graph structure. * testNode: A predicate determining which direct elements are nodes. All other graph concepts (relationships, walks) derive from this predicate.

Categorical Interpretation

Graph Lens provides a functorial interpretation where Pattern structures are transformed into graph interpretations. The transformation Pattern → Graph interpretation is functorial in nature.

Design Principles

1. Scope-bounded: All operations only consider direct elements of scopePattern
2. Single predicate foundation: Only testNode is required, all else derives
3. Context at construction: Predicate context captured when lens is created
4. Interpretation, not intrinsic: Graph structure is an interpretation, not a property of Pattern itself

Example

>>> let atomicLens = GraphLens pattern (\(Pattern _ els) -> null els)
>>> nodes atomicLens
[[a], [b], [c]]

Construct a GraphLens using a predicate to identify nodes.

This encapsulates the context for interpreting graph structure.

Extract all nodes from the graph lens.

Nodes are direct elements of scopePattern that satisfy the testNode predicate.

Time Complexity

O(n) where n is the number of direct elements in scopePattern

Example

>>> let lens = GraphLens pattern isAtomic
>>> nodes lens
[[a], [b], [c]]

Determine if a Pattern is a node according to the lens.

This is the context-aware version that uses the lens's testNode predicate. The lens parameter provides the predicate context.

Example

>>> let lens = GraphLens pattern isAtomic
>>> isNode lens (point "a")
True
>>> isNode lens (pattern "rel" [point "a", point "b"])
False

Determine if a Pattern is a relationship according to the lens.

A relationship is a non-node pattern with exactly two node elements.

Properties

• Must not be a node (does not satisfy testNode predicate)
• Must have exactly two elements
• Both elements must be nodes (according to the lens)

Example

>>> let lens = GraphLens pattern isAtomic
>>> let rel = pattern "knows" [point "Alice", point "Bob"]
>>> isRelationship lens rel
True

Extract all relationships from the graph lens.

Relationships are non-node patterns with exactly two node elements.

Time Complexity

O(n) where n is the number of direct elements in scopePattern

Example

>>> let lens = GraphLens pattern isAtomic
>>> relationships lens
[[knows | [Alice], [Bob]], [likes | [Bob], [Charlie]]]

Extract the source node from a relationship.

For directed relationships, the source is the first element. Returns Nothing if the pattern is not a relationship.

Example

>>> let lens = GraphLens pattern isAtomic
>>> let rel = pattern "knows" [point "Alice", point "Bob"]
>>> source lens rel
Just (point "Alice")

Extract the target node from a relationship.

For directed relationships, the target is the second element. Returns Nothing if the pattern is not a relationship.

Example

>>> let lens = GraphLens pattern isAtomic
>>> let rel = pattern "knows" [point "Alice", point "Bob"]
>>> target lens rel
Just (point "Bob")

Reverse the direction of a relationship pattern.

Swaps the first and second elements, effectively reversing the relationship direction.

Example

>>> let rel = pattern "knows" [point "Alice", point "Bob"]
>>> reverseRel rel
pattern "knows" [point "Bob", point "Alice"]

Determine if a Pattern is a walk according to the lens.

A walk is a non-node pattern whose elements are all relationships, where consecutive relationships share nodes (target of one equals source of next).

Properties

• Must not be a node (does not satisfy testNode predicate)
• All elements must be relationships (according to the lens)
• Consecutive relationships must be connected

Example

>>> let lens = GraphLens pattern isAtomic
>>> let walk = pattern "path" [rel1, rel2, rel3]
>>> isWalk lens walk
True

Extract all walks from the graph lens.

Walks are non-node patterns whose elements are all relationships, where consecutive relationships share nodes.

Time Complexity

O(n) where n is the number of direct elements in scopePattern

Example

>>> let lens = GraphLens pattern isAtomic
>>> walks lens
[[path | [rel1], [rel2], [rel3]]]

Extract nodes from a walk in traversal order.

Returns the source of the first relationship, followed by the targets of subsequent relationships. Returns empty list if the pattern is not a valid walk.

Example

>>> let lens = GraphLens pattern isAtomic
>>> let walk = pattern "path" [rel1, rel2]
>>> walkNodes lens walk
[pattern "A", pattern "B", pattern "C"]

Find all neighbors of a node.

Neighbors are nodes connected to the given node via relationships (either as source or target).

Time Complexity

O(r) where r is the number of relationships in the graph

Example

>>> let lens = GraphLens pattern isAtomic
>>> neighbors lens (point "Alice")
[point "Bob", pattern "Charlie"]

Find all relationships involving a node.

Returns relationships where the node is either source or target.

Time Complexity

O(r) where r is the number of relationships in the graph

Example

>>> let lens = GraphLens pattern isAtomic
>>> incidentRels lens (point "Alice")
[[knows | [Alice], [Bob]], [likes | [Charlie], [Alice]]]

Compute the degree of a node (number of incident relationships).

The degree is the count of relationships where the node is either source or target.

Time Complexity

O(r) where r is the number of relationships in the graph

Example

>>> let lens = GraphLens pattern isAtomic
>>> degree lens (point "Alice")
3

Construct a GraphQuery from a GraphLens.

All fields are derived from existing Graph functions. queryNodeById and queryRelationshipById perform O(n) / O(r) scans (no index available from GraphLens). queryContainers scans relationships and walks.

Note: defined here (not in Pattern.Graph.GraphQuery) to avoid a circular import between GraphQuery and Graph.

Construct a GraphView from a GraphLens and a GraphClassifier.

The classifier assigns a GraphClass tag to each element in the lens scope. viewQuery is the snapshot query built from the same lens.

Note: defined here (not in Pattern.Graph.GraphQuery) to avoid a circular import — GraphQuery cannot import Pattern.Graph.

A universal interface bridging graph representations to a single queryable and transformable state.

GraphView pairs a GraphQuery (for snapshot traversal) with an explicitly categorized, traversable list of graph elements. It acts as a lazy transformation target: transformations operate over viewElements while algorithms use viewQuery for context lookups.

Construct via toGraphView (from a PatternGraph) or toGraphView (from a GraphLens). Finalize via materialize.

Design Principles

• viewQuery is the unmodified snapshot — it never reflects in-flight transformations, ensuring deterministic context-aware operations.
• viewElements is the mutable list — transformations update this list.
• The pairing is shallow: no deep nesting, just a list and a query record.

Defines how to handle gaps in container structures (e.g., walks) when an internal element is removed by filterGraph.

When a walk's internal relationship is filtered out, the walk becomes structurally invalid. Substitution dictates the repair strategy.

Design Rationale

There is no one-size-fits-all fallback for container gaps. Sometimes a gap means the entire container is invalid; other times a surrogate placeholder should be sutured in. An explicit parameter forces callers to reason about filtering consequences directly.