From 56707b7642c7adae97aff51d79886d2cbf18b325 Mon Sep 17 00:00:00 2001 From: Thorsten Fuchs <76904008+ThorFuchs@users.noreply.github.com> Date: Mon, 9 Nov 2026 17:51:02 +0100 Subject: [PATCH] Prepare 1.8.0 minor release metadata Report CLI version 1.8.0 with its deterministic source identity and regression assertion. Finalize the 1.8.0 changelog entry, add minor release notes for located root-array streaming, and move the proposed bounded structural workflows to 1.9.0 (durable workflows to 1.10.0) in the roadmap. Public APIs, finite budgets, platform baselines and historical performance holds are unchanged. Publication remains separate. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 6 +-- CHANGELOG.md | 6 ++- Documentation/ReleaseNotes/1.8.0.md | 54 +++++++++++++++++++ Documentation/ReleaseRoadmap.md | 9 ++-- Sources/JSONCLIEngine/CLIBuildIdentity.swift | 2 +- Sources/JSONCLIEngine/CLIReleaseVersion.swift | 2 +- Tests/JSONCLITests/IntegrationTests.swift | 2 +- 7 files changed, 70 insertions(+), 11 deletions(-) create mode 100644 Documentation/ReleaseNotes/1.8.0.md diff --git a/AGENTS.md b/AGENTS.md index 1bc2a84..697a4e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ # Contributor instructions -Prepared patch release source is 1.7.1; publication is a separate owner action. Its -parent development line is 1.7.0-dev and stable 1.6.1 remains separate. This is -not a maintenance release or the frozen 6fe8067 RC. Preserve all source-bound +Prepared minor release source is 1.8.0; publication is a separate owner action. It +adds located root-array streaming to the published 1.7.1 line; stable 1.6.1 remains +separate. This is not a maintenance release or the frozen 6fe8067 RC. Preserve all source-bound qualification history; source integration never publishes a version. Swift-JSON requires Swift tools/compiler 6.4+, Swift language mode 6 and diff --git a/CHANGELOG.md b/CHANGELOG.md index 87e6c59..23a054b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased — 1.8.0-dev +## 1.8.0 — prepared source; publication separate - Add `JSONLocatedTopLevelArraySequence` and `JSONLocatedTopLevelArrayEvent` to JSONStreaming. Each root-array element also reports its `JSONSourceSpan`: @@ -10,6 +10,10 @@ - Both root-array facades share one strict grammar and pull driver, so quotas, errors, statistics and completion are identical. `JSONTopLevelArraySequence` behavior and all existing products, dependencies and platforms are unchanged. +- Report CLI source version `1.8.0` with a regenerated deterministic source + identity. The proposed bounded structural workflows move to 1.9.0 in the + [roadmap](Documentation/ReleaseRoadmap.md). See the + [minor release notes](Documentation/ReleaseNotes/1.8.0.md). ## 1.7.1 — prepared source; publication separate diff --git a/Documentation/ReleaseNotes/1.8.0.md b/Documentation/ReleaseNotes/1.8.0.md new file mode 100644 index 0000000..cc8dc09 --- /dev/null +++ b/Documentation/ReleaseNotes/1.8.0.md @@ -0,0 +1,54 @@ +# Swift-JSON 1.8.0 — release notes + +This minor release adds located root-array streaming to JSONStreaming. +Preparation and tagging do not establish publication; the official GitHub release +and its qualification asset identify the final source and actual outcomes. + +## Added + +`JSONLocatedTopLevelArraySequence` reads one root array like +`JSONTopLevelArraySequence` and yields `JSONLocatedTopLevelArrayEvent` values: +`element(index:value:sourceSpan:)` for each element, then one +`documentCompleted(_:)` summary. The `JSONSourceSpan` contains zero-based, +half-open UTF-8 byte offsets in the complete stream. It covers the element token +or subtree only; surrounding whitespace and separators are excluded. Offsets count +encoded bytes, not characters or decoded scalars, and do not depend on how the +caller's source splits chunks. + +Spans are provisional until `documentCompleted`, exactly like the elements. The +reader retains no original bytes, starts no prefetch task and owns no file. A +consumer that needs a record's raw slice retains an immutable source separately +and applies the span to it. This lets applications that stage large exports +record each element's original location without a private fork of the package. + +Both root-array facades use one internal driver. Strict grammar, per-element and +iterator-lifetime quotas, `JSONFailure` values, statistics, cancellation and the +completion boundary are therefore identical. `JSONTopLevelArraySequence` keeps its +public API and observable behavior. + +The feature was integrated through +[PR #78](https://github.com/ThorFuchs/Swift-JSON/pull/78). Public-consumer tests +cover exact spans at every two-chunk split and with one-byte chunks, nested +containers, multi-byte UTF-8 and escapes, empty arrays, parity with the +value-only reader on valid and malformed inputs, and identical limit failures. + +## Compatibility and qualification + +The change is additive. No product, runtime dependency, platform or deployment +floor changes. The package keeps twelve library products plus `swift-json`, +thirteen DocC catalogs, Swift tools and compiler 6.4+, Swift language mode 6, +Apple OS/SDK 27+, an empty root dependency graph, Apache-2.0 and retained upstream +notices. CLI metadata reports `1.8.0` with the deterministic final-source identity. + +The roadmap's previously proposed 1.8 scope, bounded structural workflows, moves +to 1.9.0; durable workflows move to 1.10.0. Both remain proposed scope, not API +approval. + +The release qualification asset records actual source-bound Native, Linux, +safety, docs and archive outcomes. Navigation G4 remains HOLD with zero accepted +controlled timing samples. Transform's scoped performance disposition and +incomplete historical sampling windows are preserved, without a new measured +pass. The historical approximately 11% streaming regression disposition and +unchanged 10% review trigger remain. This release makes no speed, throughput, +allocation or RSS claim. Logical retained bytes and caller work retain their +documented accounting boundaries. diff --git a/Documentation/ReleaseRoadmap.md b/Documentation/ReleaseRoadmap.md index 550bb6c..cc138f9 100644 --- a/Documentation/ReleaseRoadmap.md +++ b/Documentation/ReleaseRoadmap.md @@ -49,17 +49,18 @@ there is no public store/follow API or store product. Root dependencies stay emp | Release | Proposed outcome | Gate before choosing a release date | | --- | --- | --- | | **1.7.0 — integrated foundations** | Release the complete current public consolidation together: Navigation/Inspection snapshots, projections and graph, Transform and both DSL products, alongside all stable products. Keep store implementation private. | Freeze current-main successor; qualify exact source, public consumers/API/DocC, archives/assets and supported platforms; resolve the new candidate's performance dispositions explicitly. | -| **1.8.0 — bounded structural workflows** | Add independently reviewed, additive Inspection conveniences: aggregate batch reads and, if separately admitted and qualified, the minimal immutable public configured-store/follow interface. Improve Navigation/Inspection guides and error/resource ergonomics. | One-ledger aggregate proof, finite request/result/frontier profiles, ordinary compiler refusals, adversarial failure/cancellation and complete supported-platform evidence. Store can remain private if its gate is not complete. | -| **1.9.0 — durable workflows and operational maturity** | Candidate wave for versioned exact snapshot/store persistence and source-bound restoration, after a dedicated design admission. Complete capacity/scaling characterization and consumer migration guidance. | Freeze the logical envelope, corruption/version/source-identity semantics, bounded decode/rebuild and disk teardown/reopen tests. No persistence or source-span claim from a bare JSON dump. | +| **1.8.0 — located root-array streaming** | Add JSONLocatedTopLevelArraySequence: root-array elements with zero-based half-open UTF-8 source spans over the existing shared grammar/driver, for consumers that stage original record bytes. | Additive public-consumer tests, facade parity on errors/limits/statistics, DocC and complete supported-platform CI on the exact source. | +| **1.9.0 — bounded structural workflows** | Add independently reviewed, additive Inspection conveniences: aggregate batch reads and, if separately admitted and qualified, the minimal immutable public configured-store/follow interface. Improve Navigation/Inspection guides and error/resource ergonomics. | One-ledger aggregate proof, finite request/result/frontier profiles, ordinary compiler refusals, adversarial failure/cancellation and complete supported-platform evidence. Store can remain private if its gate is not complete. | +| **1.10.0 — durable workflows and operational maturity** | Candidate wave for versioned exact snapshot/store persistence and source-bound restoration, after a dedicated design admission. Complete capacity/scaling characterization and consumer migration guidance. | Freeze the logical envelope, corruption/version/source-identity semantics, bounded decode/rebuild and disk teardown/reopen tests. No persistence or source-span claim from a bare JSON dump. | | **2.0.0 — supported family and compatibility contract** | Ship all accepted products/capabilities under one coherent, documented compatibility, resource and platform contract. Complete end-to-end applications, migration tooling and the release qualification matrix. | Scope freeze, complete public API review and cross-product qualification, explicit treatment of every remaining hold, reproducible clean candidate and a separate owner tag/publication instruction. | Release numbers are shared across all products. Do not remove already-integrated -public APIs merely to postpone a product to 1.8. Minor releases remain additive. +public APIs merely to postpone a product to 1.9. Minor releases remain additive. A major version is a deliberate compatibility commitment: record and justify any actual break and provide migration guidance; do not manufacture a break to reach 2.0. Dates follow exit gates, not a promised calendar. -The 1.8/1.9 entries are **proposed scope**, not API approval or permission to start +The 1.9/1.10 entries are **proposed scope**, not API approval or permission to start implementation. All planned packages at 2.0 means the explicitly accepted release portfolio. Lexical/semantic retrieval, embeddings, persistent indexes, weighted graph algorithms, set algebra, matrix arithmetic, JSONPath/another query grammar, diff --git a/Sources/JSONCLIEngine/CLIBuildIdentity.swift b/Sources/JSONCLIEngine/CLIBuildIdentity.swift index b61044d..d207128 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, not a Git commit. package enum CLIBuildIdentity { - package static let revision = "sha256:9d42eb6dbc4c0e23e7329ae1b3c278421d996c7446638e46cc5c1a07ab1240ac" + package static let revision = "sha256:ff976484187552cfd967cc4a750bd1f32f63bf37137e01b7343d4152a385273a" package static let kind = "source-sha256" } diff --git a/Sources/JSONCLIEngine/CLIReleaseVersion.swift b/Sources/JSONCLIEngine/CLIReleaseVersion.swift index 24f9d2b..945f7d0 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.7.1" + package static let value = "1.8.0" } diff --git a/Tests/JSONCLITests/IntegrationTests.swift b/Tests/JSONCLITests/IntegrationTests.swift index a6e9a46..8936fc3 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.7.1")) + #expect(try metadata.requiredMember("version") == .string("1.8.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)