Graph Attribution and Operational Evidence
Observability and Shadow use the graph to select boundaries and explain evidence. They do not create a second graph identity system or make every span an application node. Architecture, execution history and aggregate overlays answer different questions.
Identity contract
| Identity | Meaning | Evidence rule |
|---|---|---|
| Graph definition/revision | Semantic topology and contracts | Resolve against the actual recorded revision; do not substitute today's graph |
| Node, port, edge and operation | Architectural subject | Stable definition identity, with a source mapping when available |
| Artifact vector | Implementation actually executed | Hashes for client/service/framework artifacts and dirty changes; contract fingerprint alone is insufficient |
| Configuration/policy | Flags, schema, model, runtime compatibility and effect rules | Version or digest plus approved reconstructible references |
| Activation/instance | Particular runtime lifetime | Separate from definition and release; PID alone can be reused |
| Workspace/base/run/comparison | Controlled experiment | Pin pre-state, admitted workload, runner/assertions and paired executions |
| Trace/span/journal operation | Observed causal action | Parent/link/attempt/order evidence; correlation alone is not causality |
Current ReaktorAttributes.NodeId records a node label and NodeInstance its runtime UUID. Resource keys include service version, environment, snapshot and activation. Treat these as implemented labels, not proof that every label already resolves to a canonical definition revision. Unknown artifact/source identity stays unknown.
Keep high-detail IDs on spans, records and artifact metadata. Metric dimensions require a quantitative cardinality budget; stable IDs can still be numerous. Snapshot/release labels accumulate. Use bounded views, rollups and visible overflow accounting.
Observe, compile and execute
A selector/visitor walks a graph and compiles a bounded instrumentation plan. Runtime adapters install hooks and return teardown ownership. Traversal enter/exit is not the lifetime of an asynchronous operation.
Current framework code includes a port interceptor chain, typed attachments, PortSemantics, TelemetryPlanVisitor and installation/uninstallation. Lambda-form invocations are observable; handing out a raw reference does not intercept arbitrary later method calls. Service, HTTP, binding and storage adapters close different boundaries. The workbench must show which paths were actually covered.
Multiple layers may observe one effect. Exactly one selected adapter owns substitution at a replay boundary. Otherwise a graph mock plus a network mock can execute or suppress the same work twice. A planned ShadowPlan selects a region and policies through this existing mechanism; a new universal event bus or receipt database is unnecessary.
The Capture fabric extends observation to JVM methods/state, kernel/process events, JavaScript runtime/compiler hooks, Workers and Kubernetes. Preserve each collector's original evidence and coverage. Map process lifetimes, pod/container identity, runtime activations and operation contexts to the canonical graph only where evidence supports the join. Unmapped observations remain useful; they must not acquire invented node attribution. Broad capture and a narrower replay substitution boundary can coexist.
Causal evidence across runtimes
Use W3C context for supported request boundaries, and explicit links/creation contexts for asynchronous messages. Preserve producer admission, processing, retry and acknowledgement as different actions. Queue acceptance does not mean downstream completion. A single logical journey may span several traces.
Current local port spans, Java-agent spans and Worker spans do not by themselves establish a connected client-to-store trace. The missing propagation and serializer links/events are delivery work. Present URL/binding-derived structural links from Connected panes as structural evidence until an actual observation proves an execution.
Evidence as a fact
Each read carries subject, revision/activation, acquisition method, observation time, scope, freshness, coverage/loss and perturbation. It also carries supported operation and effective grant. Sampling, attribution and interactivity are independent dimensions; an interactive target may still lack a particular value read or write capability.
Reuse Fact/TruthClass: source-derived, observed live, stale, unknown, fixture and simulated values remain distinct. A source finding is not a live incident; a recorded response is not a successful real dependency execution. Capture gaps must be visible in charts, overlays, findings and agent summaries.
Profiles and instance metrics on the graph
A profile belongs to an attachment and activation, with a time interval, workload, build/runtime identity, profiler settings, symbols and measured overhead. Map samples to graph scopes only when source markers or adapters support that mapping. Unmapped samples and scheduler/native/GC time remain visible.
Instance metrics aggregate into deployment and graph views without pretending that one process equals one node. One JVM can host many graph activations; one logical service can span many pods; a Worker isolate does not expose an ordinary stable process inventory. Build-size attribution uses the build/dependency graph and symbol/bundle breakdown, not runtime duration.
The investigator follows: user journey → graph scope → exact activation/release → trace and instance timeline → original profile or heap artifact → reproducible Shadow case. Changes use the existing prepare/execute/receipt path with target authority, bounded duration and cleanup evidence. Read visibility never grants mutation permission.
Acceptance
A real selected port must reveal its source/release and one measured operation with coverage. A historical trace must resolve to its historical graph or report that graph unavailable. A profile must reveal its real target and capture settings. A paired Shadow failure must link both executions, pre-state and fixed assertion. These are separate gates in the instrumentation plan.