Skip to content
Closed
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
49 changes: 30 additions & 19 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,35 @@
# Changelog

## Unreleased — next feature train
## 1.6.0 — 2026-10-16

- Add bounded synchronous JSON composition with one cumulative work/retention
ledger, borrowed scope lifetime, cross-scope rejection and a scope-bound admitted
root. Trusted and source-parsed roots are admitted once; each selected output
remains charged. Preserve exact values, source snapshots, cancellation and
terminal owned failures.
- Add structured JSONHTML layouts with finite string, color, declared raster, inline
and atomic MathML previews; preserve exact source, complete export/print and shared
CLI policy. Native, browser and WASI evidence is recorded with remaining assistive
and host qualification boundaries.
- Forward-port the following 1.5.1 maintenance repairs. Development CLI metadata
is `1.6.0-dev` with a deterministic source digest; this is not a released version.

### 1.5.1 maintenance repairs
CLI policy. Native, browser and WASI evidence retains its assistive and host
qualification boundaries.
- Ship the opt-in JSONNavigation library for exact many-node DFS over canonical
documents, with typed locations, physical and virtual scopes, finite metadata,
explicit coverage and the existing cumulative resource contract.
- Carry forward the 1.5.1 diagnostic, regression-suite, CLI-identity and Git-free
archive repairs. The CLI reports `1.6.0` and a deterministic source digest.
- Composition qualification covers 20 core functions in Debug/Release/ASan, two
concurrent-scope functions under TSan, 18 semantic ownership rejections, 14
call-site probes and 1,000 selections from 50,000-value trusted and parsed roots.
- **Known compiler limitation:** four inferred call-site forms still abort Swift
6.4. Explicit borrowing methods prevent two bound-method aborts, but the
nonescaping bound-method positive remains unsupported. Five new explicit
callback-parameter probes verify a source workaround. The original failures
remain blocked, never counted as successful rejections. The direct reference adapter still refuses the
`balanced-128-128` capacity target. The large-root consumer is synthetic and does
not qualify a complete Swift-OpenAPI importer, arbitrary callback instructions,
process RSS or broad application capacity. See the [composition qualification
record](Documentation/Qualification/Release1.6.0/README.md).

## 1.5.1 — 2026-10-15

- Restore best-effort schema diagnostic omission without latching terminal failure;
strict diagnostic, work, retention, annotation and cancellation errors still throw.
Expand All @@ -19,7 +39,7 @@
- Replace stale CLI development metadata with an explicit version and reproducible
source digest; preserve empty dependencies, all seven products and 49 core caps.
- Reconcile README, support/platform guidance, release history and DocC navigation.
Structured HTML previews remain outside the separate 1.5.1 patch candidate.
Structured HTML previews shipped in 1.6.0.

## 1.5.0 — 2026-10-15

Expand All @@ -30,7 +50,7 @@
- Qualify native and ARM64/x86_64 Linux behavior/safety, source reproduction,
public consumers and six DocC catalogues. Full CLI/WASI and Apple model helpers
remain unqualified/unavailable. Frozen CLI metadata reports 1.4.0-dev/unknown,
explicitly disclosed in the release notes and repaired in the next candidate.
explicitly disclosed in the release notes and repaired in 1.5.1.

## 1.4.0 tag — 2026-10-15

Expand Down Expand Up @@ -85,7 +105,7 @@ Published from the separate 1.2 maintenance branch. Add 126 behavior/conformance
functions, public integration and missing/corrupt-resource acceptance, complete
coverage export and explicit performance disposition. Repair best-effort schema
diagnostics and Git-free qualification identity. These two repairs and the added
suites were absent from 1.3.0 through 1.5.0; the 1.5.1 candidate restores them.
suites were absent from 1.3.0 through 1.5.0; the 1.5.1 release restores them.
Historical qualification and performance receipts retain their original scope.

## 1.2.0 — 2026-10-13
Expand Down Expand Up @@ -170,12 +190,3 @@ remain unselected; projection and RFC 7464 framing remain deferred.
timing sleeps; retain an invocation-local package-only checkpoint observer.
- Qualify twenty frozen explicitly rooted downstream schema vectors and public
cumulative budgets in a separate consumer; no protocol/runtime dependency added.

## Unreleased Navigation candidate

- Propose opt-in JSONNavigation as an eighth SwiftPM product, preserving its56
exact traversal declarations and cumulative resource semantics.
- Qualify a real external Debug/Release SwiftPM consumer and preserve source-first
error precedence with two explicit regressions.
- N2 inspection remains unimplemented: its separate borrowed-context compiler
proof is blocked. No version/tag/release or automatic merge is implied.
74 changes: 74 additions & 0 deletions Documentation/Architecture/CompositionCompiler.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Composition compiler diagnosis

Swift 6.4 aborts in `SILGenCleanup` when some implicitly named callback parameters
of noncopyable type are captured. The contextual function type says `borrowing`,
but the generated SIL attempts `copy_addr` on a value marked
`mark_unresolved_non_copyable_value [no_consume_or_assign]`. The ownership verifier
aborts before an ordinary ownership diagnostic can be emitted. JSON values,
resource accounting, Foundation and the private owner reference are not required
to reproduce this defect.

The [standalone reductions](../../Tools/CompositionQualification/CompilerReproductions)
use an empty noncopyable `Handle`, a borrowing callback and either an escaping
capture or a synchronous local function. The inferred parameter forms abort;
spelling `(handle: borrowing Handle)` makes the escape produce a normal diagnostic
and makes the synchronous local function compile. The original inferred public
API fixtures remain in the qualification gate.

## Library repair and supported spelling

Every composition instance method now explicitly declares `borrowing`. This
preserves the existing ownership convention and prevents the two bound-method
probes from aborting. `MethodEscape` receives the expected borrowed-self diagnostic.
`MethodBorrow` also receives a borrowed-self diagnostic even though its callee is
nonescaping. Its original positive expectation is retained as an unsupported
compiler call site; a diagnostic does not turn that requirement into a pass.
Use a closure literal instead of a bound method value.

Explicit callback parameter ownership avoids the other capture-lowering defect:

```swift
try JSON.withComposition { (scope: borrowing JSONCompositionScope) in
try scope.withAdmittedRoot(value) { (root: borrowing JSONCompositionRoot) in
let pointer = try scope.pointer(tokens: ["name"])
return try scope.resolve(pointer, in: root)
}
}
```

Five additional public probes exercise explicit ownership: three invalid escapes
must produce source-backed borrowed-parameter errors, while a local function and
a closure-literal method call must emit objects. They supplement the original
nine call sites and 18 semantic-negative programs.

Swift emits a bound method's primary borrowed-self error at `<unknown>:0`, with
the actual expression in a source note. Only the two bound-method fixtures opt
into that diagnostic shape. Classification requires the exact primary error and
the matching fixture's `closure capturing 'self' here` note. A setup error, a note
from another file, an object emitted for a negative program, or an abort cannot
satisfy the ownership rejection requirement.

## Ownership boundary

The public callback conventions remain borrowed. Scope and root types remain
noncopyable and non-Sendable; private owner identity, cumulative accounting,
selected-output reservations and terminal failures are unchanged. No compiler
feature flag or unsafe annotation is introduced.

Trials with owning callbacks or copyable facades are excluded from the repair.
Owning callbacks allowed a local scope to be moved, swapped with a nested
invocation and restored. That would reopen the accounting substitution boundary.
Adding nonescapability to borrowed noncopyable callbacks alone did not eliminate
the compiler abort. These alternatives cannot replace the current guarantees.

The remaining inferred captures still require an upstream compiler correction.
The gate stays blocked on those aborts and the unsupported bound-method positive;
the explicit spelling is a source workaround, not a claim that the compiler gate
has passed.

For toolchain comparisons, run `python3 Scripts/ci.py --lane composition-compiler`.
This builds the JSON module with the selected compiler, runs the classifier tests,
and checks all 18 semantic negatives and 14 call sites with their existing
expectations. It records runtime behavior as `not_run`; the full composition lane
remains the runtime, sanitizer, adapter and scale qualification gate. Compiler
aborts and rejected positive call sites keep either lane blocked with exit 2.
59 changes: 44 additions & 15 deletions Documentation/Architecture/CompositionQualification.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
The synchronous borrowed composition API is described in
[Compose native operations](../../Sources/JSON/Documentation.docc/Composition.md).
Its public surface and default profiles are unchanged by this qualification work.
The root dependency graph remains empty and the package retains the existing products and adds opt-in JSONNavigation after its
separate public-product gate.
The root dependency graph remains empty and JSONNavigation is available as an
opt-in product alongside the composition API.

The separate [qualification package](../../Tools/CompositionQualification) exercises
source-backed parsing, exact Pointer targets, URI identity and explicitly charged
Expand Down Expand Up @@ -50,6 +50,34 @@ characterization check verifies those outcomes; it does not turn the three
incomplete imports into successes or establish arbitrary production capacity.
The direct adapter's failed capacity target remains explicit.

## Admitted-root lookup path

`withAdmittedRoot` admits one trusted immutable graph and lends a private,
noncopyable, non-Sendable handle for the synchronous callback. `withParsedDocument`
parses and admits its root on the same ledger without traversing that parsed root
again. The handle retains the exact snapshot and a private reference to its owner;
only that composition can resolve through it. Cross-scope use fails before
navigation. Root admission and the logical handle slot remain charged through
composition completion.

Each Pointer and selected output still consumes work and retention. Selecting the
entire root with an empty Pointer therefore reserves the selected graph again.
The arbitrary-JSON overload retains conservative repeated admission. For a root
with N nodes and R small selections, the admitted-handle path changes root
admission from O(R × N) to O(N), plus Pointer navigation and each selected-output
graph. A 50,000-value trusted root and the same source-parsed root are each
resolved 1,000 times in the separate public consumer under balanced limits; its
work and retention receipts qualify that synthetic workload only.

The public compiler probes also record supported explicit-borrow call sites and
known Swift 6.4 compiler aborts. Those aborts remain compiler-robustness blockers;
they are not counted as successful ownership rejections. Explicit borrowing
methods and callback-parameter counterparts isolate the remaining capture-lowering
defect; see the [compiler diagnosis](CompositionCompiler.md). The synthetic scale
consumer does not qualify a full Swift-OpenAPI importer, broad application
capacity, process RSS or callback instruction limits. The original direct
adapter's 128/128 balanced quota refusal remains in the record.

The adapter declares 64 logical bytes for its frame, 16 per output slot and a
conservative 68 per descriptor (20 index-text bytes and three 16-byte input token
slots). Staging adds one admitted input token slot. Reservations and work charges
Expand All @@ -59,26 +87,27 @@ owned operation. Functional elapsed times do not establish throughput guarantees

## Execution and evidence

Run python3 Scripts/ci.py --lane composition on the supported native or Linux
runner. The lane requires 12 core functions in each build mode, separate public
consumers, five external Swift Testing functions in Debug/Release/ASan, all eight
scale cells and 11 compiler rejection cases. Exact module/cardinality checks
reject missing tests and misclassified resource failures. The reconciled 597 native / 581
Linux root functions, 325 parameter invocations, restored identities and 49 public
metric probes retain their existing contracts.
Run `python3 Scripts/ci.py --lane composition` on the supported native or Linux
runner. The lane requires 20 core functions in Debug/Release/ASan, two TSan
concurrency functions, a strict-memory-safety build, distinct public consumers,
both 50,000-value admitted-root scale cases, all eight reference-adapter scale
cells, 18 semantic compiler rejections and 14 actual call-site probes. Exact
module/cardinality checks reject missing tests and misclassified resource
failures. The current root function counts and 49 public metric probes are
recorded by `Documentation/Qualification/TestDiscovery.json`.

The tests replay exact and one-below work/retention thresholds, compare both
strategies on identical input, preserve exact values and scalar keys, and catch
late missing-target/cancellation failures before attempting normal completion.
Finalization must still throw the original native failure. Each report retains
its actual source, environment, command exits, counts and input hashes.

CI runs the focused lane alongside the existing Native / native and both Linux
architecture jobs. Their names and protection rules remain unchanged. Sanitizer
and full-root lanes continue independently. Linux uses the existing Swift
Testing-only runner policy; no baseline is suppressed.
The full Native / native and Linux architecture lanes discover and run the new
root functions. The standalone composition lane adds the separate compiler
harness and adapter/scale consumers. Sanitizer and full-root lanes continue
independently. Linux uses the existing Swift Testing-only runner policy; no
baseline is suppressed.

Controlled idle-host performance remains a separate gate using the unchanged
10% review trigger. Shared or busy-host timing cannot close it. Representative
application scale beyond these synthetic cells needs separate evaluation; no
downstream dependency adoption, merge or release follows automatically.
application scale beyond these synthetic cells needs separate evaluation.
8 changes: 8 additions & 0 deletions Documentation/Architecture/Concurrency.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,14 @@ unchecked box. Operation reports are Sendable only when their result qualifies.
Library work has no default MainActor isolation or CPU-offloading convenience.
Synchronous calls use the caller executor.

Experimental composition root handles are borrowed, noncopyable and non-Sendable.
Their immutable graph is admitted once by the owning invocation; a private owner
reference prevents another invocation from using that admission. Root callbacks
hold no inout meter borrow across caller code. Handle lifetime never refunds
logical ownership. Scope and handle captures remain subject to compiler ownership
checks; the composition qualification records known Swift 6.4 call-site compiler
aborts separately from expected semantic rejections.

Cancellation checks occur at operation entry, before growth/suspension, on await
return and at most 1024 owned charged units apart. Native tests must exercise
inner numeric, codec and regex loops, not only wrapper cancellation. A clock
Expand Down
6 changes: 6 additions & 0 deletions Documentation/Architecture/ExtractionManifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -274,6 +274,12 @@
"1.5.1 restores 126 original Apache-2.0 test functions and qualification tools from Swift-JSON 1.2.1 (e8b687f822c577311156b13bf1d15c2d5620b84e), with file hashes and stable function identities in Qualification/Release1.5.1/Restoration.json. The diagnostic omission and Git-free provenance repairs are restored original code; current seven-product harness reconciliation and deterministic CLI identity are original contributions. No new upstream adaptation or dependency.",
"Composition reference-load fixtures, serial descriptor staging, public-only adapter, capacity/terminal tests and strict CI receipt checks are original Apache-2.0 code. Generated JSON graphs introduce no upstream protocol fixtures, engine or dependency. Core public APIs, finite profiles and accounting weights are unchanged."
],
"composition_admitted_root_original_contributions": {
"license": "Apache-2.0",
"adapted_third_party_code": false,
"basis": "Independent ownership and repeated-admission review of 720da596; private review evidence excluded from source distribution.",
"scope": "Borrowed immutable admitted-root handles, private invocation identity, conservative selected-output reservations, boundary and scale consumers, compiler-callsite regressions, explicit borrowing method declarations, standalone compiler reductions and source-anchored compiler-abort/unsupported-callsite classification. No root dependency or unsafe annotation added."
},
"jsonhtml_export_original_contributions": {
"license": "Apache-2.0",
"adapted_third_party_code": false,
Expand Down
13 changes: 3 additions & 10 deletions Documentation/Architecture/Linux.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,14 @@
# N1 candidate platform scope

This additive candidate proposes JSONNavigation as an eighth product (seven
libraries plus CLI), with no external dependencies. Its public SwiftPM consumer
and39 Navigation functions join the unchanged Linux lanes. Both actual ARM64 and
x86_64 full/safety receipts are required for final qualification. The historical
platform text below describes the original seven-product implementation.

# Linux platform contract

The six libraries and swift-json executable are qualified for 64-bit
Release 1.6.0 includes opt-in JSONNavigation alongside the six established
libraries. The seven libraries and swift-json executable are qualified for 64-bit
Linux with Swift tools/compiler 6.4+ and Swift language mode 6. Initial execution
qualification targets Ubuntu 24.04 with glibc on ARM64 and x86_64. A platform
preflight identifies the actual runtime; cross-compilation alone cannot qualify
behavior or safety. Architecture-specific receipts must pass before claiming
that architecture qualified. Apple minimums remain macOS/SDK 27 and iOS/SDK 27.

The root manifest keeps an empty dependency graph and seven products.
The root manifest keeps an empty dependency graph and eight products.
Apple PDF and native transfer APIs retain their platform availability; portable
HTML has no WebKit requirement.
Linux does not need a SwiftPM deployment-platform entry. Foundation file/resource
Expand Down
Loading