Design note. What exists today: Triage makes the decision and composerID publishes its decision reference into configured downstream systems. What this article describes: a capability or engineering principle we are considering as composerID develops. It is not a claim that this functionality is currently available in production.
Documentation tells you what software is supposed to do. Tests tell you whether it actually does it. The gap between those two sentences is where technology claims quietly go wrong, and closing it is exactly the discipline composer should adopt as it develops.
A simple rule
Our rule should be simple: if we cannot write an acceptance test for a technical product claim, we should be careful about making that claim publicly.
An acceptance test is not paperwork. It is the claim, restated as something a machine can check:
Claim: composer publishes a reference to destination X.
Test: run a Triage decision through composer and verify that exact reference appears in destination X.
Claim: publishing is safe to retry.
Test: publish twice and prove there was only one downstream result.
Claim: composer notices downstream changes.
Test: change the downstream record and prove composer detects it.
If a claim cannot be restated that way, it is not yet a technical claim. It is an ambition, and it should be written as one.
What we have built so far
We turned the claims on our own API documentation into a runnable test pack: point it at an address and a credential, and it checks each documented behaviour against whatever is listening there. It runs against our reference sandbox on every change, so the documentation, the reference implementation and the tests are held together by the build. If someone changes the behaviour without changing the documented claim, the build fails.
The sandbox is a sandbox. Passing against it proves the design is implementable and the documentation is consistent with itself. It does not prove a production service exists, and we do not use it to claim one does.
What the first run taught us
Writing tests against our own documentation immediately found a disagreement between what a page said and what the reference implementation did, in the fine print of how publish attempts are keyed. Nobody had noticed, because nobody had written anything that compared the two. It is precisely the kind of small mismatch a partner engineer finds in their first week and remembers for a year, and it is much better found by us.
Why this is a design note
The principle already governs what we claim: it is why our coverage table distinguishes research from live integrations, and why this blog marks design notes as design notes. When a production composer service is built, its definition of done should be this test pack exiting cleanly against the production address. Done should be a command, not an argument.
Written with Claude. This post was drafted with Claude, Anthropic’s AI model, working from the composerID repository: the registry, the schemas, the reference sandbox and the vendor documentation it cites. Edited and published by the composerID team.