The Arrow Had No Protocol

The diagram still had its gateway, API pods and private network. I removed only the label on the connection between the gateway and an API component. Archify rejected it.

Then I supplied a made-up label: imaginary encrypted tunnel. The engineering-profile validator accepted the diagram again.

Those two results belong together. Machine-readable architecture can make omissions testable. It cannot establish that a named protocol exists in the deployed system merely because the corresponding string is nonempty.

August 30 retrospective; experiments run September 12, 2026. The pinned revision is b36d79fdbc3aec3728744341485a7e79f03c0071, committed on August 29 UTC. Its package identifies itself as 2.16.0-dev.0.

The Failing Change

Archify represents a diagram as JSON before producing its rendered output. In the production deployment example, components have IDs and owners, boundaries list the component IDs they contain, and connections refer to their endpoints. The example document enables the deployment-ownership engineering profile.

My mutation selected the connection from gateway to api_a and set its label to an empty string. The returned diagnostic code was:

engineering/deployment-crossing-mechanism

This is a stronger review aid than an undifferentiated “invalid diagram” message. The profile's diagnostic includes the connection's identity, its array position, the boundaries it crosses and a suggested edit location. An agent can locate the omission without guessing which arrow the validator disliked.

It should still ask the repository or a human for the real connection mechanism. Supplying text merely to satisfy the check is easy, as the invented label demonstrated.

Membership Drives the Check

The profile implementation follows authored membership lists. It checks which region and security-group boundaries include each component ID. Its boundary-crossing decision does not depend on whether a box happens to look enclosed at a particular pixel coordinate.

That separation is useful when an agent rearranges a diagram. Moving a node to improve spacing should not silently change its declared network placement. Conversely, drawing a node inside a rectangle does not repair missing membership in the JSON.

The profile also checks owners for non-external components, region assignment, and private placement for components classified as database. These are explicit rules for this profile. They are not a general proof that every possible stateful service has been recognized or that an owner tag names a real team.

I exercised five variants of the same input through validateEngineeringProfile:

Input	Profile validation
Original example	Accepted
Owner removed from the edge component	Rejected: missing owner
Gateway-to-API mechanism removed	Rejected: missing crossing mechanism
Invented mechanism inserted	Accepted
Profile disabled, missing mechanism retained	Accepted

The last row is deliberate. The engineering profile is opt-in. Calling the lower-level diagnostic function directly can still reveal an omission, but normal profile validation does not enforce these rules on an ordinary diagram that never selected them. The probe script prints both outcomes so that distinction is visible.

A Failed Render Should Preserve the Last Good File

The upstream engineering-profile suite tests a second behavior that matters in an agent editing loop: a failed delivery must leave an existing output file intact. The test places known bytes in the destination, tries to deliver an invalid diagram, and checks that those bytes remain unchanged.

I ran the pinned suite directly with Node 24.18.1:

node --test archify/test/engineering-profile.test.mjs
tests 7
pass 7
fail 0

Those seven tests include CLI validation and delivery, boundary membership cases, profile scope, and the preserved-output check. This was a focused suite, not an exhaustive visual audit of every renderer. The test source makes the exercised paths reviewable.

For generated architecture documentation, I would retain the JSON, the validation receipt and the rendered diagram together. Reviewers could then distinguish three separate questions: whether the document satisfies its declared rules, whether the drawing communicates them clearly, and whether the repository or deployment supports its claims.

A missing protocol label can be a build error. A believable but invented protocol still needs an evidence check. The useful role for this validator is to expose the first problem reliably enough that reviewers can spend their attention on the second.