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
6 changes: 6 additions & 0 deletions .github/workflows/linux.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,12 @@ jobs:
with:
persist-credentials: false
fetch-depth: 0
- name: Verify the checked-out container workspace
run: |
# The image user differs from the checkout owner. Trust this exact
# ephemeral workspace so Git identity and full-history checks run.
git config --global --add safe.directory "$GITHUB_WORKSPACE"
test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
- run: python3 -B Scripts/ci.py --lane '${{ matrix.lane }}'
- name: Preserve Linux receipts
if: always()
Expand Down
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,11 @@ 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
Documentation/Architecture before changing behavior.

- Keep six public products: JSON, JSONSchema, JSONStreaming, JSONPatch, JSONHTML and JSONBridges.
- Keep eight public products: JSON, JSONSchema, JSONStreaming, JSONPatch, JSONHTML, JSONBridges, JSONValueDSL and JSONSchemaDSL.
JSONHTML depends on JSON only; the maintainer-approved 1.3 addition preserves historical four-product releases.
The E2-approved opt-in JSONBridges depends on JSON only and is never re-exported by core.
The P1.2-approved optional DSL products use JSONDSLCore without a standalone core product.
Trusted authored DSL staging is outside finalization quotas; never imply a staging/RSS bound.
JSONRegexRuntime is package-private. Root package dependencies remain empty.
- Preserve exact bounded decimals, decoded Unicode scalar identity, ordered
objects with order-independent equality, one strict UTF-8 grammar, native
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

## Unreleased

- 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.
Expand Down
28 changes: 26 additions & 2 deletions Documentation/Architecture/API.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,24 @@
# Public API contract

This document describes the implemented public interface. Native compiler symbol
graphs supply the complete declarations in the six DocC catalogs. Examples
graphs supply the complete declarations in the eight product DocC catalogs and the shared DSL structure reference. Examples
in the [README](../../README.md) are compiled and executed by the public consumer.

## Products and ownership

| Product | Main entry points | Owned implementation boundary |
| --- | --- | --- |
| JSON | JSON, JSONNumber, JSONObject, JSONParser, JSONWriter, JSONValueEncoder, JSONValueDecoder, JSONPointer, JSONDocument | Shared strict codec, exact decimal model, bounded traversal and native coding |
| JSONValueDSL | JSONValueDSL.object/array, Field, Element, Elements | Trusted authored staging; finite iterative exact finalization |
| JSONSchemaDSL | JSONSchemaDSL.document/boolean, Schema, Property, Definition, PatternProperty, DependentSchema, RequiredDependency, Rule | Trusted authored schema declarations; existing document/compiler/validator authority |
| JSONBridges | BinaryInteger.jsonNumber, FixedWidthInteger/Double/Decimal.init(jsonNumber:), Double.jsonNumberFromRoundTripText | Optional one-delegate numeric conversions; explicit fidelity, no new authority |
| JSONSchema | JSONSchemaDocument, JSONSchemaRegistry, JSONSchemaCompiler, CompiledJSONSchema, JSONSchemaValidator | Offline immutable plan, invocation-owned evaluation and private native regex |
| JSONStreaming | JSONEventSequence, JSONValueSequence, NDJSONValueSequence, JSONTopLevelArraySequence, JSONAsyncWriter | Exclusive pull state, shared codec, strict framing and awaited handoffs |
| JSONPatch | JSONPatch, JSONPatchOperation, JSONPatchResult, JSONMergePatch | Transaction staging, exact comparison and iterative editing |
| JSONHTML | JSONHTMLRenderer, JSONHTMLRenderingOptions, JSONHTMLLimits, JSONHTMLRenderReport, JSONHTMLAnnotation, JSONExportDocument, JSONExportOptions, JSONExportReport | Exact HTML, native Apple transfer, immutable prepared JSON/text/Markdown/static HTML/opt-in styled RTF and cumulative budgets |

JSON imports no siblings. JSONSchema depends on JSON and package-private
JSONRegexRuntime. Streaming, Patch, HTML and Bridges depend on JSON. There are six public
JSONRegexRuntime. Streaming, Patch, HTML and Bridges depend on JSON. There are eight public
products and no external root-package dependencies. Runtime code uses no HTTP,
UI, MCP or documentation-tool dependencies.

Expand Down Expand Up @@ -211,3 +213,25 @@ JSONHTMLRenderer also accepts JSONDocument in its four rendering/report methods.
Caller annotations use exact typed paths, explicit missing-parent attachment and
coherent value byte spans without schema execution or source-byte archival.
See [diagnostic rendering](Release1.3/DiagnosticAnnotations.md).

## Optional Dual DSL P1.2

The two DSL products do not change or re-export the existing core entry points.
JSONDSLCore has no standalone product; its public structural builder types occur
in the optional generic signatures. See the [decisions](DualDSL/Decisions.md).
Callbacks, content emission and staging are trusted and unmetered. Finalization
uses one finite invocation ledger through iterative construction and, for schemas,
document admission. This does not imply whole-pipeline cumulative billing, staging
retention, caller instruction or RSS bounds. No whole-DSL report is supplied.

Exact duplicate names throw JSONFailure/duplicateKey. Decoded scalar identity and
order are preserved. Missing declarations emit nothing; null, empty containers and
Boolean schemas differ. Array flattening requires Elements(contentsOf:). Implicit
numbers accept BinaryInteger only, with explicit JSONNumber for decimals. E2 and
JSONBridges remain unchanged; DSL targets import neither bridge nor framework DSL.

Schema rawKeyword preserves declarations for existing compiler classification.
No requiredness/default/format/reference/annotation policy is inferred. Invalid
instances return false; malformed schemas, offline missing resources, nonproductive
cycles, resource failures and cancellation remain operational errors. Factories
never validate or publish a candidate schema as already compiled.
98 changes: 98 additions & 0 deletions Documentation/Architecture/DualDSL/Decisions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Dual DSL decisions

## D1 — Trusted authored staging, finite finalization

P1.2 adopts the explicitly permitted authored-configuration boundary. Result-builder
callbacks, wrappers, collection emission, IR assembly and integer literal construction
are trusted, unmetered staging. They can allocate or run caller computation before
finalization. This API is not an untrusted-input entry point, an instruction quota,
a staging-retention guarantee, an RSS bound or a whole-pipeline cumulative report.
Use existing bounded parsers/accumulators for dynamic untrusted input.

Finalization is a separate checked phase. One invocation-owned JSONWorkMeter covers
iterative lowering, exact key/index admission, output slots, literal payload traversal,
work/cancellation and, for schemas, JSONSchemaDocument admission. Existing package
hooks are reused; JSON, JSONSchema and JSONBridges source need no changes. No helper
restarts this finalization ledger. A caught owned failure remains terminal, including
at the package continuation boundary. No partially finalized value is returned.
There is deliberately no public whole-DSL `WithReport` API. Tests distinguish the
finalization counters from unaccounted staging; existing 49 baseline probes remain.

## D2 — Flat staging lifetime and iterative lowering

The prototype's recursive indirect enum and per-container checked materialization
are replaced with a flat private token sequence. The public node's object/array/literal
factory spellings remain, but it is a struct rather than a pattern-matchable enum.
Nested typed declarations assemble these tokens without flattening JSON array values.
Finalization uses explicit frames and the engine's exact-key index and admission helpers.
IR teardown does not recursively own child IR nodes. Literal JSON retains its existing
engine lifetime semantics. Depth failures use JSONFailure/resource/maxDepth, replacing
the prototype-only JSONDSLBuildFailure; no second resource-error model is added.

Qualification must cover default-cap rejection of deeply staged inputs, accepted depth
boundaries, cancellation in owned finalization and terminal errors. Arbitrary caller-
configured depths and callback recursion are not implied by a finite tested depth.

## D3 — Separate products and semantic authorities

JSONValueDSL and JSONSchemaDSL add no dependency to core or each other. Shared typed
builder protocols are public declarations in JSONDSLCore because optional public generic
signatures reference them; the helper module has no independently selectable product.
Objects use ordered exact-key semantics, arrays preserve nesting, omission emits nothing,
and duplicate keywords/properties/definitions fail. There is no String dictionary merge.

The schema DSL emits ordinary JSONSchemaDocument. The existing compiler and validator
alone govern dialect, vocabularies, regex, references, annotations, requiredness and
invalidity versus operational errors. Explicit offline registry resources use existing
JSONSchemaDocument/JSONSchemaRegistry APIs; no ID-to-retrieval inference or network resolver.

## D4 — E2 reconciliation and minimal naming

Merged E2/JSONBridges remains unchanged and opt-in. DSL implicit numeric inputs remain
BinaryInteger only; exact decimals require explicit JSONNumber. No Float/Double overload,
Optional bridge, floating literal, coercion or automatic requiredness is added.
JSONValueDSL and JSONSchemaDSL remain distinct discovery namespaces. An umbrella product,
typed ObjectSchema/StringSchema/ArraySchema synonyms, automatic references/derivation and
new Boolean-schema overload aliases are deferred: existing Rule(Boolean), table Boolean
initializers and rawKeyword preserve the complete declaration without another surface.
The identical prototype rawSchemaKeyword synonym is removed in favor of rawKeyword.

## D5 — Retain measured variadic composition

Native Swift 6.4 compiled both strategies against the real engine. The final
comparison passed 41 commands, including 22 scaling probes: value/schema blocks
of 16/64/128/256 declarations, nested depth 24, choices/loops and mixed inference.
All six domain-negative fixtures rejected in both configurations, and ordinary
and module-qualified consumers compiled with complete strict concurrency.

The final 256-property schema typecheck took 3.765 s with variadic composition
versus 5.304 s with pairwise partial blocks; compiler maximum resident sizes were
122,929,152 and 137,789,440 bytes respectively. An earlier integration run measured
1.097 s versus 5.513 s. All raw fixture hashes and measurements are retained; neither
run was quiet (final load averages approximately 600/587/533). Some small branching
fixtures favored partial composition. These observations justify retaining the
working variadic strategy through the tested scale, not a general speed guarantee.
Compiler RSS does not bound DSL staging, finalization retention or process RSS.
The alternative modules remain experiment outputs and are not shipped code.

## D6 — Empty enum is distinct from malformed schema

The initial integration test incorrectly grouped an empty enum with malformed
length/count declarations. Actual compiler behavior and the pinned validation
meta-schema accept an enum array with no entries. Draft 2020-12 validation
[section 6.1.2](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-01#name-enum)
requires an array and recommends a nonempty one. The corrected case compiles
both DSL and handwritten declarations and proves ordinary invalidity for all
six JSON kinds. Negative bounds, zero multipleOf, empty oneOf and duplicate
required names remain explicit compilation failures. No engine behavior changed.

## D7 — Real module qualification instead of facade shadowing

A native Swift 6.4 consumer with its own Field, Element, Schema and Property
declarations cannot spell JSONValueDSL.Field or JSONSchemaDSL.Schema when the
prototype facade enums shadow their modules. P1.2 therefore uses module-level
object/array/document/boolean factories. Existing authored calls retain the same
JSONValueDSL.object and JSONSchemaDSL.document spelling, while declaration types
can be qualified with their actual module. No umbrella, alias or synonym is added.
This is an unreleased prototype declaration-shape change, not an engine API change.
The compiler harness retains explicit collision cases in both configurations.
39 changes: 39 additions & 0 deletions Documentation/Architecture/DualDSL/Plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Dual DSL P1.2 integration

This is an unreleased integration on `codex/dual-dsl-p1.2`, based on current main
`e8c3e4bd9ae40d797f07a527ea98879acee3c057`. The supplied packet inspected
`9517233ef0a3c1b961b738df58fe3ee4081d780c`; the intervening E2 merge adds entry points
and JSONBridges. Existing six products and core implementation remain authoritative.
The requested JSONValueDSL and JSONSchemaDSL are additive opt-in products. JSONDSLCore
has no standalone product. Root dependencies, platforms and all 49 profiles remain unchanged.

The maintainer-supplied packet SHA-256 is
`a69432b69f59d3d587502c2453fed3d00259845b9335a551b962965be10f9588`.
Its 32-file manifest verified. Its three DSL source roots and six negative fixtures are adapted. Neither
signature shim is an engine input. Its sixteen positive cases are ported from XCTest to Swift Testing and real JSONLimits.
Original and adaptation contributions retain Apache-2.0.

## Gates and reviewable increments

1. **G0 baseline:** pin source/SDK/compiler; record manifest and file collisions;
run production native baseline in an untouched detached worktree.
2. **G1/G3 integration:** add opt-in targets, iterative flat staging/lowering,
exact admission and shared finalization/document ledger. Compile the real consumer.
3. **G2 semantics:** port all sixteen cases, implement V-01–V-20 parity against
exact manual JSON and hand-written schemas; retain unchanged official suite policies.
4. **G4 compiler qualification:** exact-domain negative fixtures and measured
16/64/128/256 blocks, nesting, choices, loops and mixed schema contexts; compare
pairwise composition when the observed scaling warrants it.
5. **G5 API/docs:** public comments and DocC, compiled README and guides; record
accepted/rejected namespace and sugar decisions against merged E2.
6. **G6 final qualification:** exact-count native/safety/docs and real Linux lanes;
public consumer, strict concurrency, source/diff/receipts and remaining limitations.

Each coherent increment is committed on the isolated feature branch. The maintainer
authorized a branch push and existing ARM64/x86_64 Linux CI after native checks.
PR creation, merging, tagging and release publication remain separate. Existing release and sibling worktrees
are preserved. A passing shim or typecheck is never a semantic qualification claim.

Private input and raw receipts live in ignored `Artifacts/DualDSLP1.2`; source identity,
commands, exits, toolchains, suite counts and source hashes accompany actual outcomes.
[Progress](Progress.json) records incomplete gates without rewriting older release history.
44 changes: 44 additions & 0 deletions Documentation/Architecture/DualDSL/Progress.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
{
"wave": "P1.2",
"base_commit": "e8c3e4bd9ae40d797f07a527ea98879acee3c057",
"packet_baseline": "9517233ef0a3c1b961b738df58fe3ee4081d780c",
"packet_sha256": "a69432b69f59d3d587502c2453fed3d00259845b9335a551b962965be10f9588",
"branch": "codex/dual-dsl-p1.2",
"release_ready": false,
"gates": {
"P1.2-G0": "passed",
"P1.2-G1": "passed",
"P1.2-G2": "passed",
"P1.2-G3": "passed",
"P1.2-G4": "passed",
"P1.2-G5": "passed",
"P1.2-G6": "passed"
},
"scope": "Trusted authored staging; finite iterative shared-ledger finalization; no staging/RSS/caller-work claim",
"observed": {
"baseline_native_commands": 17,
"dsl_tests_per_configuration": 47,
"native_root_functions": 343,
"baseline_parameter_invocations": 173,
"compiler_commands": 41,
"negative_rejections": 12,
"native_safety": "passed after retained transient PDF failure and unchanged full rerun",
"native_lane": "All19 production commands passed across retained13-command run plus6-command source-equivalent continuation after ENOSPC; no uninterrupted full-lane exit0 claimed",
"docs": "passed:1005/1005 comments,9 catalogs,1530 routes,7636 links",
"wasi": "passed:47 new DSL tests Debug/Release in Node; portable root bundles compiled; public release consumer Node/WasmKit. No new execution of other root corpora or host sanitizers claimed",
"linux": "passed:run38680343090 at6f6bd90467aae0354dc5dcfdc7e125a5f6e8d2de; ARM64/x86_64 full16 and safety4 commands each;329 root functions/173 parameters,12 portable TSan; actual receipts and identical archive bytes verified",
"completion": "passed:3 actual SourceKit-LSP contexts; interactive Xcode UI not claimed",
"apple_sdk": "passed:iPhoneOS/iPhoneSimulator27.2 public DSL consumer builds at existing minimum27; SDK-only scope"
},
"native_results": "Documentation/Qualification/DualDSL/NativeResults.md",
"qualification_status": "passed",
"release_readiness_reason": "Qualified feature candidate; maintainer API/merge and release authorization remain separate, not a failed technical gate",
"qualified_ci_source": "6f6bd90467aae0354dc5dcfdc7e125a5f6e8d2de",
"linux_results": "Documentation/Qualification/DualDSL/LinuxResults.md",
"remaining_limitations": [
"Trusted authored staging/callbacks excluded from finalization work and retention accounting",
"No whole-DSL report, caller instruction quota or hard process RSS/throughput guarantee",
"Interactive Xcode UI and new physical-device execution not claimed",
"All other WASI corpus/sanitizer execution remains its separately qualified existing scope"
]
}
Loading