Complete JSON Schema parity and safe reconstruction

docs/plans/2026-07-12-0900-framework-coroutine-state-lifecycle-audit.md

@@ -990,9 +990,9 @@ An exceptionally large shared work unit may receive its own linked detail plan w
 
 This compact index routes the completed-work history that must be consulted with the full plan after compaction. Detailed history remains in the [companion ledger](2026-07-12-0915-framework-coroutine-state-lifecycle-audit-ledger.md).
 
-- **Active package or work unit:** `inertia`; correctness and SSR lifecycle maintenance is recorded under `Complete Inertia correctness and SSR lifecycle maintenance`; detail plan `2026-08-07-2018-inertia-correctness-ssr-lifecycle-and-current-parity.md`. Current upstream DevTools is the next Inertia work unit.
-- **Ledger entries required for the active work:** `Complete Inertia correctness and SSR lifecycle maintenance`.
-- **Pending revalidation carried into the active work:** None. Inertia revalidated `support-02`; current upstream DevTools remains separately scoped before the package checklist can be completed.
+- **Active package or work unit:** None. `json-schema` is complete; detail plan `2026-08-07-2015-json-schema-correctness-current-parity-and-bounded-reconstruction.md`.
+- **Ledger entries required for the active work:** None. The completed JSON Schema work is recorded under `Complete JSON Schema correctness, current parity, and bounded reconstruction`.
+- **Pending revalidation carried into the active work:** None. JSON Schema changed no lower-level assumption and has no repository runtime consumer requiring revalidation.
 
 Update these three lines when a package starts, completes, or gains a cross-package dependency. Name exact work-unit headings or shared finding IDs from the companion ledger; never use “see recent entries” or require a full-ledger reread.
 
@@ -1320,7 +1320,7 @@ The order is lower-level first where practical. Hypervel has cross-cutting depen
 - [ ] `sentry`
 - [ ] `inertia`
 - [x] `nested-set`
-- [ ] `json-schema`
+- [x] `json-schema`
 
 ### Tooling and developer surfaces
 

docs/plans/2026-07-12-0915-framework-coroutine-state-lifecycle-audit-ledger.md

@@ -2016,6 +2016,33 @@ Append package entries in checklist order. Keep each entry compact but complete
 - **Validation and review:** Focused API, route, installer, and complete Fortify coverage is green. The authoritative `composer fix` gate, final stale-state and caller/callee review, and independent code review passed with no remaining finding.
 - **Assessment:** The implementation restores current parity and one-source configuration ownership without a compatibility shim, speculative abstraction, hot-path synchronization, or meaningful performance regression.
 
+### Complete JSON Schema correctness, current parity, and bounded reconstruction
+
+- **Status and inspected surface:** Complete; implementation, the authoritative gate, fresh source/test/documentation review, and independent code review are signed off. The audit covered every JSON Schema source and test file, the contract, package metadata, repository consumers, current Laravel 13.x source/tests and originating changes, JSON Schema 2020-12 representation rules, Opis validation behavior, reference expansion, serializer wire shapes, and worker-failure boundaries. The detailed design is recorded in [`2026-08-07-2015-json-schema-correctness-current-parity-and-bounded-reconstruction.md`](2026-08-07-2015-json-schema-correctness-current-parity-and-bounded-reconstruction.md).
+
+| Findings | Final decision |
+|---|---|
+| `json-schema-01` | Port current Laravel `unique`, reversible flags, `fromArray`, union, and any-of APIs with truthful Hypervel typing. |
+| `json-schema-02` | Replace recursive reference following with a local loop, cap one active path at 256 distinct references, and bound aggregate expansion without shared state. |
+| `json-schema-03`, `json-schema-11`, `json-schema-12` | Reject malformed, unsupported, coerced, dropped, deferred, or structurally lossy reconstruction; preserve representable permissive forms and empty enums; reconstruct bare null schemas while collapsing only bare null branches and preserving `oneOf` exact-match cardinality. |
+| `json-schema-04` | Emit numeric/list-shaped property maps and top-level object defaults as JSON objects and normalize those exact boundaries during reconstruction. |
+| `json-schema-05` | Preserve JSON encoding failures with `JSON_THROW_ON_ERROR` instead of returning a blank schema. |
+| `json-schema-06` | Validate union and any-of only after nullability is applied, reject finally-empty output and empty input type arrays, and reconstruct null-only schemas truthfully. |
+| `json-schema-07`, `json-schema-08` | Add canonical package guidance and provenance, and distinguish required properties from nullable values. |
+| `json-schema-09`, `json-schema-10` | Preserve explicit null concrete defaults and add owner-approved fluent mixed defaults to union and any-of schemas. |
+| `json-schema-13` | Reject non-string direct union members without coercion, warnings, or undocumented PHP errors. |
+| `json-schema-14` | Preserve branch-local enum ownership in nullable `anyOf` and reject the equivalent unrepresentable `oneOf` form. |
+
+- **Architecture and lifecycle:** Factories, builders, serialization, and deserialization remain allocation-only and operation-local. Serializer retains one protected static list of ignored internal fields, inherited from Laravel and never mutated by package code; no other static or worker-lifetime state exists. No provider, binding, callback, external service, coroutine context, or worker cleanup is involved. Reference caches and counters exist only for one `fromArray()` call.
+- **Reference-risk evidence:** The recursive implementation expanded about 130 KiB of 4,000-link input to 192 MiB and died near 200 KiB / 6,000 links at a 256 MiB limit. The iterative implementation handled 6,000 links in about 8 MiB and 79 ms. The original memory fatal is uncatchable and would terminate a Swoole worker and every concurrent coroutine it serves.
+- **Implementation:** The current builder surface, sum types, explicit-default state, reversible flags, unique arrays, and strict direct-union boundary are complete. Serialization preserves object shapes, numeric required names, final composition validity, and encoding exceptions. Reconstruction uses bounded iterative local references, strict recognized-keyword ownership, exact null/composition handling, exact nullable-`oneOf` cardinality, branch-local enum ownership, and fail-closed unsupported assertions while continuing to ignore harmless annotations and extensions. Superseded coercion, recursive reference frames, false nullable prose, and blank-output fallback are removed.
+- **Important rejected concerns:** No container/scoped binding, static factory, worker cache, registry, lock, `CoroutineContext`, configurable limits, graph engine, validator, keyword table, raw assertion bag, `NullType`, serializer cycle tracker, schema-valued additional-properties bridge, recursive object-default reinterpretation, or default-versus-branch validation was added. These mechanisms had no supported consumer or would duplicate a JSON Schema validator.
+- **Regression coverage:** Tests cover the current factory and contract surface; reversible flags; sum types and defaults; primitive, object, array, nullable, composition, and reference reconstruction; exact nullable-`oneOf` matching; branch-local enum ownership; active-path and aggregate expansion limits; exact property/default JSON shapes; malformed recognized keywords; unsupported assertions; integer range boundaries; falsey and permissive forms; explicit null defaults; direct union-member failures; and JSON encoding exceptions. Counterfactual rows pin every corrected silent-loss and warning/error path.
+- **Performance and compatibility:** Ordinary builder use adds only bounded local checks and object-shape classification. `fromArray()` is explicit cold work; its fixed keyword checks and counters replace recursive reference copying with a lower-memory loop and hard bounds. No request path gains I/O, synchronization, yielding, retries, container resolution, or retained worker state. Current Laravel-facing APIs and named arguments are preserved; concrete null defaults and sum-type defaults are additive approved widenings, and invalid inputs now fail instead of producing a weaker or unusable schema.
+- **Upstream handoff:** Current Laravel 13.x retains direct union-member coercion, unbounded recursive reference following, lossy reconstruction of scalar/constrained null and unsupported or malformed assertions, nullable-`oneOf` overlap, branch-local enum hoisting, nested-composition loss, boolean `oneOf` loss, over-rejection of representable `items: true`, numeric object-map encoding, blank-string JSON failures, and invalid finally-empty compositions. Each can be upstreamed independently without Hypervel lifecycle machinery.
+- **Validation and review:** Changed tests passed throughout implementation; the complete JSON Schema suite, formatting, both PHPStan configurations, the full parallel components suite, Testbench package mode, dogfood, stale-marker scans, and `git diff --check` are green. Post-review corrections passed the complete package tests and both normal PHPStan configurations. Independent review reproduced the defect paths, rechecked neighboring behavior and performance, and signed off after every correction.
+- **Assessment:** JSON Schema is current at the audited Laravel surface, coroutine-safe by operation-local construction, bounded against worker-fatal reference expansion, and truthful at every supported reconstruction and serialization boundary. Every accepted finding is resolved without a workaround, speculative mechanism, useful Laravel API removal, meaningful hot-path regression, stale code, unresolved defect, or deferred TODO.
+
 ### Complete Prompts correctness, current parity, and terminal lifecycles
 
 - **Status and inspected surface:** Complete; implementation, focused validation, the authoritative gate, fresh caller/callee and performance self-review, and independent code review are signed off, including the interval-scaled renderer settlement correction found during pull-request review. The work corrected every verified prior-audit finding and the same-family defects found while tracing Prompts rendering, terminal ownership, process transport, signal restoration, retained instances, package metadata, Testbench shutdown cleanup, tests, and documentation. The detailed design is recorded in [`2026-08-07-1654-prompts-correctness-current-parity-and-terminal-lifecycles.md`](2026-08-07-1654-prompts-correctness-current-parity-and-terminal-lifecycles.md).