From deb16f59e21964f2dca50b3300ab2579e6640661 Mon Sep 17 00:00:00 2001 From: Thorsten Fuchs <76904008+ThorFuchs@users.noreply.github.com> Date: Sun, 15 Nov 2026 22:56:48 +0100 Subject: [PATCH 1/2] Prepare 1.10.0 minor release metadata Report CLI version 1.10.0 with its deterministic source identity and regression assertion. Finalize the 1.10.0 changelog entry (including the unpublished 1.9.1 hygiene items), add minor release notes for exact interchange and a 1.10 qualification record with the API compatibility check, and mark 1.10.0 prepared in the roadmap and authority records. Public APIs and finite budgets are unchanged. Publication remains separate. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 14 +-- CHANGELOG.md | 7 +- Documentation/Qualification/Release1.10.md | 83 ++++++++++++++++ Documentation/Qualification/ReleaseLines.md | 5 +- Documentation/README.md | 8 +- Documentation/ReleaseNotes/1.10.0.md | 95 +++++++++++++++++++ Documentation/ReleaseRoadmap.md | 2 +- Sources/JSONCLIEngine/CLIBuildIdentity.swift | 2 +- Sources/JSONCLIEngine/CLIReleaseVersion.swift | 2 +- Tests/JSONCLITests/IntegrationTests.swift | 2 +- 10 files changed, 206 insertions(+), 14 deletions(-) create mode 100644 Documentation/Qualification/Release1.10.md create mode 100644 Documentation/ReleaseNotes/1.10.0.md diff --git a/AGENTS.md b/AGENTS.md index 3eb2c7a..3fe2566 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,9 @@ # Contributor instructions -Latest published release is 1.9.0 at f2a0d12da7028edfbcb0cb307f19a921a3a12d03; -main continues from it. Stable 1.6.1 remains a separate maintenance line. Preserve -every source-bound qualification record. No tag/publication follows from passing -tests alone. +Prepared minor release source is 1.10.0; publication is a separate owner action. It +builds on published 1.9.0 at f2a0d12da7028edfbcb0cb307f19a921a3a12d03. Stable 1.6.1 +remains a separate maintenance line. Preserve every source-bound qualification +record. No tag/publication follows from passing tests alone. Swift-JSON requires Swift tools/compiler 6.4+, Swift language mode 6 and a macOS/SDK 27+ development host; deployment minimums are macOS 15 and iOS 18. Read README.md, CONTRIBUTING.md and the relevant contracts in @@ -57,8 +57,10 @@ store/follow API on 2026-11-10; later API changes stay additive and human-gated. one invocation-owned ledger per operation. Positions remain unforgeable and source-instance-local. No persistence or mutable store is exposed. See Documentation/Architecture/StructuralIntelligence/BoundedWorkflows1.8.md. -Wider retrieval/persistence remains separate work. RFC 7464 JSON text sequences -are 1.10 development in JSONStreaming (`JSONTextSequence`, `JSONTextSequenceWriter`). +Wider retrieval/persistence remains separate work. Prepared 1.10.0 adds RFC 8785 +canonical JSON and `JSONEnvelope` (format version 1 is fixed) to JSON, RFC 6902 +difference to JSONPatch and its static page to JSONHTML (one shared package walker +in JSON), and RFC 7464 text sequences to JSONStreaming. JSONTransform uses one private compiler/VM and the CLI's accounted adapter. Preserve its accepted 42 authored declarations and exact semantics. The original diff --git a/CHANGELOG.md b/CHANGELOG.md index 669d2ed..4120e4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,10 @@ # Changelog -## Unreleased — 1.10.0 exact interchange (in progress) +## 1.10.0 — exact interchange; prepared source, publication separate +- Report CLI source version `1.10.0` with a regenerated deterministic source + identity. See the [minor release notes](Documentation/ReleaseNotes/1.10.0.md) + and the [1.10 qualification record](Documentation/Qualification/Release1.10.md). - Add `JSONCanonicalWriter`, which writes RFC 8785 JSON Canonicalization Scheme (JCS) bytes: compact output, keys ordered by UTF-16 code units, short string escapes and ECMAScript spelling of binary64 numbers. Equal values produce equal @@ -44,7 +47,7 @@ have equal digests for content addressing. Tests pin bytes and digests computed independently. -## Unreleased — 1.9.1 hygiene +### Maintenance collected as 1.9.1 hygiene (not published separately) - Add the `platform-floor` native CI lane. It checks the macOS 15 / iOS 18 manifest minimums, cross-compiles all twelve libraries for iOS 18 devices and diff --git a/Documentation/Qualification/Release1.10.md b/Documentation/Qualification/Release1.10.md new file mode 100644 index 0000000..c6f34d2 --- /dev/null +++ b/Documentation/Qualification/Release1.10.md @@ -0,0 +1,83 @@ +# 1.10.0 qualification + +Status: **prepared, not published.** The maintainer approved the 1.9.1–2.0.0 +release train on 2026-11-12 (see the [roadmap](../ReleaseRoadmap.md)) and chose +the digest design of the envelope on 2026-11-15. Approval of the train is not +approval to tag or publish. A tag and GitHub release need an explicit maintainer +instruction, and the release qualification asset must then record the exact +release commit, tree and lane outcomes. + +## Scope + +1.10.0 adds to published 1.9.0 (`f2a0d12d`): + +| Area | Addition | PR | +| --- | --- | --- | +| JSON | `JSONCanonicalWriter` (RFC 8785) with `NumberPolicy` | #95 | +| JSONPatch | `JSONPatch.difference(from:to:options:)`, `differenceWithReport` | #96 | +| JSONHTML | `JSONHTMLRenderer.renderDifference(from:to:)`, `renderDifferenceWithReport` | #97 | +| JSON | Package `JSONDifferenceWalker` shared by JSONPatch and JSONHTML | #97 | +| JSONStreaming | `JSONTextSequence`, `JSONTextSequenceOptions`, `JSONTextSequenceWriter` (RFC 7464) | #98 | +| JSON | `JSONEnvelope`, `JSONEnvelopeOptions`, `JSONEnvelopeEncoding`, `JSONEnvelopeFailure` | #99 | + +The roadmap update is #94. Maintenance collected as 1.9.1 hygiene (the +`platform-floor` lane, the CLI identity without DocC catalogs, developer kit +0.2.0) ships in 1.10.0, because 1.9.1 was not published. + +No product, product dependency or root package dependency is added. JSONHTML +still depends on JSON only. Platforms and toolchain requirements are unchanged. + +## API compatibility + +`swift package diagnose-api-breaking-changes 1.9.0` on the preparation branch +(based on `8090589`), with Swift 6.4.2, exited 1 with two findings, both in JSON: + +- `JSONNumber.binaryConversionText(meter:)` → `binaryConversionText(meter:chargesOutput:)` +- `JSONNumber.doubleValue(policy:meter:)` → `doubleValue(policy:meter:chargesOutput:)` + +Both are `package` declarations, not public API. #95 gave them a defaulted +parameter so canonical number spelling does not charge output bytes twice. As +with the single package-only finding for 1.9.0, these are false positives for +consumers. The eleven other library modules report no breaking change. The +public change is additive. + +## Format commitments + +- `JSONEnvelope` format version 1 is fixed: the six member names, the marker + `swift-json-envelope`, SHA-256 over the RFC 8785 payload bytes and the + `sha256:` lowercase hexadecimal digest. Tests pin bytes and digests computed + independently with Python `hashlib`. +- `JSONCanonicalWriter` output is pinned by the RFC 8785 Appendix B number + vectors, the RFC's sample document and its key-sorting example. +- The patch difference is deterministic but not minimal. Its operation order is + part of the tested behavior (paired changes, then removals from the highest + index, then additions), not a compatibility promise of minimality. + +## Lane results + +Toolchain: Swift 6.4.2 (`swiftlang-6.4.2.1.9`) via swiftly, Xcode 27.2 macOS SDK, +language mode 6, run with `python3 Scripts/ci.py --lane `. + +Each feature PR passed the local `docs` (4 commands) and `native` (62 commands) +lanes with every command exiting 0, and all 20 GitHub checks (Native, Native +execution, Linux execution on x86_64 and arm64, platform-floor, composition, +safety, archive) before merging. On #98 the first local docs run failed on a +cross-module DocC link; the fix changed a doc comment only and the docs lane then +passed. Native for #98 ran on the commit before that fix; GitHub CI ran on the +merged state. + +The `wasm` lane was not run locally for 1.10. The release commit needs its own +exact CI receipts and a WASI run before tagging. + +## Performance gate: open + +No timing, allocation, RSS or throughput measurement was made for 1.10.0, and +the release claims no performance improvement or parity. The 1.9.0 exception +covered 1.9.0 only. Before tagging, the maintainer decides whether to measure the +controlled-performance gate or record a new explicit exception for 1.10.0. + +## Not yet done + +- Tag, GitHub release and qualification asset (maintainer instruction required). +- Developer kit update to 1.10.0: the kit pins the exact published commit and + tree, so it follows the tag. diff --git a/Documentation/Qualification/ReleaseLines.md b/Documentation/Qualification/ReleaseLines.md index 70f7930..fa2a26c 100644 --- a/Documentation/Qualification/ReleaseLines.md +++ b/Documentation/Qualification/ReleaseLines.md @@ -1,4 +1,7 @@ -# Current source lines — 11 November 2026 +# Current source lines — 15 November 2026 + +Prepared 1.10.0 on `main` builds on published 1.9.0 and is not published. See +[its qualification record](Release1.10.md). Latest published stable is [1.9.0](https://github.com/ThorFuchs/Swift-JSON/releases/tag/1.9.0), commit `f2a0d12da7028edfbcb0cb307f19a921a3a12d03`, tree diff --git a/Documentation/README.md b/Documentation/README.md index 2e4a6c5..43e60cf 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -1,4 +1,10 @@ -# Current authority — 1.9.0 +# Current authority — 1.10.0 (prepared) + +Prepared 1.10.0 keeps the twelve libraries plus CLI and thirteen catalogs of +published 1.9.0 and adds exact interchange: canonical JSON, versioned envelopes, +RFC 6902 differences with a visual page and RFC 7464 text sequences. See the +[1.10 release notes](ReleaseNotes/1.10.0.md) and +[1.10 qualification record](Qualification/Release1.10.md). Published 1.9.0 has twelve libraries plus CLI and thirteen catalogs. It adds bounded batches and a public immutable store inside JSONInspection to 1.8.0. See the diff --git a/Documentation/ReleaseNotes/1.10.0.md b/Documentation/ReleaseNotes/1.10.0.md new file mode 100644 index 0000000..a1f1969 --- /dev/null +++ b/Documentation/ReleaseNotes/1.10.0.md @@ -0,0 +1,95 @@ +# Swift-JSON 1.10.0 — release notes + +This minor release is about exact interchange: canonical bytes for hashing and +signing, a versioned envelope for stored records, structural differences as RFC +6902 patches and as a visual page, and RFC 7464 JSON text sequences. Preparation +and tagging do not establish publication; the official GitHub release and its +qualification asset identify the final source and actual outcomes. + +## Added + +**Canonical JSON (RFC 8785).** `JSONCanonicalWriter` writes JSON +Canonicalization Scheme bytes: compact output, keys ordered by UTF-16 code units, +short string escapes and ECMAScript spelling of binary64 numbers. Equal values +produce equal bytes, so the output can be hashed, signed or used as a content +address. Because `JSONNumber` is an exact decimal, `NumberPolicy.preserving` (the +default) refuses a number whose binary64 spelling would denote a different value; +`.rounding` rounds as RFC 8785 does. Tests cover the RFC's Appendix B number +vectors, its sample document and its key-sorting example. The existing writer and +its scalar key order are unchanged. + +**Versioned envelopes.** `JSONEnvelope` stores one payload with a caller-chosen +`type` and schema `version` as one canonical object: + +```json +{"digest":"sha256:…","format":"swift-json-envelope","formatVersion":1,"payload":{…},"type":"mcp.task","version":3} +``` + +The digest is the SHA-256 of the payload's canonical bytes. Decoding accepts any +strict spelling, checks the marker, the six members, the format version, the +fields and the digest, and reports `JSONEnvelopeFailure` for invalid or damaged +records. Equal envelopes encode to equal bytes, and equal payloads have equal +digests. Format version 1 is fixed. Stores built on +[Swift-SQLite](https://github.com/ThorFuchs/Swift-SQLite) are the intended users; +Swift-JSON itself adds no persistence. + +**Structural differences.** `JSONPatch.difference(from:to:options:)` computes RFC +6902 operations that turn one exact value into another. Equal values produce no +operation, objects are compared by key, and arrays keep their longest equal prefix +and suffix and compare the rest by position. The result always applies to the +source to give the target. It is deterministic but not minimal, and it never uses +`move`, `copy` or `test`. + +**Visual differences.** `JSONHTMLRenderer.renderDifference(from:to:)` renders two +values as one static, script-free tree. Added, removed and changed values carry +text markers as well as color, and unchanged parts stay visible but collapsed. The +page has a summary, a change list linked by JSON Pointer, a CSS-only "Show changes +only" toggle and downloads of the patch, the source and the target. Its CSP sets +`script-src 'none'` and authorizes its stylesheets by hash. The comparison is a +package walker in JSON shared with `JSONPatch.difference`, so JSONHTML still +depends on JSON only. + +**JSON text sequences (RFC 7464).** `JSONTextSequence` reads +`application/json-seq` streams with the same pull model and budgets as NDJSON. +A top-level number, `true`, `false` or `null` without trailing whitespace is +treated as possibly truncated. Malformed texts fail by default; the `.skip` +policy skips and counts them as RFC 7464 recommends, but never skips resource +failures. `JSONTextSequenceWriter` writes RS, strict JSON and LF per value, as a +whole sequence or in awaited bounded chunks. + +## Maintenance + +These changes were collected for a 1.9.1 hygiene release that was not published +separately; they ship in 1.10.0. + +- A `platform-floor` CI lane checks the macOS 15 / iOS 18 manifest minimums, + cross-compiles every library for iOS 18 devices and the simulator, and builds + and runs an external consumer with the same minimums. +- The CLI source identity no longer covers DocC catalogs. +- Developer kit 0.2.0 targets published 1.9.0. The repository is a Claude Code + plugin marketplace. A kit update for 1.10.0 follows the 1.10.0 tag. + +## Platforms + +Unchanged from 1.9.0: macOS 15 and iOS 18 minimums, developed with Swift 6.4 and +the macOS 27 SDK (Xcode 27). Linux and WASI scope is unchanged. + +## Compatibility and qualification + +The release is additive over 1.9.0. The package keeps twelve library products +plus `swift-json`, thirteen DocC catalogs, Swift tools and compiler 6.4+, Swift +language mode 6, an empty root dependency graph, Apache-2.0 and retained upstream +notices. No product dependency changes. CLI metadata reports `1.10.0` with the +deterministic final-source identity. + +See the [1.10 qualification record](../Qualification/Release1.10.md) for the API +compatibility check, the local and CI lane outcomes and the open +controlled-performance decision. + +The work was integrated through +[PR #94](https://github.com/ThorFuchs/Swift-JSON/pull/94), +[PR #95](https://github.com/ThorFuchs/Swift-JSON/pull/95), +[PR #96](https://github.com/ThorFuchs/Swift-JSON/pull/96), +[PR #97](https://github.com/ThorFuchs/Swift-JSON/pull/97), +[PR #98](https://github.com/ThorFuchs/Swift-JSON/pull/98) and +[PR #99](https://github.com/ThorFuchs/Swift-JSON/pull/99). diff --git a/Documentation/ReleaseRoadmap.md b/Documentation/ReleaseRoadmap.md index 1637d25..2440df2 100644 --- a/Documentation/ReleaseRoadmap.md +++ b/Documentation/ReleaseRoadmap.md @@ -23,7 +23,7 @@ to 2.0.0. It replaces the earlier 1.10 persistence wave: | Release | Approved direction | | --- | --- | | **1.9.1 — hygiene** | Already on main: the `platform-floor` CI lane, the CLI source identity without DocC catalogs, branch housekeeping and developer kit 0.2.0. Tag/publication remains a separate decision. | -| **1.10.0 — exact interchange** | RFC 8785 JSON Canonicalization Scheme (canonical bytes for hashing, signing and content addressing); a versioned envelope built on it; structural diff producing an RFC 6902 patch; RFC 7464 JSON text sequences in JSONStreaming. | +| **1.10.0 — exact interchange (prepared)** | RFC 8785 JSON Canonicalization Scheme (canonical bytes for hashing, signing and content addressing); a versioned envelope built on it; structural diff producing an RFC 6902 patch, also rendered as a static JSONHTML page; RFC 7464 JSON text sequences in JSONStreaming. Integrated through PRs #95–#99; see the [release notes](ReleaseNotes/1.10.0.md). Tag and publication remain a separate decision. | | **1.11.0 — queries and diagnostics** | RFC 9535 JSONPath with finite budgets, kept separate from Transform semantics; detailed and basic JSON Schema output formats. | | **1.12.0 — API consolidation** | Review every public surface before 2.0: naming, error and limit consistency, deprecations with replacements and migration notes. No break in a minor release. | | **2.0.0 — compatibility contract** | Unchanged from the gate below: one documented compatibility, resource and platform contract for the accepted family, with migration guidance for every recorded break. | diff --git a/Sources/JSONCLIEngine/CLIBuildIdentity.swift b/Sources/JSONCLIEngine/CLIBuildIdentity.swift index ea9f983..439687a 100644 --- a/Sources/JSONCLIEngine/CLIBuildIdentity.swift +++ b/Sources/JSONCLIEngine/CLIBuildIdentity.swift @@ -2,6 +2,6 @@ // Generated by Scripts/generate_cli_identity.py; excludes this file. // SHA-256 of the ordered Package.swift + Sources content manifest (DocC catalogs excluded), not a Git commit. package enum CLIBuildIdentity { - package static let revision = "sha256:fd026d72a5ef7b9f545d4ab4b08edd1460af5d0630551034a16f066824e1fa39" + package static let revision = "sha256:99a750404f5c4af53abe83fb52194c296a09e9e69387be2d4a3984b09551e327" package static let kind = "source-sha256" } diff --git a/Sources/JSONCLIEngine/CLIReleaseVersion.swift b/Sources/JSONCLIEngine/CLIReleaseVersion.swift index 01acae9..9abcf0e 100644 --- a/Sources/JSONCLIEngine/CLIReleaseVersion.swift +++ b/Sources/JSONCLIEngine/CLIReleaseVersion.swift @@ -2,5 +2,5 @@ // Version of this source distribution. Publication is a separate action. package enum CLIReleaseVersion { - package static let value = "1.9.0" + package static let value = "1.10.0" } diff --git a/Tests/JSONCLITests/IntegrationTests.swift b/Tests/JSONCLITests/IntegrationTests.swift index 1ef51a7..de3db1f 100644 --- a/Tests/JSONCLITests/IntegrationTests.swift +++ b/Tests/JSONCLITests/IntegrationTests.swift @@ -146,7 +146,7 @@ private func integrationDirectory() throws -> URL { @Test func cliVersionIsDeterministicAndNeedsNoRepositoryOrInput() throws { let metadata = try JSONParser().parse(CLIHelp.versionJSON) - #expect(try metadata.requiredMember("version") == .string("1.9.0")) + #expect(try metadata.requiredMember("version") == .string("1.10.0")) #expect(try metadata.requiredMember("revisionKind") == .string("source-sha256")) let revision = try #require(try metadata.requiredMember("revision").stringValue) #expect(revision.hasPrefix("sha256:") && revision.utf8.count == 71) From ad1c8633c75863517163780ccaa84f0fdfe281da Mon Sep 17 00:00:00 2001 From: Thorsten Fuchs <76904008+ThorFuchs@users.noreply.github.com> Date: Mon, 16 Nov 2026 00:00:37 +0100 Subject: [PATCH 2/2] Record 1.10.0 preparation lane receipts Co-Authored-By: Claude Opus 5.5 --- Documentation/Qualification/Release1.10.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/Qualification/Release1.10.md b/Documentation/Qualification/Release1.10.md index c6f34d2..baaea50 100644 --- a/Documentation/Qualification/Release1.10.md +++ b/Documentation/Qualification/Release1.10.md @@ -66,6 +66,14 @@ cross-module DocC link; the fix changed a doc comment only and the docs lane the passed. Native for #98 ran on the commit before that fix; GitHub CI ran on the merged state. +On the preparation commit `deb16f5` (CLI version 1.10.0), `docs` passed 4 of 4 +commands. The first `native` run failed one command: +`Scripts/qualify_cli_limits.py` hit its 30-second subprocess timeout on a +`swift-json query` call while the host load average was about 56. Run alone, +that call took 9 ms and the script passed 33 of 33 observations. A full `native` +rerun on the same commit (load average falling from about 22) passed 62 of 62 +commands with exit 0. The failure is recorded here rather than omitted. + The `wasm` lane was not run locally for 1.10. The release commit needs its own exact CI receipts and a WASI run before tagging.