Complete Nested Set invariants, performance, and modern APIs

composer.json

@@ -336,6 +336,7 @@
                 "Hypervel\\Log\\Context\\ContextServiceProvider",
                 "Hypervel\\Log\\LogServiceProvider",
                 "Hypervel\\Mail\\MailServiceProvider",
+                "Hypervel\\NestedSet\\NestedSetServiceProvider",
                 "Hypervel\\Notifications\\NotificationServiceProvider",
                 "Hypervel\\ObjectPool\\ObjectPoolServiceProvider",
                 "Hypervel\\Passkeys\\PasskeysServiceProvider",

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:** `reverb`
-- **Ledger entries required for the active work:** `Preserve configuration identity across worker reloads`; `Normalize framework enum identifiers at string boundaries`; `Complete Console command, scheduling, and generator lifecycles`; `Unify HTTP response emission and harden native server boundaries`; `Complete Redis pooling, subscriber transport, topology, parity, and lifecycle safety`; `Complete Horizon cluster, process, publication, and current Laravel parity`.
-- **Pending revalidation carried into the active work:** `config-02`, `support-02`, `reverb-03`, `reverb-04`, `redis-10`, `redis-11`, `reverb-05`, `http-server-06`, and `reverb-06`.
+- **Active package or work unit:** `reverb`; completed parallel work unit: `nested-set`
+- **Ledger entries required for the active or completed parallel work:** `Preserve configuration identity across worker reloads`; `Normalize framework enum identifiers at string boundaries`; `Complete Console command, scheduling, and generator lifecycles`; `Unify HTTP response emission and harden native server boundaries`; `Complete Redis pooling, subscriber transport, topology, parity, and lifecycle safety`; `Complete Horizon cluster, process, publication, and current Laravel parity`; `Complete Nested Set invariants, performance, and modern APIs`.
+- **Pending revalidation carried into the active work:** `config-02`, `support-02`, `reverb-03`, `reverb-04`, `redis-10`, `redis-11`, `reverb-05`, `http-server-06`, and `reverb-06`. `nested-set-13` revalidation is complete for Testing and remains indexed for its later full audit.
 
 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.
 
@@ -1117,6 +1117,7 @@ Add one row only for a shared finding or changed lower-level assumption that ano
 | `telescope-03` | `telescope` | `telescope` (targeted correction complete); later full `telescope` audit | `Complete Horizon cluster, process, publication, and current Laravel parity`; finding `telescope-03` |
 | `fortify-01` | `fortify` | `fortify` (targeted correction complete); later full `fortify` audit | `Complete Horizon cluster, process, publication, and current Laravel parity`; finding `fortify-01` |
 | `reverb-06` | `reverb` | `reverb` (targeted correction complete); later full `reverb` audit | `Complete Horizon cluster, process, publication, and current Laravel parity`; finding `reverb-06` |
+| `nested-set-13` | `nested-set` | `testing` (revalidation complete); later full `testing` audit | `Complete Nested Set invariants, performance, and modern APIs`; finding `nested-set-13` |
 
 ## Package checklist
 

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

@@ -1367,3 +1367,35 @@ Append package entries in checklist order. Keep each entry compact but complete
 - **Laravel-facing result:** Current supported Horizon commands, options, CSP/dev APIs, configuration, controllers, metrics, process behavior, locks, docs, and Boost resources are restored or preserved. Hypervel's public Queue and Horizon APIs remain Laravel-shaped; differences are limited to approved Swoole/pool/coroutine adaptations and verified upstream fixes. No useful Hypervel-specific capability was removed.
 - **Validation and review:** Every changed/new focused package test and live Horizon/Redis/MySQL path passed during implementation. The authoritative `composer fix` gate passed both PHPStan configurations and the complete parallel components, Testbench package, and dogfood suites. Split metadata and npm locks validate; `git diff --check`, stale-reference, direct-pipeline, installer-write, test-type, dependency, and documentation/resource scans are clean. Fresh caller/callee, signal/process, Redis ownership, publication, API, hot-path, retained-state, and overengineering review is complete. Independent review corrected final typing, confirmed the Reverb post-reap race empirically and rejected its accompanying timeout increase, and found the Horizon command readiness race. Later pull-request review surfaced the CSP defect, CI investigation surfaced the permission-test defects, and follow-up review verified the capability probes, finding allocation, and native niceness boundary.
 - **Assessment:** Every accepted Horizon and cross-package finding is fixed at its lowest owner. The result removes fatal Cluster paths, stale process work, non-atomic locks/publication, leaked transient state, false cleanup ownership, metadata drift, and timing-dependent test harnesses while preserving all useful Laravel and Hypervel behavior. It contains no workaround, speculative mechanism, meaningful hot-path regression, or unresolved accepted defect.
+
+### Complete Nested Set invariants, performance, and modern APIs
+
+- **Architecture and inspected risk surfaces:** Nested Set is an Eloquent tree package whose model actions stage intent, database rows own bounds/parent/depth within an optional concrete scope, structural freshness is coroutine-local per logical connection/table, and relations own operation-local matching indexes. The work covered every package source and test file; schema types and indexes; integer, UUID, ULID, and scoped trees; model/builder metadata; structural writes, deletion, repair, rebuild, and diagnostics; relations and collections; testing cleanup; all supported database drivers; and the maintained Aimeos fork as a behavior and performance reference rather than a parity contract. The detailed design and benchmark evidence are recorded in [`2026-07-29-1711-nested-set-invariants-performance-and-modern-api.md`](2026-07-29-1711-nested-set-invariants-performance-and-modern-api.md).
+
+| ID | Category | Severity | Confidence | Failure and owning boundary | Final decision |
+|---|---|---|---|---|---|
+| `nested-set-01` | Schema and API improvement | Major | High | The package exposes only one integer schema shape, omits depth, and lacks scope-prefixed indexes | Add discovered Blueprint helpers for bigint, integer, UUID, and ULID parents, mandatory stored depth, symmetric drops, and scoped structural indexes |
+| `nested-set-02` | Type and key defect | Major | High | Integer-only parent/root/model boundaries truncate or reject valid UUID, ULID, zero, empty-string, and numeric-string keys | Use truthful `int\|string\|null` model-key contracts and preserve explicit root values |
+| `nested-set-03` | Coroutine lifecycle defect | Major | High | Model-class freshness and mutable restore state can miss shared-table writes or leak across nested operations | Key freshness by logical connection/table and derive exact restore state from Eloquent's previous attributes |
+| `nested-set-04` | Structural query defect | Major | High | Global visibility scopes, blank scope values, stale builder construction, and unqualified columns can hide or corrupt structural work | Separate structural from user queries, preserve Eloquent builder extensions/metadata, require concrete scopes, qualify ordinary composable reads, and order compound results by their projected column |
+| `nested-set-05` | Scope identity defect | Major | High | Ad hoc scope values and ambiguous bucket keys can cross scoped trees or collide under eager matching, while hardcoded date normalization misses custom-format scope rows | Normalize supported scalar/enum/date/stringable values once, honor model date formats without connection resolution, and length-prefix ordered scope tuples |
+| `nested-set-06` | Relation defect | Major | High | Sibling access is not a real relation; ancestor/descendant existence queries duplicate scope or correlate bounds to the wrong outer table; and existence aliases copy model state and fire replication events on reads | Add a scope-aware `SiblingsRelation`, correct foreign keys/aliases and immediate-outer scope correlation, and build aliases from event-free class-default models on the parent's connection |
+| `nested-set-07` | Performance defect | Major | High | Existing eager matching becomes quadratic across large parent/result sets, while Aimeos's global index retains excessive memory and is slower for scoped workloads | Use four bounded operation-local paths with scope buckets and descendant binary search, preserving query order and releasing all indexes after matching |
+| `nested-set-08` | Collection and serialization defect | Major | High | Truthy root inference, recursive linking, and parent objects carrying child relations lose valid keys or create stale/cyclic graphs | Distinguish inferred from explicit roots, use iterative flat linking, clear stale relations, and share relation-free parent clones |
+| `nested-set-09` | Structural mutation defect | Major | High | Moves, inserts, gap changes, and partial selects can persist wrong depth or intervals, stale bounds, stale relations, or invalid zero-height SQL | Maintain depth in the structural statement, derive omitted target depth, reload omitted source structural values, validate repair roots before writes, publish freshness before interval writes, and make zero-height gaps no-ops |
+| `nested-set-10` | Deletion behavior and scalability | Major | High | Bulk deletion is scalable but cannot offer descendant events, while naïve evented deletion would recurse through package gap handling | Keep set-based deletion as the default and provide protected Laravel-shaped evented deletion hooks with keyset chunks and exact veto handling |
+| `nested-set-11` | Integrity defect | Major | High | Pairwise or PHP tree checks are slow, scoped diagnostics can inspect the wrong tree, and prior categories are incomplete or misleading | Use one portable endpoint-window query, exact named categories, concrete-scope enforcement, and cheap-first brokenness checks |
+| `nested-set-12` | Repair and rebuild defect | Critical | High | Orphans, cycles, vetoed saves, post-gap snapshots, or parentage outside a subtree's bounds can silently misreport success or corrupt coordinates | Repair iteratively with checked saves, exact original-snapshot reconciliation, complete-set boundary validation, maintained depth/scope, and transaction-visible exceptions |
+| `nested-set-13` | Worker metadata and test lifecycle improvement | Minor | High | Repeated trait discovery wastes CPU and obsolete relation cleanup no longer resets the actual package cache | Cache trait membership per concrete class, expose `NestedSet::flushState()`, and make Testing own its one authoritative reset |
+| `nested-set-14` | Metadata, documentation, and maintenance defect | Minor | High | Package dependencies, provenance, public guidance, native types, and PHPStan suppressions lag the supported design | Declare exact split metadata, name Aimeos as the maintained reference, document the final contracts/tradeoffs, and retain only identifier-scoped suppressions |
+| `nested-set-15` | Upstream test defect | Minor | High | Two Aimeos tests call nonexistent methods and another test named for insertion-before calls insertion-after; broad exception expectations hide all three mismatches | Call the real mutation API named by each test and assert the exact guard messages |
+
+- **Approved owner gates and intentional differences:** The owner approved mandatory stored depth, bigint/integer/native-UUID-or-compatible/ULID schema helpers, the three-index layout, explicit concrete scopes for structural diagnostics and scalar lookups, stored named integrity categories, bounded worker-static trait metadata, protected evented descendant deletion, and the measured write/storage cost required for much faster reads and better scope isolation. Existing useful Laravel/Eloquent-shaped APIs remain; Aimeos is the ongoing source reference but not a parity constraint.
+- **Important rejected concerns:** Do not add a package lock, retry/backoff, timeout, schema-introspection cache, optional-depth fallback, default depth index, widened bounds, self-FK, arbitrary ID-type selector, scope registry, restore stack, worker-retained tree index, global result sort/re-sort, pairwise crossing join, whole-tree PHP scanner, scalar-ID encoder, unconditional movement refresh, implicit relation cache, default per-descendant events, or compatibility layer for the former schema/results. These either duplicate framework/database ownership, regress measured write or memory behavior, or address no supported failure.
+- **Implementation:** Schema macros and split discovery now create typed parents, stored depth, and exact scoped indexes. Model actions, builders, relations, collections, repair/rebuild, and diagnostics use one scope/key/structural-query model; structural writes maintain bounds, parentage, and depth together. Real sibling relations, adaptive eager matching, iterative collection linking, exact restore/freshness publication, evented-deletion hooks, and bounded trait metadata replace stale or incomplete paths. Dead properties, overrides, constants, helpers, imports, comments, fixture resets, integrity categories, and obsolete suppressions are removed.
+- **Cross-package revalidation:** `database-10` is complete for Nested Set: schema helpers and all structural paths use the pooled Database connection/builder lifecycle without retaining connection objects or bypassing supported query construction. `nested-set-13` updates Testing's authoritative static-state subscriber and its regression; the later full Testing audit must preserve this cleanup registration. Eloquent's existing soft-delete and custom-builder metadata remain the single owners instead of gaining package caches.
+- **Regression tests:** Unit and SQLite/Testbench coverage proves all scalar/model key shapes, exact scopes, model date-format normalization without connection resolution, logical connection/table freshness, custom builders, event-free connection-preserving existence aliases, qualified/nested relation queries, sibling relations, adaptive eager matching, collection linking, every movement/deletion mode including partial structural projections, stored depth, integrity categories, repair/rebuild root and boundary refusal before writes, veto/snapshot behavior, trait caching, cleanup, and schema macro re-registration. Driver-routed MySQL, MariaDB, PostgreSQL, and SQLite integration coverage proves exact parent types/index order, integer and UUID trees, scope isolation, portable diagnostics, and persisted subtree depth.
+- **Performance and complexity:** Benchmarks selected operation-local scope indexes and the three database indexes over Aimeos's retained global index and the former quadratic matcher. Against the former Hypervel matcher, large eager matches fall from hundreds or thousands of milliseconds to tens. Against Aimeos's global index, the final design retains about 6 MiB instead of roughly 37–45 MiB. Representative scoped reads improve materially on every supported driver; structural index writes cost about 1.6x on MySQL and 1.3x on PostgreSQL in the measured worst cases, with MariaDB/SQLite neutral or faster. Ordinary model checks gain one bounded static lookup; no network call, lock, retry, worker-retained tree, or hidden serialization is introduced.
+- **Public result:** Nested Set remains Eloquent-shaped and adds modern schema, typed-key, sibling-relation, stored-depth, repair, rebuild, and diagnostic APIs. Bulk deletion remains the scalable default. Transactions and application-owned serialization remain required for concurrent writes to one tree. Native UUID columns are supported where the database does so, including PostgreSQL and supported MariaDB versions.
+- **Validation and review:** Every changed/new test file passed immediately; focused Nested Set and Testing suites, real four-driver integration routes, metadata and suppression audits, `git diff --check`, and the authoritative `composer fix` gate passed. Fresh caller/callee, scope, SQL, lifecycle, public API, documentation, hot-path, retained-memory, stale-code, and overengineering review is complete. Independent review re-read every changed source/test file and re-ran the gates. It found and corrected post-gap subtree rows omitted from persistence, wrong nested existence correlation, ambiguous joined sibling predicates, premature parent cloning during recursive creation, and compound-order handling exposed by the added regression; it also corrected the reasoning behind a rejected repair guard before signing off. Automated pull-request review later exposed custom date-format mismatch and observable replication during existence-query construction; both were corrected at their owning boundaries.
+- **Assessment:** Every accepted Nested Set finding is fixed at its lowest owner. The result is scope-correct, coroutine-safe, UUID/ULID-capable, substantially faster and more memory-efficient on large scoped trees, and complete across mutation, relation, repair, and diagnostic paths. It contains no workaround, speculative abstraction, hidden I/O, meaningful unaccounted hot-path regression, unresolved accepted defect, or stale superseded path.