diff --git a/AGENTS.md b/AGENTS.md index a9f132d..b0ca32d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,9 @@ # Contributor instructions -Development source is 1.7.0-dev. This consolidation retains the stable 1.6.1 line -separately; it is not a maintenance release or the frozen 6fe8067 RC. Preserve -all source-bound qualification history. Main integration never publishes a version. +Prepared release source is 1.7.0; 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 +qualification history; source integration never publishes a version. Swift-JSON requires Swift tools/compiler 6.4+, Swift language mode 6 and macOS/SDK 27+. Read README.md, CONTRIBUTING.md and the relevant contracts in diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f240da..dfe6eb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased — 1.7.0-dev consolidation +## 1.7.0 — prepared source; publication separate - Reconcile admitted set/matrix APIs with the reviewed public directed graph, shared JSONTransform compiler/pull VM and optional exact value/schema DSLs. @@ -11,7 +11,12 @@ - Preserve finite exact semantics and all predecessor fixtures, failures and performance/platform holds. Require fresh combined-source qualification; a merge is development integration and does not publish a version. -- See [combined qualification](Documentation/Qualification/Consolidation2026.md). +- Prepare the combined source with CLI version1.7.0 and a regenerated deterministic + source digest. Record exact final-source outcomes in the + [release checklist](Documentation/Qualification/Release1.7Preparation.md) and + [release notes](Documentation/ReleaseNotes/1.7.0.md). +- Preserve [consolidation qualification](Documentation/Qualification/Consolidation2026.md) + and every historical failed attempt; neither preparation nor CI creates a release. ### Historical JTX10 release-candidate checkpoint (unpublished) @@ -29,6 +34,14 @@ - See [candidate qualification](Documentation/Qualification/Release1.7.0.md) for source-bound gates, Apple/Linux/scoped WASI claims and historical holds. +### Historical authored-DSL prototype checkpoint (unpublished) + +The value/schema DSL proposal was developed against the earlier 1.4-era source, +but JSONValueDSL and JSONSchemaDSL are absent from the published 1.4.0, 1.5.0 and +1.6.1 manifests. Their first combined public-product preparation is this 1.7 source. +The prototype introduced trusted authored values/schema documents with native exact +semantics and finite iterative finalization; staging/callbacks remain caller work. + ### Historical JSONTransform extraction checkpoints - Add an optional public compiler/pull API over the single existing private query kernel. @@ -113,11 +126,6 @@ The protected public version tag exists; its separate GitHub release remains draft. These additive APIs are also included in the published 1.5.0 release. -- Add opt-in JSONValueDSL and JSONSchemaDSL products for typed, trusted authored - values and Draft 2020-12 declarations. Exact values and schema semantics remain - owned by the existing engine. Finalization uses one finite iterative ledger; - authored staging and callbacks are explicitly outside its resource accounting. - - Add E2's shallow JSON parsing, checked object construction, decimal-text and pre-parsed Pointer entry points; exact-key membership and three-state presence composition; and direct validation from an immutable compiled schema plan. diff --git a/Documentation/Architecture/API.md b/Documentation/Architecture/API.md index 1becebf..c8e167f 100644 --- a/Documentation/Architecture/API.md +++ b/Documentation/Architecture/API.md @@ -354,12 +354,22 @@ follows from this contract. ## 1.7.0 release-candidate authority -This unpublished candidate retains the accepted Transform API (42 authored -declarations) and Inspection API (95), with all 56 Navigation declarations -unchanged. Historical provisional headings above remain stable link targets and -checkpoint descriptions; the [candidate contract](../Qualification/Release1.7.0.md) -and final compiler graphs determine current scope. API shape acceptance does not -imply publication, measured allocations or unobserved platform execution. +The current consolidated 1.7 source has twelve library products plus the CLI and +thirteen DocC catalogs, including shared non-product JSONDSLCore. Its qualified +compiler graphs contain 1,500 authored declarations: Transform 42, Inspection 162 +and Navigation 56, with the remaining declarations in the other catalogs. +The [combined qualification contract](../Qualification/Consolidation2026.md) and +[source-line matrix](../Qualification/ReleaseLines.md) define this source boundary. +A final versioned candidate must bind its own inventory, checks and assets. + +Historical provisional headings above remain stable link targets. The earlier +[frozen RC contract](../Qualification/Release1.7.0.md) belongs to `6fe8067`: ten +libraries plus CLI, 1,214 authored declarations and Inspection 95. It is retained +history, not the current consolidated inventory or a later-source pass. + +Transform's accepted 42 declarations and one compiler/VM remain unchanged. +API shape acceptance does not imply publication, measured allocations or +unobserved platform execution. ## Optional Dual DSL P1.2 diff --git a/Documentation/CLI.md b/Documentation/CLI.md index 1065143..9436c4a 100644 --- a/Documentation/CLI.md +++ b/Documentation/CLI.md @@ -46,8 +46,17 @@ source, compiler and architecture; library WASI results are a separate boundary. ## Version and source identity -This candidate reports `1.7.0`; latest stable remains `1.6.1`. The source version -does not establish a published version tag. See the [candidate scope and exception](Qualification/Release1.7.0.md). +Development main and a versioned release candidate are distinct sources. Read +`--version` and `--version --json` from the selected checkout: development main +uses `1.7.0-dev`, while a separately frozen 1.7.0 candidate uses `1.7.0` after its +version metadata and source identity are updated and qualified. Neither value +establishes publication. Latest stable remains `1.6.1`. + +The [source-line matrix](Qualification/ReleaseLines.md) and +[consolidation contract](Qualification/Consolidation2026.md) describe the current +twelve-library source. The [older RC contract](Qualification/Release1.7.0.md) +retains its ten-library inventory and scoped performance exception as history; +it does not qualify a later combined candidate. The frozen 1.5.0 executable reports `1.4.0-dev` and revision `unknown`; its release notes disclose that limitation. The 1.5.1 maintenance release corrects it, and diff --git a/Documentation/Performance/README.md b/Documentation/Performance/README.md index 9eefb46..dc63107 100644 --- a/Documentation/Performance/README.md +++ b/Documentation/Performance/README.md @@ -28,5 +28,9 @@ pattern and aggregate-byte quotas; sharing does not bypass admission or work. Logical retained bytes differ from process RSS. Darwin ru_maxrss is cumulative; allocator end observations are not isolated workload allocations. These results make no cross-machine throughput or OS-enforced memory guarantee. Source-attached structural views in unreleased Inspection carry no performance -claim (G4 HOLD). P2 matrix/graph/store/set/retrieval and JSON text-sequence framing -remain deferred. +claim (G4 HOLD). Consolidated 1.7 source includes set/matrix and directed graph +capabilities in JSONInspection, plus package-only store construction/preparation. +Their source admission does not close G4 or establish a speed, allocation or RSS +claim. Public store/follow, wider retrieval/persistence, NAV13 batches and JSON +text-sequence framing remain separately gated, unadmitted work. See the +[combined scope and holds](../Qualification/Consolidation2026.md). diff --git a/Documentation/Qualification/Release1.7Preparation.md b/Documentation/Qualification/Release1.7Preparation.md new file mode 100644 index 0000000..9a9b8c7 --- /dev/null +++ b/Documentation/Qualification/Release1.7Preparation.md @@ -0,0 +1,84 @@ +# 1.7.0 combined release preparation + +This contract records preparation of the combined twelve-library1.7.0 source, +not historical RC6fe8067. At preparation, latest stable remains1.6.1. Final source +identity, gate outcomes and performance decisions belong to the qualification +receipt; publication is established by the official release. Preparing a candidate +does not authorize a protected merge, tag or GitHub release publication. + +## Candidate scope + +The release includes JSON, JSONSchema, JSONSchemaExamples, JSONStreaming, +JSONPatch, JSONHTML, JSONBridges, JSONNavigation, JSONInspection, JSONTransform, +JSONValueDSL, JSONSchemaDSL and swift-json. JSONDSLCore is a shared public module +without a product. Root dependencies remain empty. Preserve Swift 6.4+/language 6, +macOS/iOS 27 minima, Apache-2.0 and all upstream notices. + +Navigation 56, Inspection 162, Transform 42 and the total 1,500 authored declarations +are the current reviewed baseline. No new store/follow, batches, persistence, +query grammar, resolver, platform or public API is added during preparation. +Store construction/preparation stays package-only. All existing operation, source +identity, error, cancellation, concurrency and finite-budget contracts remain. + +## Shared source ownership + +Use one final-source candidate. Navigation/Inspection preparation owns the common +freeze ledger, version/CLI identity, release envelope and combined qualification +binding. Transform review owns API/lifecycle/accounting/shared-kernel findings, +its targeted documentation and the scoped performance evidence/disposition +proposal. Integrate only reviewed focused commits, never whole obsolete drafts. +Do not edit shared main or rewrite the frozen RC. + +## Final freeze checklist + +| Gate | Required evidence | +| --- | --- | +| Source lease | Current main/base/head/tree, branch/ruleset/check/thread review; no protected-ref changes | +| Transform review | Explicit current-source findings and resolution of concrete contract failures; no speculative feature expansion | +| Version and identity | Candidate CLI 1.7.0, matching literal regression and site metadata, deterministic digest regenerated after final Source/manifest edits | +| Public boundary | Compiler-derived 1,500 declarations preserved; optional import boundaries, private stores/constructors/runtime/context inaccessible | +| Behavior and safety | Native Debug/Release, ASan, TSan, strict/lifetime, ownership full codegen; complete identities and parameter populations | +| Portability | Actual Linux ARM64/x86_64 and explicitly source-bound WASI/Apple scopes; SDK compilation is not device runtime | +| Resource/conformance | All 49 core caps, 16 CLI metrics, 126 restoration identities, pinned independent cases and ordinary-invalid/operational-error separation | +| Consumers and docs | Actual final revision consumers, executable guide/README blocks,13 catalogs, full comments and verified routes/indexes/links | +| Performance disposition | Source-bound G4/P4 measured outcome or explicit applicable maintainer decision; no allocation/RSS/speed claim from partial telemetry | +| Reproducibility | Actual source archive, embedded manifest, byte-equal rebuild, clean Git-free qualification and actual provider receipts | +| Public envelope | Reviewed release notes, source/compiled DocC archives, sanitized public qualification summary, checksums, notices/dependencies/privacy | +| Integration/tag/publication | Separate deliberate owner actions after final-head review and all applicable gates; no automatic release from preparation/CI | + +Baseline main qualification is evidence for its exact source. A changed candidate +needs a fresh binding; an unchanged-source reuse must identify precisely which +inputs, flags, commands and scopes are equal. Never relabel an old source run as +a new execution. Preserve every failed attempt and its successful retry separately. + +Current expected roots remain 975 native / 959 Linux / 871 WASI, 390 native/Linux and +353 WASI parameter invocations, targeted sharing 60/59. These are discovery +requirements, not preclaimed final-candidate outcomes. Public declaration counts +exclude compiler synthesis; catalog/module count differs from product count. + +## Performance and platform limits + +Navigation G4 remains HOLD, with zero accepted controlled timing samples. +The original Transform P4 waiver applies to its historical scoped candidate; +later 44/150 and 119/150 windows remain separate partial populations with the +original incomplete-output incident retained. Neither is a new candidate's +allocation/overhead pass. Record any final-source scope mapping and decision +explicitly under the unchanged 10% review trigger. Logical retained bytes are +not process RSS or heap allocation totals; caller work is not an owned instruction +quota. Do not benchmark a busy host or manufacture measurements. + +Retain the historical approximately 11% streaming disposition. Do not broaden +mobile/device, full-root WasmKit, WASI sanitizer, CLI/file-I/O, browser, Embedded +Swift or lower-deployment claims beyond actual source-bound evidence. The physical +iPad deferral remains explicit; simulator output is not physical-device evidence. + +## Assets and publication boundary + +The private working ledger may contain local paths, approvals, raw crash traces +and provider archives. None belongs in public release assets. Publishable assets +need a public-safe receipt with actual commands, source/fixture/toolchain pins, +counts and limitations. Verify every archive/checksum byte before upload. + +A path/revision consumer does not prove a nonexistent 1.7.0 version tag. Actual tag +resolution, asset downloads, released DocC and Swift Package Index checks follow +separately authorized tag/publication. Stable1.6.1 remains unchanged throughout. diff --git a/Documentation/Qualification/ReleaseLines.md b/Documentation/Qualification/ReleaseLines.md index c2b2326..40adade 100644 --- a/Documentation/Qualification/ReleaseLines.md +++ b/Documentation/Qualification/ReleaseLines.md @@ -5,6 +5,7 @@ | Published 1.6.0 | `f975ac1c5a18af9b422db0994cbc551fd37eee2f` | Eight libraries plus CLI, eight catalogs, 1,077 authored declarations | | Published 1.6.1 (latest stable) | `e431f157ececc0cf3d061192420b0e36a9062f83` | Same eight-library public API and runtime as 1.6.0; no Inspection | | Consolidated development source | Main, retaining N2 admitted at `2b24f47e7405821240cf8dfc66b840c9a7f8efa5` | Twelve libraries plus CLI; thirteen catalogs including shared JSONDSLCore; compiler-derived API inventory required | +| Prepared combined 1.7.0 source | Final candidate SHA/tree belongs to its qualification receipt; no tag implied | Same twelve libraries plus CLI, thirteen catalogs and expected 1,500 authored declarations; see current preparation checklist | Source versions do not establish publication. Consult the [official releases](https://github.com/ThorFuchs/Swift-JSON/releases) for published @@ -37,6 +38,20 @@ Stable 1.6.1 has neither. Consolidated development source stays 1.7.0-dev with t performance remains HOLD without speed claims; this is distinct from technical qualification and does not authorize any release/tag. +## Combined 1.7.0 preparation + +The [current preparation checklist](Release1.7Preparation.md) and +[draft release notes](../ReleaseNotes/1.7.0.md) describe the twelve-library candidate +being prepared from current main. Its final source is not yet frozen. They are +separate from the historical ten-library RC contract below; latest stable remains +1.6.1 until actual publication. + +## Forward release plan + +See the [1.7–2.0 roadmap](../ReleaseRoadmap.md) for the proposed shared-version +sequence, current product inventory, direct Navigation ownership and remaining +source-bound release gates. The proposal creates no release or new API approval. + ## Historical JTX10 unpublished 1.7.0 candidate The isolated JTX10 successor integrates main diff --git a/Documentation/ReleaseNotes/1.7.0.md b/Documentation/ReleaseNotes/1.7.0.md new file mode 100644 index 0000000..10db693 --- /dev/null +++ b/Documentation/ReleaseNotes/1.7.0.md @@ -0,0 +1,59 @@ +# Swift-JSON 1.7.0 — release notes + +These notes describe the combined1.7.0 source. They do not establish publication; +consult the official release and its source-bound qualification asset. The +[release checklist](../Qualification/Release1.7Preparation.md) defines the gates. + +## Included capabilities + +- Add JSONInspection as an opt-in library: factual complete/prefix array evidence, + source-attached structural snapshots, checked trees/sparse object tables, + first-occurrence exact structural sets, exact numeric matrix orientation and + source-bound directed graphs with bounded complete BFS. +- Add JSONTransform over the existing shared compiler/pull VM, with guarded + invocation-owned execution, exact native output and cumulative CLI accounting. +- Add JSONValueDSL and JSONSchemaDSL for trusted authored values/schema documents. + Finite checked finalization uses existing exact values and native schema + compilation/validation; authored staging/callbacks remain caller work. +- Retain every existing core/schema/example/stream/Patch/HTML/bridge/Navigation + product and the CLI. Twelve libraries plus CLI share the release version; + JSONDSLCore provides shared public generic structure without its own product. + +## Compatibility and scope + +The public API is additive to stable 1.6.1. Exact bounded decimals, decoded scalar +identity, ordered object storage/order-independent equality, strict UTF-8, offline +immutable schema plans, operation budgets and source-map coherence remain binding. +Default profiles remain finite. Construction and each separately reported read +retain their documented admission boundaries; caller pipelines are not implicitly +one ledger. Missing, explicit null, typed shape failures, operational exhaustion +and cancellation remain distinct. + +Apple baselines remain tools/compiler 6.4+, language 6 and macOS/iOS/iPadOS 27+. +Linux and WASI claims retain their qualified architecture/runtime/host scopes. +The final receipt must state actual supported-lane outcomes rather than deriving +mobile runtime, full CLI/WASI, browser or sanitizer guarantees from compilation. +No runtime package dependencies or new backend are introduced. + +Private configured-store preparation/construction remains internal to the package. +Public store/follow, NAV13 aggregate access, persistence, retrieval and text-sequence +framing are not part of this release. No matrix arithmetic, graph serializer or +alternative JSON/query semantic authority is added. + +## Qualification and known limits + +Final-source Native/Linux/safety/ownership/consumer/DocC/archive and scoped portable +receipts are required before release. Independent suite policy exclusions are +separate from evaluated successes. Swift Build planner incidents and successful +unchanged-source retries remain visible; no unconfirmed toolchain fix is claimed. + +Controlled Navigation performance remains HOLD. Transform's historical scoped +P4 waiver and later partial sampling windows are not an allocation pass. The +final-source performance disposition belongs to the qualification receipt; no +speed/throughput/allocation- +efficiency/RSS claim is made. Logical accounting is not physical memory. +The existing streaming regression disposition and 10% review trigger are unchanged. + +Final source, public qualification, compiled documentation and checksum assets +will be attached only after their actual byte/source checks and the maintainer's +separate release actions. See [the roadmap](../ReleaseRoadmap.md) for later waves. diff --git a/Documentation/ReleaseRoadmap.md b/Documentation/ReleaseRoadmap.md new file mode 100644 index 0000000..550bb6c --- /dev/null +++ b/Documentation/ReleaseRoadmap.md @@ -0,0 +1,140 @@ +# Release roadmap: 1.7 through 2.0 + +Maintainer working proposal, audited 27 October 2026. The next step is a release +freeze review, not a tag or publication. This roadmap authorizes no new public API +and does not supersede existing semantic, resource, ownership or platform gates. + +## One repository, one package version + +Swift-JSON is one SwiftPM package with separately selectable products. A repository +tag versions all products in that tag. JSONNavigation is already released in +1.6; Inspection is a different optional product. Do not give Navigation a separate +version or repository merely to describe the Structural Intelligence programme. +A split would need an independent dependency/versioning design. + +The audited development baseline is main +`15aa7e432cbb7173aa94b91e32badd1ab2695068` (PR #69). It contains twelve library +products and the CLI, thirteen reference catalogs including the non-product +JSONDSLCore module, and 1,500 compiler-derived authored declarations. The latest +published stable version is 1.6.1. The frozen historical Transform RC at 6fe8067 +is a different source and must not replace current main during release preparation. +See [source lines](Qualification/ReleaseLines.md) and +[combined qualification](Qualification/Consolidation2026.md). + +## Product and capability inventory + +| Selectable product | Current capability | Publication boundary | +| --- | --- | --- | +| JSON | Exact decimals/scalar keys, strict codec, Codable, Pointer, presence, source documents, finite operation reports | Existing stable product | +| JSONSchema | Offline Draft 2020-12 plans, native bounded regex, annotations and declaration inspection | Existing stable product | +| JSONSchemaExamples | Exact deterministic candidates with native validation/certification | Existing stable product | +| JSONStreaming | Pull events/values, strict NDJSON, root-array completion and awaited sinks | Existing stable product | +| JSONPatch | Staged RFC 6902 and RFC 7396; root removal distinct from null | Existing stable product | +| JSONHTML | Formatted/interactive inspection, annotations and qualified Apple transfer/export backends | Existing stable product; platform scopes stay explicit | +| JSONBridges | Opt-in checked native/Foundation conversions | Existing stable product; core does not re-export | +| JSONNavigation | Exact typed DFS traversal, physical/virtual scopes and coverage | Existing stable product; 56 authored declarations unchanged | +| JSONInspection | Array evidence, source-attached snapshots, trees, sparse tables, structural sets, exact numeric matrices and source-bound directed graphs | Public development source; not supplied by 1.6.1 | +| JSONTransform | Exact query compiler/VM facade, bounded execution and accounted CLI adapter | Public development source; 42 accepted declarations | +| JSONValueDSL | Trusted authored value construction with checked finalization | Public development source | +| JSONSchemaDSL | Trusted authored schema documents using the native compiler/validator | Public development source | +| swift-json | Existing CLI workflows, sharing the Transform implementation | Existing stable executable; new development engine must be qualified | + +JSONDSLCore has 82 authored public generic declarations needed by the DSLs, but +no standalone product. Regex/filter/CLI runtime targets remain package-private. +Store preparation and construction are also package-only inside JSONInspection; +there is no public store/follow API or store product. Root dependencies stay empty. + +## Proposed release sequence + +| 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. | +| **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. +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 +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, +new backends and text-sequence framing have no automatic place in this promise. +If a later scope review admits one, give it its own product-boundary decision, +finite profiles, fixtures and release gate. Do not rename speculative designs +into committed packages. + +## Navigation and Inspection ownership + +The maintainer can operate this train directly through the repository's normal +PR/review workflow; an external coordination layer is not a release dependency. +Use current main as the sole integration authority. Keep JSONNavigation focused +on traversal and JSONInspection on checked observations/views. Prefer public +consumers over private-meter test shortcuts. New APIs require an exact compiled +surface review before promotion, with ordinary full-codegen negatives and no +escaping cursor/context, replacement ledger or second root admission. + +The first bounded work queue after the 1.7 freeze is: + +1. Record the Navigation56/Inspection162 public boundary and compiled examples on + the frozen source. Preserve factual prefix evidence versus complete admission. +2. Admit NAV13's batch design: caller order/repeats, complete results or throw, + one source admission/ledger and explicit request/output alias retention. Do not + implement batches as loops over independently admitted single reads. +3. Review the private store profile and ownership/error precedence before proposing + public construction/follow. Source-local handles are not persistent IDs; cycles + and missing/null/reference states need explicit, bounded semantics. +4. Consider durable snapshots/store restoration only after that contract settles. + A rewritten root does not acquire invented original source spans. + +## Consolidation and branch discipline + +PR #66 admitted set/matrix; PR #69 reconciled graph, Transform, DSL and private +store source with current main. Historical donor drafts are provenance, not a +second integration backlog. Replaying them wholesale could restore old manifests, +remove later functionality or duplicate semantics. Squash ancestry alone cannot +prove whether a feature was incorporated: inspect donor source and the recorded +component mapping. Close a proven superseded draft as superseded, not merged. + +Use one short-lived feature branch per independently reviewable increment, based +on fresh main. Keep protected main/tag rules and the `Native / native`, `Native / safety`, +`Native / docs` contexts unchanged. A clean worktree whose exact head is a merged PR +can be archived recoverably after confirming no new work or needed ignored files. +The app's active/shared ownership guard must be honored; retire such a checkout +from its owning task instead of deleting directories manually. Preserve held +composition/root and lower-platform proposals until independently dispositioned. +Maintenance releases use the 1.6 line; do not merge old release branches into main +just to make ancestry look simpler. + +## Required release evidence and remaining holds + +Current-main hosted Native and both Linux architectures are green, with the +original x86 Swift Build planning crash and its unchanged-source retry retained. +Actual roots are 975 native / 959 Linux functions with 390 parameters, targeted +sharing 60/59; all 49 core caps, 16 CLI metrics, 126 maintenance identities and +independent fixture policies remain required. The current WASI contract expects +871 functions/353 parameters, with separately stated Node/WasmKit scopes. SDK +compilation is not a new mobile-device runtime qualification. + +Existing unchanged-source evidence can be reused only with explicit source/flag +equality and scope. A successor freeze must bind every claim to its final source +SHA/tree/archive. Required checks include public consumers, original ownership +codegen, Debug/Release/ASan/TSan/strict checking, supported Linux/WASI/Apple lanes, +13 DocC catalogs, link/privacy/license/dependency review, clean Git-free rebuilding +and exact artifact checksums. Policy exclusions are not evaluated suite successes. + +Controlled Navigation G4 remains HOLD. Transform's historical one-time P4 waiver +for the frozen RC and later partial 44/150 and 119/150 populations do not qualify +a new consolidated candidate or constitute measured allocation totals/overhead. +A new release must either satisfy the applicable measurement gate or receive an +explicit source-bound maintainer disposition. Keep the unchanged 10% review +trigger, historical streaming disposition and zero unproven performance claims. +Logical retained bytes are not RSS/heap measurements; caller work is not owned +instruction work. Do not run a controlled characterization on a busy host. + +Tagging, draft release creation and publication remain separately deliberate +maintainer actions under [RELEASING.md](../RELEASING.md). This roadmap creates none. diff --git a/README.md b/README.md index 332abd3..4137295 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,17 @@ # Swift-JSON -This is **unreleased 1.7.0-dev consolidation source**. Latest stable remains -**1.6.1**; no new tag or release is implied. It combines the existing Navigation -and Inspection projections with the reviewed source-bound graph, JSONTransform -and optional JSONValueDSL/JSONSchemaDSL proposals. The manifest has twelve library -products plus the CLI. The shared JSONDSLCore module has no standalone product; -its reference makes thirteen DocC catalogs. Stable 1.6.1 keeps eight libraries. - -Each combined source must pass fresh qualification; predecessor green checks do -not qualify a new tree. See the [consolidation contract](Documentation/Qualification/Consolidation2026.md). +This is **Swift-JSON 1.7.0 source prepared for release**. Version metadata identifies +the source; the [official releases](https://github.com/ThorFuchs/Swift-JSON/releases) +establish publication. At preparation, latest stable remains **1.6.1**. No tag or +publication is implied by this checkout. The source combines exact Navigation and +Inspection projections/graphs, JSONTransform and optional JSONValueDSL/JSONSchemaDSL. +It has twelve library products plus the CLI and thirteen DocC catalogs including +the shared, non-product JSONDSLCore reference. + +See the [combined release checklist](Documentation/Qualification/Release1.7Preparation.md), +[release notes](Documentation/ReleaseNotes/1.7.0.md) and +[1.7–2.0 roadmap](Documentation/ReleaseRoadmap.md). Every final candidate claim +requires source-bound receipts; predecessor green checks alone do not qualify it. See the [release-line matrix](Documentation/Qualification/ReleaseLines.md) for exact source scopes and publication boundaries. Version metadata identifies source; the @@ -36,7 +39,7 @@ eight DocC catalogs and the unchanged 1.6 API/runtime. The optional verified sch examples, structural traversal, structured HTML previews and bounded composition were introduced in 1.6.0. Exact JSON and offline schema validation remain the semantic authorities. -The published CLI reports `1.6.1`; this development source reports `1.7.0-dev`. +The published 1.6.1 CLI reports `1.6.1`; this prepared source reports `1.7.0`. Both use a deterministic source-content digest. The [published 1.6.1 release](https://github.com/ThorFuchs/Swift-JSON/releases/tag/1.6.1) is pinned to `e431f157ececc0cf3d061192420b0e36a9062f83`. Use its matching eight-catalog diff --git a/RELEASING.md b/RELEASING.md index ab2c50e..7ec54a5 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,5 +1,9 @@ # Release process +Use the [release roadmap](Documentation/ReleaseRoadmap.md) for the proposed 1.7–2.0 +sequence. All SwiftPM products in a repository tag share that version; a roadmap +is not tag, publication or new public API approval. + Keep the [stable/development matrix](Documentation/Qualification/ReleaseLines.md) source-bound. Prepare 1.6 maintenance releases from the pre-N2 line, not current main. Preserve published tags/assets and map applicable maintenance changes to @@ -31,13 +35,15 @@ or releases. Published version tags are protected against updates and deletion. Keep private records, credentials, input clones and build outputs out of source archives and Git history. 4. Measure changed workloads on an idle supported host unless a specific maintainer - exception is recorded. For this 1.7.0 candidate, the maintainer explicitly authorized - loaded-host observations and a one-time allocation-instrumentation waiver; the full - allocation gate remains unqualified. Later 44-profile and 119-pair observations - are partial, loaded-host evidence, not passed population/overhead measurements. See - Documentation/Qualification/Release1.7.0.md. A 10% median or retention - change still triggers review. Preserve the documented streaming regression disposition; - logical retained bytes do not imply an RSS guarantee. + exception is recorded for the actual final source. The frozen RC6fe8067's + loaded-host observations and one-time Transform allocation-instrumentation + waiver remain historical scoped evidence. Later44/150 and119/150 windows are + partial, not population/overhead passes. A combined1.7 candidate needs an + explicit scope mapping and final-source disposition; do not infer blanket + acceptance from the version number. Preserve Navigation G4 HOLD, the unchanged + 10% review trigger and historical streaming disposition. Logical retention is + not RSS/heap allocation. See [current preparation](Documentation/Qualification/Release1.7Preparation.md) + and the [historical contract](Documentation/Qualification/Release1.7.0.md). 5. Update CHANGELOG.md and compatibility notes, then run `python3 Scripts/archive_candidate.py --output Artifacts/Swift-JSON-public-candidate.tar.gz`. Verify embedded hashes, byte-equal rebuild and a clean extracted build/test with diff --git a/Scripts/build_documentation_site.py b/Scripts/build_documentation_site.py index 73b1212..d17ad71 100644 --- a/Scripts/build_documentation_site.py +++ b/Scripts/build_documentation_site.py @@ -20,7 +20,7 @@ REPOSITORY = 'https://github.com/ThorFuchs/Swift-JSON' BASE_PATH = '/Swift-JSON' SITE_URL = 'https://thorfuchs.github.io' + BASE_PATH + '/' -SOURCE_VERSION = '1.7.0-dev' +SOURCE_VERSION = '1.7.0' STABLE_VERSION = '1.6.1' GUIDES = {'JSON': ('Exact values and native coding', 'exactvaluesandcoding'), 'JSONSchema': ('Offline schema validation', 'offlinevalidation'), @@ -115,7 +115,7 @@ def landing(commit):

Exact JSON. Clear contracts.

Keep decimal values exact, Unicode scalar keys distinct and resource use explicit. Explore {len(PRODUCTS)} Swift libraries that carry those semantics from input bytes to validated, transformed and encoded output.

Swift 6.4+ · Swift language mode 6 · macOS/SDK 27+ · No package dependencies

-

Development main includes JSONInspection; this unpublished candidate also includes JSONTransform. Stable {STABLE_VERSION} has eight library catalogs; use its matching compiled DocC assets or tagged source documentation.

+

Development main includes JSONInspection, JSONTransform and the optional authored DSLs; this source is prepared as 1.7.0. Stable {STABLE_VERSION} has eight library catalogs; use its matching compiled DocC assets or tagged source documentation.

{''.join(cards)}

Start with the contract

Read the package overview and executable examples, then choose a reference above. The behavior contracts explain exact numbers, scalar identity, offline schema evaluation, cumulative budgets and stream completion.

diff --git a/Sources/JSONCLIEngine/CLIBuildIdentity.swift b/Sources/JSONCLIEngine/CLIBuildIdentity.swift index f35ccd9..a659e0c 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:d59b22f51833ddf5c3cb9da7d7a4cd5c606021f2998cf59113e081015f6e1491" + package static let revision = "sha256:138ae7e8bc2f4392db7aafaa000f60db5915658a1b34a55f12a9c27958da1312" package static let kind = "source-sha256" } diff --git a/Sources/JSONCLIEngine/CLIReleaseVersion.swift b/Sources/JSONCLIEngine/CLIReleaseVersion.swift index edbb5a4..6ed3782 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.0-dev" + package static let value = "1.7.0" } diff --git a/Sources/JSONTransform/Documentation.docc/JSONTransform.md b/Sources/JSONTransform/Documentation.docc/JSONTransform.md index 982e599..ee828d3 100644 --- a/Sources/JSONTransform/Documentation.docc/JSONTransform.md +++ b/Sources/JSONTransform/Documentation.docc/JSONTransform.md @@ -2,8 +2,9 @@ Compile the existing exact query dialect and pull bounded native JSON results. -This is the optional transformation library in the unpublished 1.7.0 release candidate. -Publication requires a separate maintainer decision. It shares one private compiler +This is the optional transformation library in the unreleased 1.7 source line. +Development main and a separately versioned candidate retain their own source +identities and qualification. Publication requires a separate maintainer decision. It shares one private compiler and VM with `swift-json query`; it does not introduce a new interpreter or numeric authority. Plans are immutable and Sendable. Each synchronous invocation has one finite cumulative meter and a guarded, non-Sendable execution handle. diff --git a/Sources/JSONTransform/Documentation.docc/ScopedTransforms.md b/Sources/JSONTransform/Documentation.docc/ScopedTransforms.md index 7bc7ec1..966c699 100644 --- a/Sources/JSONTransform/Documentation.docc/ScopedTransforms.md +++ b/Sources/JSONTransform/Documentation.docc/ScopedTransforms.md @@ -19,7 +19,19 @@ let report = try plan.withExecution(input: root) { execution in The plan uses the same exact decimal and decoded-scalar rules as JSON and the CLI. Nonterminating division is a language error; no approximate arithmetic is added. The standalone public consumer at `Tools/TransformQualification` is available -in this feature candidate; it is absent from stable 1.6.1. +in this unreleased source line; it is absent from stable 1.6.1. + +## Shared language reference + +The library and CLI execute the same jq-inspired subset. The shared +[command/filter reference](https://github.com/ThorFuchs/Swift-JSON/blob/15aa7e432cbb7173aa94b91e32badd1ab2695068/Documentation/Architecture/Release1.4/CLIReference.md), +[exact arithmetic contract](https://github.com/ThorFuchs/Swift-JSON/blob/15aa7e432cbb7173aa94b91e32badd1ab2695068/Documentation/Architecture/Release1.4/Arithmetic.md) +and [advanced filter contract](https://github.com/ThorFuchs/Swift-JSON/blob/15aa7e432cbb7173aa94b91e32badd1ab2695068/Documentation/Architecture/Release1.4/Advanced.md) +are pinned to the admitted consolidation source. This is not universal jq +compatibility. Unsupported syntax/functions produce typed compilation failures. +CLI options govern its host; they are not additional library parameters. In +particular, the public library has exact division and explicit caller-supplied +bindings/providers, with no ambient files or process input. ## Ownership and completion @@ -36,6 +48,18 @@ extracted from it, or a value handed off when the scope ends, is caller-owned. A callback may stop early. Transform completion does not drain or certify an external source: the CLI separately checks syntax, closing boundaries and EOF. +Accounting observations are snapshots, not ARC synchronization barriers. Output +leases enqueue refunds when their last handle is released; the invocation drains +that queue at its next checkpoint. `next()` performs that checkpoint even when it +must then throw the latched failure or `configuration/scopeClosed`. Reading +`statistics` or `used(_:)` alone does not drain pending refunds. + +A returned operation report is an immutable observation at scope completion. It +may include a source reservation still held by an output handle at that time; +releasing the handle later does not rewrite that report. An escaped execution can +observe the drained refund after a guarded checkpoint, while data access remains +invalid. These logical observations do not delay ARC reclamation or measure RSS. + ## Finite work and explicit providers `JSONTransformLimits` supplies finite native and transform ceilings. Compilation diff --git a/Tests/JSONCLITests/IntegrationTests.swift b/Tests/JSONCLITests/IntegrationTests.swift index 146931d..5157667 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.0-dev")) + #expect(try metadata.requiredMember("version") == .string("1.7.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)