Subgraph views, visitors and traversals

A subgraph view answers one bounded question about the same system definition. A selector chooses admissible neighbors; a traverser determines visit order and cycle handling; a visitor accumulates a finding or projection. Source graph identities, relation roles, revision and coverage stay visible. A view is not a separately authored operational graph.

Selection, traversal and observation are different

Use the existing Selector, StructuralSelector, ConnectivitySelector, DepthFirstTraverser, BreadthFirstTraverser and PortGraphVisitor in reaktor-graph-port/.../visitor/Visitor.kt. Structural selection follows containment/ports/edges. Connectivity selection currently follows consumer dependencies. A product-flow selector must choose relevant roles and directions explicitly. DFS supports balanced exit callbacks; current BFS does not call them, so do not combine BFS with the stack-based HierarchyVisitor.

Bound visits, time and remote reads. Keep visited identities for cycles. A structural graph path is not an observed execution path: derive execution from trace/operation context, environment, source revision and activation evidence.

One system, several lenses

For canonical graph G, principal/context c, selector s and evidence cut t, a view is V(G,c,s,t). It carries graph revision, selector version, admitted nodes/ports/facets, preserved incidences and explicit boundary/coverage information. A traversal order never becomes a release schedule. The diagrams below offer Whole definition / Selected view to demonstrate the declared selector; these public fixtures do not implement production RBAC.

Authorization before retrieval

Evaluate the human or delegated agent principal for the requested read and facet scope before returning graph data, source, embeddings or captured payloads. Then apply topology-disclosure policy to stubs, relation degree and names. Recheck effect-time admission at secured ports: an inspect grant does not imply send, debug or deployment permission. See Reaktor Auth.

Telemetry uses evidence, not arrows

PortTelemetryInterceptor records instrumented invocation durations using a monotonic source, graph/node/port identities and separate activation identity. Join actual traces and causal links for the selected product flow. E2E latency is between observed product milestones; overlapping spans cannot simply be summed. Propagate trace context across RPC and broker boundaries; async span links, sampling, missing instrumentation and clock uncertainty remain visible. OpenTelemetry context propagation, trace API.

Findings become plans through admission

A debugger visitor emits a source/target plan bound to permitted Shadow evidence. Running the debugger requires an isolated scenario, source maps, target attachment and a separately authorized command. A code-push visitor emits eligible cuts and rejected-boundary reasons; a controller validates, admits, drains, migrates and reconciles the chosen candidate. Neither visitor directly mutates live runtime state.

import dev.shibasis.reaktor.portgraph.visitor.*

// Existing runtime API; Graph/PortNode inputs come from the authorized host.
val visitor = HierarchyVisitor()
DepthFirstTraverser.traverse(graph, StructuralSelector, visitor)
val hierarchy = visitor.rootMap

// A custom selector can restrict neighbors to admitted identities and profiles.
// Keep authority checks at retrieval and actual effect boundaries too.

For remote/dynamic systems, take a bounded snapshot or explicit cut rather than assuming a recursive walk is transactionally consistent. Traversal alone does not load every distributed host or confer access to it.

Structural traversal and connectivity traversal

What does the selector traverse, and what does the visitor derive?

Domains and use cases: visitors, inspection, composition.

View selector: Declared product-flow nodes; omit unrelated service and evidence resources.

Admitted node identities: route, surface, service, store.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: StructuralSelector follows graph → nodes → ports → edges. ConnectivitySelector follows a node through its consumer dependencies. DepthFirstTraverser calls exit callbacks after descendants; BreadthFirstTraverser invokes visit while scanning levels and currently does not invoke exit callbacks. A custom selector chooses the relation/direction needed by a bounded view.

Concrete module/design guide · Definition JSON · revision 7e08dc2c19cc

Laws and limits:

• ConnectivitySelector is not automatically an outgoing product-flow trace; service flows may need both directions and selected relation profiles.
• HierarchyVisitor relies on balanced exit callbacks, so use it with the depth-first traverser, not the current breadth-first traverser.

A principal-scoped RBAC view

Which graph nodes and port contracts may this human or agent principal discover?

Domains and use cases: RBAC, auth, agents.

View selector: Example inspect policy admits principal, policy and conversation read; send and private identity are not admitted.

Admitted node identities: principal, policy, read.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: Evaluate AuthContext against AuthRequirement for the requested inspect action, environment and graph revision. A query admits only authorized node/port/facet identities, then applies disclosure rules to boundary stubs. A delegated agent may receive a narrower view than its human sponsor. This illustration declares a read-only agent grant; it does not authorize send or deployment.

Concrete module/design guide · Definition JSON · revision c1e39e86b511

Laws and limits:

• SecuredProviderPort and SecuredConsumerPort exist; an end-to-end principal-filtered query engine remains integration work.
• Filter before returning data or embeddings. Omitted nodes do not establish nonexistence; revealing relation degree or a redacted name may itself disclose data.

Measured end-to-end latency view

How long did one send-message intent take to reach the chosen completion milestone?

Domains and use cases: telemetry, distributed systems, mobile.

View selector: Flow identities plus authorized span evidence; exclude unrelated campaign and uncaptured Shadow resources.

Admitted node identities: route, surface, service, store, spans, visitor, finding.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: Select the route → Surface → service → authority flow, then join actual spans by trace/operation identity, graph revision and activation. PortTelemetryInterceptor records monotonic elapsed durations at instrumented calls. An E2E finding uses observed start/end milestones and causal span links; it does not sum overlapping spans or derive latency from diagram geometry.

Concrete module/design guide · Definition JSON · revision 0441208bb24d

Laws and limits:

• No measured values are fabricated in this design. Missing context, sampling, uninstrumented callbacks and clock uncertainty remain visible coverage gaps.
• Reference-shaped ports are skipped by the interceptor; returned-object calls need their own instrumentation. Queue wait and client render may lie outside a service span.

One flow in a Shadow-backed debugger

Can an operator reproduce and step through this exact send-message path with scoped captured data?

Domains and use cases: debugging, Shadow, product flows.

View selector: Selected send-message flow plus its permitted spans, redacted Shadow capture and debugger plan inputs.

Admitted node identities: route, surface, service, store, spans, shadow, visitor, finding.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: The flow visitor identifies source-owned nodes, ports, RPC hops and state authority. It produces a debugger plan bound to source maps, artifacts, graph revision, activation, and a redacted Shadow capture. Admission then creates an isolated scenario and attaches qualified target debuggers. The visitor itself stays read-only; running the debugger is a separately authorized command.

Concrete module/design guide · Definition JSON · revision 69de9a30ec7a

Laws and limits:

• Shadow capture fidelity, native FFI state and external effects have declared gaps; a full arbitrary-system debugger is a target integration, not an existing visitor guarantee.
• Replay data can be sensitive. Verify redaction, workspace access, effect suppression and target support before starting an isolated run.

A code-push eligibility view

Which region can this qualified host replace while preserving boundary and state laws?

Domains and use cases: RGL, code push, partitioning.

View selector: Illustrative candidate region only; crossing lifecycle/checkpoint/artifact contracts must be reported and qualified before deployment.

Admitted node identities: bundle, region.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: Visit the RGL definition and source/artifact dependencies. Compute a candidate closure, record every crossing port, then filter by Kotlin/JS compilation, qualified FFI target, installed capability, authority, lifetime/drain, dependency and state-migration rules. Eligible regions enter an admitted release plan; structural reachability alone never makes a region deployable.

Concrete module/design guide · Definition JSON · revision a7d148b4d9ba

Laws and limits:

• An active borrowed resource, incompatible checkpoint, unqualified target ABI or unresolved policy makes the cut ineligible.
• A graph visitor can prepare findings and a release proposal; it cannot waive the host admission/reconciliation protocol.