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)