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
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
6 changes: 5 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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`:
Expand All @@ -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

Expand Down
54 changes: 54 additions & 0 deletions Documentation/ReleaseNotes/1.8.0.md
Original file line number Diff line number Diff line change
@@ -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.
9 changes: 5 additions & 4 deletions Documentation/ReleaseRoadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
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, 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"
}
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.7.1"
package static let value = "1.8.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.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)
Expand Down