Unbribable architecture validation with REFCODES Diagnostics

The architecture of SERVPHER defines how information should be discovered, understood, represented and delivered, while an increasing amount of its code comes from close collaboration with an Artificial Intelligence (AI) and a Large Language Model (LLM). This productive and exciting collaboration raises an uncomfortable question: How can the implemented architecture be verified to (still) represent the intended architecture?

Generated code can be reviewed and questioned and other people as well as an AI or an LLM may be asked whether the implementation follows the intended architecture, potentially providing a convincing and even correct assurance that it does. Nevertheless, a conclusion expressed in natural language remains an interpretation which has to be understood and trusted, while such assurances become increasingly difficult to verify once a codebase grows beyond what can reasonably be comprehended in all its detail.

Because the architecture of SERVPHER should not depend upon naively believing reassuring confirmations, an unbribable mechanism within the software is needed to record what actually happens, evaluate that evidence against explicitly defined rules and fail when the observed architecture contradicts them. This mechanism should neither butter up the architect nor the author of the code and should produce the same conclusion from the same evidence - independently of whether the code was written by a person or an LLM. This led to the refcodes-diagnostics module.

Architecture should not merely be promised by its authors but should be validated against objectively verifiable evidence, including evidence provided by the executing software.

Trust is not validation

I use the word unbribable deliberately, even though software obviously has neither morals nor (at least not yet) a bank account, because in this context it describes a deterministic mechanism which cannot be persuaded by confidence, authority or eloquence and which evaluates the evidence it is given against explicit rules before reporting the result.

This does not imply that the mechanism is flawless: An assertion can be wrong, it may express an incomplete architectural rule, the captured observations can be incomplete or a test scenario may never execute an important path. Ordinary logs are one available transport for structured diagnostic events, but they are not cryptographically immutable merely because they carry such evidence. The unbribable part is the evaluation of the available observations, not a claim that the evidence is complete or protected against a malicious actor.

People and LLMs remain important to construct a fit architecture by expressing useful rules and interpreting unexpected results. The refcodes-diagnostics module merely removes one particularly fragile dependency:

Reproducible evidence of an implementation’s behavior removes the need to accept somebody’s assurance that it follows the architecture.

The architecture to preserve

The SERVPHER project started as an idea of exposing Markdown documents through HTTP and gradually developed into an information platform centered around a semantic Node Graph, its canonical model of interconnected Nodes representing information. The Scanners discover information, Generators turn the discovered sources into Nodes, Processors enrich those Nodes, Validators protect the graph’s consistency, Projections create purpose-specific views and Transport Adapters deliver those views without defining the underlying domain.

These separations are not incidental implementation details as they are part of the project’s identity:

Information Sources ─🠞 Scanners ─🠞 Generators ─🠞 Processors ─🠞 Validators ─🠞 Node Graph ─🠞 Projections ─🠞 Transport Adapters

The class structure can suggest this architecture, package dependencies can constrain parts of it and static analysis can prove that particular dependencies exist or are forbidden. Nevertheless, the architecture also contains statements about collaboration at runtime. A scan should happen before generation, processing should happen before validation and publication should not occur before the resulting graph has been validated. A request for a particular representation should pass through the intended projection pipeline rather than taking an attractive shortcut around it.

These questions are concerned with what actually participates in an executed scenario and in which order it participates, which is where static structure alone no longer provides every required answer.

Turning architectural questions into Concerns

The central concept of refcodes-diagnostics is the Concern, which represents an architectural question to be answered from recorded observations. A Recording collects the evidence belonging to one observed execution flow and provides the basis for answering its Concerns:

Did the scanning and processing pipeline complete successfully?
Did validation happen before the new Node Graph was published?
Did a request reach the expected Projection strategy?
Did an observed flow cross a forbidden boundary?
Did work propagated into another system complete within its deadline?

A Sensor is a reusable instrumentation point which contributes observations to the applicable Recordings. Beginning a Concern opens a Concern Bracket, the paired evidence delimiting the part of the execution belonging to that question, and completing the Concern closes that bracket. The Concern has a stable alias so that the corresponding close cannot accidentally complete another nested Concern. A Trace represents the complete execution flow across threads and system boundaries, within which several Concerns may appear sequentially, overlap or be nested. Their aliases describe the architectural question while the Trace preserves the flow in which that question was observed.

The instrumentation inside the business code comes without boilerplate and deliberately has a small footprint.

Capturing an observation records that an architecturally relevant location in the code was reached, while a scoped observation records entry, completion, duration and failure. The static RecordingSugar operations form a small domain-specific language (DSL) which keeps these statements visually separate from the business logic, and each statement can be removed without changing the business operation surrounding it. This removability is an architectural property of the instrumentation, not a promise to hide invalid usage or a broken recording configuration from the application.

The first local SERVPHER Recording conceptually looked as follows:

begin Concern "servpher.scanning-processing"
│
├── capture refresh
├── capture scan
├── capture generate
├── capture process
├── capture validate
├── capture publish
│
close Concern "servpher.scanning-processing"

These Sensors are therefore not intended to cover every method. They observe the locations which matter for answering architectural questions. Without an active Concern or propagated Trace, a Sensor is a cheap no-op and does not create unrelated Recordings merely because instrumented code happened to execute.

A Sensor is an architectural observation point, not another general-purpose logger.

Recording evidence instead of an opinion

The theoretical foundation of refcodes-diagnostics is a small evidence pipeline described by its recording manifest. A Recording Event is the canonical record of one observed occurrence and a Recording Backend folds these events into their shared Recording:

Application code
      │
      🠟
    Sensor
      │
      🠟
Recording Event
      │
      🠟
Recording Backend
      │
      🠟
   Recording
      │
      ├── Assertions
      └── Diagrams

A Sensor produces a canonical Recording Event. The Recording Event contains its identity, source-local order, timestamp, source coordinates, event type and status as well as optional Concern, observation or failure information. It does not capture arbitrary arguments, return values or object graphs by default, which avoids retaining secrets or large structures as an unexpected side effect of architectural diagnostics.

Every Recording Event path used to construct a Recording eventually reaches the same Recording Backend. This Recording Backend groups Recording Events, removes duplicates, preserves the order observed by an individual source, reconstructs causality and Concern Brackets and exposes missing or contradictory evidence as Recording Findings, explicit descriptions of incomplete or inconsistent evidence. Consumers receive immutable Recording snapshots instead of rebuilding architectural meaning from logs on their own.

This single folding point matters. If the direct in-process path and a later log-based path reconstructed their Recordings independently, both implementations would gradually develop subtly different answers. The required equivalence is simpler:

Sensors ─🠞 Recording Backend ─🠞 Recording ─🠞 Evaluation

Sensors ─🠞 Transport ─🠞 Reader ─🠞 Recording Backend ─🠞 Recording ─🠞 Evaluation

The transport may change without changing the architectural meaning.

Identity and causality across system boundaries

The first SERVPHER experiments were intentionally local. A test activated a Concern, executed a representative application scenario and evaluated the resulting Recording inside the same Java Virtual Machine (JVM). The model was nevertheless designed so that the Concern would not end at a process boundary.

The refcodes-diagnostics module follows the identity model of the W3C Trace Context specification.¹ A Trace ID identifies the complete flow across all participating systems, a Span ID identifies one execution unit within that flow and a Parent Span ID connects an execution unit to the one which caused it. The standardized traceparent HTTP header field’s representation carries this identity across a system boundary.

There is deliberately no second recording or correlation identifier as all recorded evidence carrying one Trace ID belongs to one architectural Recording. When work moves to another thread, process or system, its context must be handed over deliberately and the new execution unit receives its own Span ID. This preserves causality without confusing concurrent work with the execution unit which initiated it.

Such Recording Events may arrive directly, through a logger or through another transport. They may be delayed or arrive out of order. The Recording Backend uses their identities, ancestry and source-local order to reconstruct the available evidence. A referenced but unavailable parent span, an unclosed Concern or contradictory completion Recording Events do not disappear through a convenient guess. They remain Recording Findings in the result.

Incomplete evidence is evidence about incompleteness and must remain visible.

Making the architectural vision executable

The Recording alone documents what was observed within its Sensor boundaries. Assertions turn the intended architecture into an executable specification. The architecture tests in funcodes-servpher-architecture execute real SERVPHER paths using its Spring configuration, Scanners, Generators, Processors, Validators, Projections and Transport Adapters. They then ask the resulting Recording concrete questions.

The scanning and processing scenario currently verifies statements such as:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
theRecording
    .assertNoFailure()
    .assertNoFindings()
    .assertVisited( RefreshableNodeGraphProvider.class, "refresh" )
    .assertVisitedBefore(
        NodeScannerPipeline.class, "scan",
        NodeGraphGeneratorPipeline.class, "generate"
    )
    .assertVisitedBefore(
        NodeGraphGeneratorPipeline.class, "generate",
        NodeGraphProcessorPipeline.class, "process"
    )
    .assertVisitedBefore(
        NodeGraphProcessorPipeline.class, "process",
        NodeGraphValidatorPipeline.class, "validate"
    )
    .assertVisitedAfter(
        RefreshableNodeGraphProvider.class, "publish",
        NodeGraphValidatorPipeline.class, "validate"
    );

This is the point where an architectural intention stops being an explanatory paragraph which may drift away from the implementation, because the test fails if publication moves before validation or if a refactoring silently bypasses a required stage, independently of whether the change was introduced by a developer or an LLM.

The assertion does not prove that every possible execution path of SERVPHER is correct. It proves that the observed scenario satisfied the explicitly stated rules within the selected Sensor boundaries. Other scenarios require their own Concerns and representative executions. Static dependency rules remain valuable for paths which were not executed and ordinary unit tests remain responsible for functional behavior.

Runtime architecture assertions therefore complement rather than replace other verification techniques:

Unit tests verify functional outcomes
Static architecture tests verify permitted code structure and dependencies
Profilers explain performance and runtime cost
Distributed tracing follows operational requests
Diagnostic Recordings verify architecturally relevant collaboration for an explicit Concern

One recording 🠜🠞 Several views

The same Recording used by an assertion can be rendered through a visitor. The SERVPHER project currently writes PlantUML sequence and class diagrams from its architecture scenarios.² The sequence diagram makes the observed order and collaboration visible while the class diagram provides another view of the participating types.

This is important because the diagram and the assertion no longer describe two independently maintained versions of the architecture, but consume the same immutable evidence:

                                 ┌── Deterministic assertions
Observed execution ─🠞 Recording ─┤
                                 └── PlantUML diagrams

The assertion provides the uncompromising pass or fail decision and the diagram helps explain why the decision was reached as well as what the architecture currently looks like. A generated diagram can reveal an unexpected detour or participant before an assertion has even been formulated for it and the assertion can then preserve the insight gained from that visual analysis.

Assertions make the architectural vision executable and diagrams make the observed architecture understandable.

What unbribable does not mean

Calling this validation unbribable would be dangerous if it concealed the boundaries of the claim, because the mechanism can only evaluate the rules it has been given and the Recording Events it has observed, cannot discover every architectural intention on behalf of its author and cannot prove facts about code paths which the scenario never executed.

There are several ways in which one could still deceive oneself:

Place Sensors only where they support the expected architecture
Omit an assertion for an important rule
Choose a scenario which never exercises a problematic path
Ignore Recording Findings about missing or contradictory evidence
Treat ordinary log storage as tamper-proof evidence

The module responds to these risks by keeping its boundaries explicit. Missing data remains visible, Recordings report Recording Findings, diagrams expose the observed participants and the manifest distinguishes structured evidence from cryptographic integrity. This does not eliminate human responsibility. It gives that responsibility a reproducible object to work with.

Architectural diagnostics as a cross-cutting concern

The original need emerged from SERVPHER, but neither Concerns nor runtime architecture Recordings are specific to an information platform. Any system with an architectural claim can benefit from turning representative flows into evidence, assertions and diagrams. A file transfer may need to reach another system within a deadline, a request may be forbidden from crossing a package boundary or an asynchronous pipeline may require a particular ordering.

This made the mechanism a natural candidate for REFCODES. The base refcodes-diagnostics artifact owns Recording, reconstruction, assertions and representations without depending upon a particular application framework. Extensions may integrate the mechanism with Spring or another environment while the core model remains independent of the transport and framework which carried a Recording Event.

The similarly named refcodes-diagnosable artifact serves a different purpose. It exposes the effective runtime state of an object as a diagnostic schema which can be represented as JSON, XML or PlantUML.³ The refcodes-diagnostics module records an observed flow over time. One answers what is this object’s effective state? and the other answers what happened while this architectural Concern was active?

From a local experiment to a distributed witness

What began as local instrumentation for the architecture of SERVPHER has developed into a model which can cross threads, processes and system boundaries. Structured Recording Events may be published directly and consumed immediately or encoded into logs and reconstructed later. A central Recording Backend can combine partial evidence belonging to the same Trace while retaining open Concern Brackets, missing Parent Span IDs and delayed Recording Events as explicit facts rather than smoothing them over.

The word witness seems suitable here because refcodes-diagnostics does not design the architecture or replace the people or tools which do, but observes selected execution paths, preserves their evidence and answers the questions encoded in their assertions. Unlike an architectural document, it participates in the build, while unlike a confident explanation, its conclusion cannot be improved by phrasing.

Collaboration with an LLM made this need especially visible, but the underlying problem is much older than generative AI because code has always grown beyond the complete understanding of one person as teams change, abstractions evolve, documentation ages and convincing explanations can be mistaken. The difference is that code can now be produced at a speed which makes the gap between implementation and human comprehension widen much faster.

The aim is not to stop that productivity, but to preserve architectural authorship even when most of an implementation is no longer typed by its architect.

Conclusion

The refcodes-diagnostics module originated from the requirement to preserve the architectural vision of SERVPHER without depending upon promises which could no longer be verified by reading every line of code. The first solution was deliberately local, with instrumented scenarios producing Recordings, fluent assertions validating their collaboration and PlantUML diagrams making the observed architecture visible.

From this experiment emerged a more general model in which Concerns formulate architectural questions, Sensors record relevant observations, canonical Recording Events carry structured evidence, one Recording Backend reconstructs immutable Recordings and consumers apply assertions or create representations from that same result. The combination of Trace IDs, Span IDs and explicit context propagation lets the model retain its meaning when a flow crosses a system boundary.

This does not make architecture automatic or evidence infallible, but it does provide a previously missing deterministic witness which has no reason to reassure anybody and no ability to negotiate with the rule it is evaluating.

Code may be created in collaboration with people, an AI or an LLM, but the executing system itself should provide the unbribable evidence that its architecture still follows the vision.