Manifest resource_iris: emit a nested resource tree per depth (#197)

resource_iris changes from string[][] to NestedJsonStructure[] — the outer array stays indexed by rendering depth (root first), but each depth is now a recursive { iri, children } tree preserving resource containment (route -> pageData -> page -> componentGroup -> position -> component), so the front-end can render placeholders that mitigate layout shift.

- ManifestDepthGroupTrait: buildDepthNodes builds the per-depth tree instead of flattening; same IRI set, per-depth dedup, blank-node/back-reference/@-key exclusions. Skipped/blank/duplicate resources hoist their children so no noise nodes appear.

- Hard swap (no parallel key) — coordinated BC break with cwa-nuxt-module #250, migrated in tandem. Node key is 'iri' (bespoke DTO field). No per-node metadata yet (deliberate follow-up).

- Behat manifest assertions converted to new DoctrineContext tree steps; ManifestDepthGroupTraitTest asserts exact nested structures. Full suite green.

Author: silverbackdan

CLAUDE.md

@@ -510,7 +510,7 @@ Leave this issue open until the front-end approach and component-state semantics
 
 **Implemented.** Declaration is a **Silverback class attribute** `#[Silverback\ExplicitAllowOnly]` (`src/Annotation/ExplicitAllowOnly.php`) read by `ExplicitAllowOnlyAttributeReader` (`src/AttributeReader/`, extends `AttributeReader`, service `silverback.api_components.attribute_reader.explicit_allow_only` — mirrors `Publishable`/`Timestamped`/`Uploadable`). This is the bundle's own attribute system — a component type declares the attribute, no interface to implement. `AbstractComponent::isPositionRestricted()` and the `RestrictedComponent` override are **removed**; `RestrictedComponent` carries `#[Silverback\ExplicitAllowOnly]`. `ComponentPositionValidator` now checks `$this->explicitAllowOnlyReader->isConfigured(...)` on **both** placement paths (was `isPositionRestricted()`): `validateDirectComponent` (the placed component) **and** `validateDynamicPosition` (the pageDataProperty's resolved `componentClass`) — the dynamic path was restructured to mirror the direct path so a restricted type can't be bound to a dynamic position in an unrestricted group and bypass the rule server-side. Exposure to the front-end matches the module's already-locked contract: `VersionedDocumentationNormalizer` adds `explicitAllowOnly => true` to each flagged component's Hydra `supportedClass` entry (matched by `title` = short name; flagged short names found by walking `ResourceNameCollectionFactory` and testing each class with the reader). The module already reads `supportedClass['explicitAllowOnly'] === true` (absent ⇒ false) in `getComponentMetadata`, so **no module code change is required**. Behat: `features/main/component_position.feature` covers both the direct path (RestrictedComponent) and the dynamic path (via new test entity `PageDataWithRestrictedComponent`, whose `restrictedComponent` property resolves to a RestrictedComponent) — rejected in an unrestricted group (422), accepted when the group lists it (201); new `features/main/explicit_allow_only.feature` asserts the docs flag (RestrictedComponent → true, DummyComponent → false).
 
-**⚠ Outstanding — dynamic page-data-property positions.** The reader check was added only to `ComponentPositionValidator::validateDirectComponent`. `validateDynamicPosition` still returns early when a group has no `allowedComponents`, so an `explicitAllowOnly` component surfaced as a **page-data property** can still be positioned into an unrestricted group — bypassing the restriction. Decision (cwa-nuxt-module #249): `explicitAllowOnly` applies to **both** placement paths. **TODO:** in `validateDynamicPosition`, after resolving `$componentClass = $propertyMetadata->getComponentClass()`, apply the same `ExplicitAllowOnlyAttributeReader` check (reject when the group doesn't explicitly allow that component class), mirroring `validateDirectComponent`. Add a Behat scenario for the dynamic-position case. The front-end (module) already blocks both paths (`AddComponentDialog` + `useDynamicPositionSelectOptions.getPropertyOptions`), so this closes the server-side bypass.
+**Both placement paths enforced.** `explicitAllowOnly` applies to **direct** components (`validateDirectComponent`) **and** **dynamic** page-data-property positions (`validateDynamicPosition`, checking the property's resolved `componentClass`), so a flagged type can't be bound to a dynamic position in an unrestricted group and bypass the rule server-side. The front-end (module) blocks both paths too (`AddComponentDialog` + `useDynamicPositionSelectOptions.getPropertyOptions`). Only remaining cross-repo item: component cloning (cwa-nuxt-module #157) must also respect the flag.
 
 ---
 <details><summary>Original issue context</summary>
@@ -649,7 +649,11 @@ Depends on #194. References: `src/Fixture/CwaFixtureBuilder.php` (flush phases;
 
 ---
 
-### #197 — Manifest: each depth's payload becomes a nested resource tree (`NestedJsonStructure[]`) — front-end: cwa-nuxt-module #250
+### #197 — Manifest: each depth's payload is a nested resource tree (`NestedJsonStructure[]`) — front-end: cwa-nuxt-module #250 ✓ **DONE (API side)**
+
+**Implemented.** `GET /_/resource_manifest/{id}` now returns `resource_iris` as an array indexed by rendering depth (root first) where **each element is a nested tree node `{ "iri": string, "children": [...] }`** instead of a flat `string[]`. Only `ResourceManifestNormalizer` emits `resource_iris` (via `ManifestDepthGroupTrait`; `RouteNormalizer` does not). The trait was rewritten: `buildDepthGroups` splits depths on the `parentPage`/`parentPageData` boundary (unchanged) and, within each depth, `buildDepthNodes` builds the containment tree instead of flattening — same IRI set as before, same per-depth dedup, same blank-node/`resource_metadatas`/`@`-key/back-reference exclusions (skipped/blank/duplicate resources hoist their children so no noise nodes appear). **Decisions taken:** hard swap (no parallel key — pre-alpha BC break, ships in lockstep with module #250); node key is `iri` (not `@id` — bespoke DTO field); **no per-node metadata yet** (placeholder metadata is a deliberate follow-up). Tests: `tests/Serializer/Normalizer/ManifestDepthGroupTraitTest.php` asserts exact nested structures; `features/main/route.feature` + `features/main/page.feature` converted to new `DoctrineContext` steps (`the manifest depth :n root IRI should be …`, `… should have :n resource IRIs`, `… should contain the IRI …`, `… should contain/not contain an IRI matching …`) which flatten a depth's tree. Full suite green.
+
+<details><summary>Original design notes</summary>
 
 Change the manifest endpoints (`GET /_/resource_manifest/{id}` and the `Route:manifest:read` output) so each depth's payload is a **nested resource tree** instead of a flat list of IRIs. The **outer array stays indexed by rendering depth** (root first) — only the inner element type changes.
 
@@ -680,4 +684,7 @@ Page nesting → outer array index (as today); component nesting → the per-dep
 - **Node key** — `iri` + `children` (proposed) vs. `@id` to match JSON-LD conventions used elsewhere.
 - **Siblings** — sibling child pages (tab bars) still come from `GET /_/routes/{id}/children`, not the manifest. Recommend keeping out for v1.
 
-References: `src/Serializer/Normalizer/Trait/ManifestDepthGroupTrait.php`, `src/Serializer/Normalizer/RouteNormalizer.php`, `src/Serializer/Normalizer/ResourceManifestNormalizer.php`. **Note:** the `resource_iris: string[][]` shape described elsewhere in this file (manifest sections + design decisions) is the *current* contract; #197 keeps the depth-indexed outer array but replaces each inner `string[]` with a `NestedJsonStructure` tree.
+References: `src/Serializer/Normalizer/Trait/ManifestDepthGroupTrait.php`, `src/Serializer/Normalizer/RouteNormalizer.php`, `src/Serializer/Normalizer/ResourceManifestNormalizer.php`.
+</details>
+
+> **⚠ Note:** the older `resource_iris: string[][]` description in the manifest architecture sections and design-decisions list above (e.g. "`resource_iris` is `string[][]`") is now **superseded by #197** — the shape is `NestedJsonStructure[]` (depth-indexed array of `{ iri, children }` trees).

features/bootstrap/DoctrineContext.php

@@ -1494,6 +1494,111 @@ public function theApiDocsSupportedClassShouldHaveExplicitAllowOnly(string $clas
         }
     }
 
+    // --- Manifest resource_iris (nested tree per depth, #197) ---
+    // resource_iris is an array indexed by rendering depth; each element is a nested node
+    // { iri, children: [...] }. These steps flatten a depth's tree to assert on its IRI set.
+    // Manual checks + plain exceptions: a failing Assert::* fatals under Behat (PHPUnit Exporter).
+
+    /**
+     * @Then the manifest depth :depth root IRI should be :iri
+     */
+    public function theManifestDepthRootIriShouldBe(int $depth, string $iri): void
+    {
+        $actual = $this->manifestDepthNode($depth)['iri'] ?? null;
+        if ($actual !== $iri) {
+            throw new \RuntimeException(\sprintf('Manifest depth %d root IRI is "%s", expected "%s".', $depth, $actual ?? 'null', $iri));
+        }
+    }
+
+    /**
+     * @Then the manifest depth :depth root IRI should be the IRI of the resource :name
+     */
+    public function theManifestDepthRootIriShouldBeTheIriOfTheResource(int $depth, string $name): void
+    {
+        $this->theManifestDepthRootIriShouldBe($depth, $this->restContext->resources[$name]);
+    }
+
+    /**
+     * @Then the manifest depth :depth should have :count resource IRIs
+     */
+    public function theManifestDepthShouldHaveResourceIris(int $depth, int $count): void
+    {
+        $iris = $this->flattenManifestNode($this->manifestDepthNode($depth));
+        if (\count($iris) !== $count) {
+            throw new \RuntimeException(\sprintf('Manifest depth %d has %d IRIs, expected %d: %s', $depth, \count($iris), $count, implode(', ', $iris)));
+        }
+    }
+
+    /**
+     * @Then the manifest depth :depth should contain the IRI :iri
+     */
+    public function theManifestDepthShouldContainTheIri(int $depth, string $iri): void
+    {
+        $iris = $this->flattenManifestNode($this->manifestDepthNode($depth));
+        if (!\in_array($iri, $iris, true)) {
+            throw new \RuntimeException(\sprintf('Manifest depth %d does not contain "%s". Has: %s', $depth, $iri, implode(', ', $iris)));
+        }
+    }
+
+    /**
+     * @Then the manifest depth :depth should contain an IRI matching :pattern
+     */
+    public function theManifestDepthShouldContainAnIriMatching(int $depth, string $pattern): void
+    {
+        $iris = $this->flattenManifestNode($this->manifestDepthNode($depth));
+        foreach ($iris as $iri) {
+            if (1 === preg_match($pattern, $iri)) {
+                return;
+            }
+        }
+        throw new \RuntimeException(\sprintf('Manifest depth %d has no IRI matching %s. Has: %s', $depth, $pattern, implode(', ', $iris)));
+    }
+
+    /**
+     * @Then the manifest depth :depth should not contain an IRI matching :pattern
+     */
+    public function theManifestDepthShouldNotContainAnIriMatching(int $depth, string $pattern): void
+    {
+        $iris = $this->flattenManifestNode($this->manifestDepthNode($depth));
+        foreach ($iris as $iri) {
+            if (1 === preg_match($pattern, $iri)) {
+                throw new \RuntimeException(\sprintf('Manifest depth %d unexpectedly contains "%s" matching %s.', $depth, $iri, $pattern));
+            }
+        }
+    }
+
+    /**
+     * @return array{iri?: string, children?: array}
+     */
+    private function manifestDepthNode(int $depth): array
+    {
+        $json = $this->jsonContext->getJsonAsArray();
+        $node = $json['resource_iris'][$depth] ?? null;
+        if (!\is_array($node)) {
+            throw new \RuntimeException(\sprintf('Manifest has no depth %d.', $depth));
+        }
+
+        return $node;
+    }
+
+    /**
+     * @return string[] every iri in the node tree, depth-first
+     */
+    private function flattenManifestNode(array $node): array
+    {
+        $iris = [];
+        if (isset($node['iri'])) {
+            $iris[] = $node['iri'];
+        }
+        foreach ($node['children'] ?? [] as $child) {
+            if (\is_array($child)) {
+                $iris = array_merge($iris, $this->flattenManifestNode($child));
+            }
+        }
+
+        return $iris;
+    }
+
     /**
      * @Then the response resource should be saved as :name
      */

features/main/page.feature

@@ -125,15 +125,15 @@ Feature: Page resources
     When I send a "GET" request to the resource "page_data_manifest"
     Then the response status code should be 200
     And the JSON node "resource_iris" should have 1 element
-    And the JSON node "resource_iris[0][0]" should be equal to the IRI of the resource "page_data"
+    And the manifest depth 0 root IRI should be the IRI of the resource "page_data"
 
   @loginAdmin
   Scenario: I can get a resource manifest for a nested PageData by UUID
     Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
     When I send a "GET" request to the resource "page_data_manifest"
     Then the response status code should be 200
     And the JSON node "resource_iris" should have 2 elements
-    And the JSON node "resource_iris[1][0]" should be equal to the IRI of the resource "page_data"
+    And the manifest depth 1 root IRI should be the IRI of the resource "page_data"
 
   @loginAdmin
   Scenario: I can PATCH a page when componentGroups are included in the request body
@@ -227,4 +227,4 @@ Feature: Page resources
     When I send a "GET" request to the resource "page_manifest"
     Then the response status code should be 200
     And the JSON node "resource_iris" should have 2 elements
-    And the JSON node "resource_iris[1][0]" should be equal to the IRI of the resource "page"
+    And the manifest depth 1 root IRI should be the IRI of the resource "page"

features/main/route.feature

@@ -224,65 +224,65 @@ Feature: Route resources
     Given there is a PageData resource with the route path "/my-route"
     When I send a "GET" request to "/_/resource_manifest//my-route"
     Then the response status code should be 200
-    And the JSON node "resource_iris[0][5]" should match the regex "/\/component\/dummy_components\/[a-z0-9\-]+/"
+    And the manifest depth 0 should contain an IRI matching "/\/component\/dummy_components\/[a-z0-9\-]+/"
 
   Scenario: The manifest includes component IRIs from allowedComponents-restricted pageDataProperty positions for anonymous users
     Given there is a pageDataProperty position with an allowed component type in a restricted group with route "/my-route"
     When I send a "GET" request to "/_/resource_manifest//my-route"
     Then the response status code should be 200
-    And the JSON node "resource_iris[0][5]" should match the regex "/\/component\/dummy_components\/[a-z0-9\-]+/"
+    And the manifest depth 0 should contain an IRI matching "/\/component\/dummy_components\/[a-z0-9\-]+/"
 
   Scenario: The manifest for a nested PageData route includes parent resource IRIs grouped by depth
     Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
     When I send a "GET" request to "/_/resource_manifest//conference/programme"
     Then the response status code should be 200
     And the JSON node "resource_iris" should have 2 elements
-    And the JSON node "resource_iris[0]" should have 3 elements
-    And the JSON node "resource_iris[1]" should have 3 elements
-    And the JSON node "resource_iris[0]" should contain the element "/_/routes//conference"
-    And the JSON node "resource_iris[1]" should contain the element "/_/routes//conference/programme"
+    And the manifest depth 0 should have 3 resource IRIs
+    And the manifest depth 1 should have 3 resource IRIs
+    And the manifest depth 0 should contain the IRI "/_/routes//conference"
+    And the manifest depth 1 should contain the IRI "/_/routes//conference/programme"
 
   Scenario: The manifest for a nested Page route includes parent resource IRIs grouped by depth
     Given there is a Page resource with the route path "/conference/programme" nested within the route "/conference"
     When I send a "GET" request to "/_/resource_manifest//conference/programme"
     Then the response status code should be 200
     And the JSON node "resource_iris" should have 2 elements
-    And the JSON node "resource_iris[0]" should have 2 elements
-    And the JSON node "resource_iris[1]" should have 2 elements
-    And the JSON node "resource_iris[0]" should contain the element "/_/routes//conference"
-    And the JSON node "resource_iris[1]" should contain the element "/_/routes//conference/programme"
+    And the manifest depth 0 should have 2 resource IRIs
+    And the manifest depth 1 should have 2 resource IRIs
+    And the manifest depth 0 should contain the IRI "/_/routes//conference"
+    And the manifest depth 1 should contain the IRI "/_/routes//conference/programme"
 
   Scenario: I can get a manifest of all unauthenticated resources that should be loaded for a route
     Given there is a PageData resource with the route path "/my-route"
     When I send a "GET" request to "/_/resource_manifest//my-route"
     Then the response status code should be 200
     And the JSON node "resource_iris" should have 1 element
-    And the JSON node "resource_iris[0][0]" should be equal to "/_/routes//my-route"
-    And the JSON node "resource_iris[0][1]" should match the regex "/\/page_data\/page_data_with_components\/[a-z0-9\-]+/"
-    And the JSON node "resource_iris[0][2]" should match the regex "/\/_\/pages\/[a-z0-9\-]+/"
+    And the manifest depth 0 root IRI should be "/_/routes//my-route"
+    And the manifest depth 0 should contain an IRI matching "/\/page_data\/page_data_with_components\/[a-z0-9\-]+/"
+    And the manifest depth 0 should contain an IRI matching "/\/_\/pages\/[a-z0-9\-]+/"
 
   @loginAdmin
   Scenario: I can get a manifest of all authenticated resources that should be loaded for a route
     Given there is a PageData resource with the route path "/my-route"
     When I send a "GET" request to "/_/resource_manifest//my-route"
     Then the response status code should be 200
     And the JSON node "resource_iris" should have 1 element
-    And the JSON node "resource_iris[0][0]" should be equal to "/_/routes//my-route"
-    And the JSON node "resource_iris[0][1]" should match the regex "/\/page_data\/page_data_with_components\/[a-z0-9\-]+/"
-    And the JSON node "resource_iris[0][2]" should match the regex "/\/_\/pages\/[a-z0-9\-]+/"
+    And the manifest depth 0 root IRI should be "/_/routes//my-route"
+    And the manifest depth 0 should contain an IRI matching "/\/page_data\/page_data_with_components\/[a-z0-9\-]+/"
+    And the manifest depth 0 should contain an IRI matching "/\/_\/pages\/[a-z0-9\-]+/"
 
   Scenario: A draft component resolved via pageDataProperty is excluded from the anonymous manifest
     Given there is a PageData resource with a draft component in a pageDataProperty position and the route path "/my-route"
     When I send a "GET" request to "/_/resource_manifest//my-route"
     Then the response status code should be 200
-    And the JSON node "resource_iris[0]" should not contain an element matching "/\/component\/dummy_publishable_components\/[a-z0-9\-]+/"
+    And the manifest depth 0 should not contain an IRI matching "/\/component\/dummy_publishable_components\/[a-z0-9\-]+/"
 
   @loginAdmin
   Scenario: A draft component resolved via pageDataProperty is included in the admin manifest
     Given there is a PageData resource with a draft component in a pageDataProperty position and the route path "/my-route"
     When I send a "GET" request to "/_/resource_manifest//my-route"
     Then the response status code should be 200
-    And the JSON node "resource_iris[0]" should contain an element matching "/\/component\/dummy_publishable_components\/[a-z0-9\-]+/"
+    And the manifest depth 0 should contain an IRI matching "/\/component\/dummy_publishable_components\/[a-z0-9\-]+/"
 
   @loginUser
   Scenario: When I create a redirect route, the cache should be cleared for the route being redirected to