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..baaea50 --- /dev/null +++ b/Documentation/Qualification/Release1.10.md @@ -0,0 +1,91 @@ +# 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. + +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. + +## 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)