What happened
The KryptoOS audit of 2 September 2026 examined why on-chain credential verification always returned verified: false. Reading the polkadot-js source, the auditor concluded that the SDK read the DID document's key list from a field (doc.keys_) that polkadot-js never creates — because the library's Struct extends Map, and 'keys' already exists on the prototype, so the alias would not be added. The fix, it said, was doc.get('keys'). Its unit test agreed, because the test stub fabricated the field.
What the chain said
On 13 September, Phase 3 of the KryptoOS work tested the decoder against a running node with the dependency versions actually installed (@polkadot/api 10.13, @polkadot/util 12.6.2). The key list did live in doc.keys_. doc.get('keys') returned undefined. The 2 September conclusion had read a library and inferred behaviour; the behaviour, in the versions in use, was the opposite.
What was actually wrong
Something the library-reading could not see: the issuer and verifier APIs constructed their WebSocket provider with new WsProvider(url, false) and never called connect(). Over WebSocket, they had never reached the chain at all.
The rule
Test a decoder against a node. Never infer its behaviour from the library's source. Library internals vary by version, by build, by which of several code paths a value took. The chain's answer is the only ground truth, and it is cheap to get: live tests are now gated by an RPC URL and a seed and run against a development chain in CI.
Why this note is uncomfortable
Because the first conclusion was careful, well-reasoned and wrong, and it was recorded in the project's memory as fact for eleven days. The correction is recorded in the same place, with the rule. A project that keeps its reasoning errors visible is one whose current reasoning you can weigh.
From the KryptoOS audit (2026-09-02) and Phase 3 verification (2026-09-13).