Skip to content

Add JSONEnvelope, a versioned digest-checked envelope over JCS - #99

Merged
ThorFuchs merged 1 commit into
mainfrom
feature/1.10-envelope
Nov 15, 2026
Merged

ThorFuchs merged 1 commit into
mainfrom
feature/1.10-envelope

Conversation

@ThorFuchs

Copy link
Copy Markdown
Owner

Summary

1.10 exact interchange, last piece: JSONEnvelope, a versioned record of one payload in RFC 8785 canonical bytes. The maintainer chose the digest design on 15 November 2026.

Wire format (version 1, fixed)

{"digest":"sha256:87245ae1c062ec8fd5e2ab1ac60fbc44f6822d6176fe850381db1fd6e97c7810","format":"swift-json-envelope","formatVersion":1,"payload":{"id":7,"state":"done"},"type":"mcp.task","version":3}
  • Members: exactly six, and the whole object is JCS bytes, so equal envelopes encode to equal bytes.
  • digest: sha256: plus the lowercase hex SHA-256 of the canonical payload. Equal payloads have equal digests, so the digest can serve as a content address.
  • type: non-empty, at most 256 UTF-8 bytes.
  • version: 1 … 2^53 − 1.

API (JSON core)

  • JSONEnvelope(type:version:payload:).
  • encode(options:) / encodeWithReport → JSONEnvelopeEncoding { data, digest }.
  • JSONEnvelope.decode(_:options:) / decodeWithReport: accepts any strict spelling and verifies the marker, member set, formatVersion, fields and digest.
  • JSONEnvelopeFailure (invalidFormat, unsupportedFormatVersion, invalidType, invalidVersion, invalidDigest, digestMismatch) for well-formed values that are not valid envelopes. No case carries input text. Syntax, resource and number failures stay JSONFailure. I used a separate error type so the public JSONFailure.Code enum gains no cases.
  • JSONEnvelopeOptions: limits and the canonical NumberPolicy. The default .preserving refuses numbers binary64 cannot spell exactly; .rounding must be used on both sides.
  • Each call uses one invocation ledger: admission, canonical writing, SHA-256 and assembly share the meter, with cancellation checkpoints. Conversion checks catch only .conversion failures, so cancellation and resource failures propagate.

Docs and tooling

  • New DocC article VersionedEnvelopes.md, linked from the JSON landing page.
  • CHANGELOG entry.
  • JSONTests discovery counts 198 → 203.
  • CLI identity regenerated.

Tests

  • Envelope bytes and three digests are pinned to values computed independently with Python hashlib over the RFC 8785 payload bytes, including non-ASCII keys and 1e+21.
  • Equal and reordered payloads produce equal bytes; a whitespace-spelled envelope round-trips.
  • 20 corruption and invalid-field cases, plus syntax errors and duplicate keys.
  • Number-policy behavior, and the input/output limits.

Qualification (local)

Toolchain: Apple Swift 6.4.2 (swiftlang-6.4.2.1.9), macOS 27.3. Source: 22f4383 on b3eef29.

  • python3 Scripts/ci.py --lane docs: exit 0, 4/4 commands passed
  • python3 Scripts/ci.py --lane native: exit 0, 62/62 commands passed, 0 failed

No tag, release or publication follows from this PR.

🤖 Generated with Claude Code

Format version 1 is one RFC 8785 canonical object with digest, format,
formatVersion, payload, type and version. The digest is the SHA-256 of the
payload's canonical bytes; decoding verifies marker, fields and digest and
reports JSONEnvelopeFailure for invalid or damaged envelopes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ThorFuchs
ThorFuchs merged commit 8090589 into main Nov 15, 2026
21 checks passed
@ThorFuchs
ThorFuchs deleted the feature/1.10-envelope branch November 15, 2026 10:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant