feat(parsing): frame CESR 2.0 (v2) streams (stacked on #402)

[dhh1128]

Summary

Adds CESR 2.0 / KERI 2.x support to the stream parser introduced in #402.
The parser now frames both CESR-1 and CESR-2 streams to the same resilience
posture, ground-truthed against keripy 2.0.0-dev6.

Stacked on #402. This branch is based on feat/cesr-stream-parser, so
until #402 merges the diff here shows both commits; the change owned by this
PR is the second commit (feat(parsing): frame CESR 2.0 (v2) streams via genus dispatch). Please review/merge #402 first — this will then narrow to just the
v2 commit and can retarget cleanly onto main.

What it does

• parseVersion now parses the v2 version string
  (proto + protocol-version + embedded CESR-genus-version + kind +
  base64 size + . terminator) and returns the genus.
• frameGroup dispatches by CESR genus. Native v2 counter framing (from
  keripy's CtrDex_2_0) is added because signify-ts's Counter carries only the
  v1 table and silently misframes v2 codes — they collide with v1 code
  strings but denote different groups (e.g. v1 -C is NonTransReceiptCouples;
  v2 -C is the AttachmentGroup wrapper). Every v2 group counts its body in
  quadlets, so it self-frames as count*4 bytes: decomposition is uniform,
  even unrecognized codes are unknown-but-framed, and the v1 -V
  resilience-boundary rule generalizes to all groups.
• Primitives still delegate to Matter/Indexer even under v2 — primitive
  codes are genus-stable, so a v2 AID/SAID/key/signature parses unchanged.
• AttachmentGroup gains a genus field, since a code's meaning depends on it.

Tests

Adds v2 parseVersion, framing, and resilience/corruption tests, plus a real
keripy-generated v2 witness-OOBI vector (PII-free synthetic). All four CI gates
(build, lint, pretty:check, tests) pass locally.

Provenance

Developed and proven in a downstream viewer against a corpus of keripy
2.0.0-dev6 streams, then contributed upstream.

🤖 Generated with Claude Code

[daidoji]

I'm not sure this one is working either. The SAD Path example from the CESR spec fails to parse (as do many other streams that I think should work).

    it('SAD Path example from CESR spec', () => {
        const stream = bytesOf('{"v":"ACDCCAACAAJSONAAIe.","t":"acm","d":"EO3117lnAbjDt66qe2PtgHooXKAYQT_C6SIbESMcJ5lN","i":"EEDGM_DvZ9qFEAPf_FX08J3HX49ycrVvYVXe9isaP5SW","s":"EGU_SHY-8ywNBJOqPKHr4sXV9tOtOwpYzYOM63_zUCDW","a":{"d":"ED1wMKzV72L7YI1yJ3NXlClPUgvEerw4jRocOYxaZGtH","i":"ECsGDKWAYtHBCkiDrzajkxs3Iw2g-dls3bLUsRP4yVdT","dt":"2025-06-09T17:35:54.169967+00:00","personal":{"name":"John Doe","home":"Atlanta"},"p":[{"ref0":{"name":"Amy","i":"ECmiMVHTfZIjhA_rovnfx73T3G_FJzIQtzDn1meBVLAz"}},{"ref1":{"name":"Bob","i":"ECWJZFBtllh99fESUOrBvT3EtBujWtDKCmyzDAXWhYmf"}}]}}');
        const { messages, errors } = parse(stream);
        assert.isEmpty(messages);
        assert.equal(errors, []);
    });

https://trustoverip.github.io/kswg-cesr-specification/#sad-path-examples

[dhh1128]

Thanks for the catches, @daidoji . Fixed now.

[dhh1128]

@daidoji — following up on the SAD-path example, now that the fix is pushed (head 6caf3be).

That stream parses cleanly. Against the current branch head:

parseVersion → { proto: 'ACDC', version: '2.0', kind: 'JSON', size: 542, genus: 2, length: 19 }
parse        → messages: 1, errors: [], consumed: 542, span: { start: 0, end: 542 }

with the full sad decoded, ilk: 'acm', said: 'EO3117lnAbjDt66qe2PtgHooXKAYQT_C6SIbESMcJ5lN', and no attachments. What was broken before was the size field: AAIe is 542, and the parser wasn't reading the v2 version string, so it never framed the body.

One note on the snippet as written, in case you rerun it: assert.isEmpty(messages) asserts the absence of a message, so it fails on a stream that parses correctly, and assert.equal(errors, []) compares a fresh array by identity and can never pass. assert.lengthOf(messages, 1) and assert.isEmpty(errors) are what I think you meant.

On "many other streams that I think should work" — I'd like to chase those. If you have concrete ones, paste them (or point me at the corpus) and I'll add each as a test case.

[daidoji]

Sure, I was testing by hand and hadn't pulled v2 streams out of keripy into a testable corpus (it was always the intention to pull them out into https://github.com/WebOfTrust/cesr-test-vectors/ but we never got around to it, just the primitives and cesr appropriate messages but not necessarily the keri appropriate ones). Like these should parse with cesr but most aren't keri protocol field map payloads. https://github.com/WebOfTrust/cesr-test-vectors/tree/main/example_payloads/version2/json

The ones I was trying were the version 2 field maps from the keri, cesr, acdc specs though as those are the easiest to reach for. I may have made errors in minifying them and running them by hand though so didn't include them explicitly. The counterexample I found was just the easiest. If it becomes difficult I can come back and pull some arbitrary keri protocol messages of any length for you from our implementation. I find it a bit more difficult to do this from keripy.