Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down
7 changes: 5 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down
91 changes: 91 additions & 0 deletions Documentation/Qualification/Release1.10.md
Original file line number Diff line number Diff line change
@@ -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 <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.
5 changes: 4 additions & 1 deletion Documentation/Qualification/ReleaseLines.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 7 additions & 1 deletion Documentation/README.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
95 changes: 95 additions & 0 deletions Documentation/ReleaseNotes/1.10.0.md
Original file line number Diff line number Diff line change
@@ -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).
2 changes: 1 addition & 1 deletion Documentation/ReleaseRoadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
2 changes: 1 addition & 1 deletion Sources/JSONCLIEngine/CLIBuildIdentity.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
2 changes: 1 addition & 1 deletion Sources/JSONCLIEngine/CLIReleaseVersion.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
2 changes: 1 addition & 1 deletion Tests/JSONCLITests/IntegrationTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading