Shipmind Labs

We shipped a marking step that reported success and wrote "marked" into the evidence log. Weeks later two copies of the same document came back for comparison, and we could not tell them apart.

The log was confident. The bytes were identical.

What happened is boring and, looking back, predictable. A marker implementation met a media type it did not really support, returned the input untouched, and still set its own marked flag to true. Nothing crashed. The log recorded a mark that never existed, wrong in the direction that makes you trust it.

The cost was not an outage. It was the hour we spent re-deriving from context which copy was which, and the much longer conversation about what else in that log we were still willing to believe.

So in our open-source project disclosurekit we made one function the only path by which a marker result reaches the evidence log, and we put the check ahead of the claim.

It awaits the marker, hashes the content that came back, hashes the content that went in (a string as utf8, a byte array as its bytes) and compares the two digests.

If the marker says marked and the digests are equal, the bytes win. We append a content-unmarked entry naming the marker, the media type and the method, with a reason that spells out the contradiction: this method reported a mark and returned the content unchanged, so no byte differs from the input. The result handed back says marked false, carrying the original content.

Only a marked result whose digest actually differs gets a content-marked entry, with the hash of the content as served.

The quiet cases get written down too. An unmarked result that gives no reason gets a default sentence saying exactly that, because a gap in the record should be a line in the log rather than an absence.

The habit we kept afterwards: in any log meant to serve as evidence, verify the claim at the moment the component makes it. Otherwise you are not recording a fact, you are recording an intention, and the two look the same six weeks later.

Your audit trail probably still takes some component claims on trust, and those are the ones worth listing.

Was this useful?

Building something similar?

or email hello@shipmindlabs.com