Add parent entity columns to patternkit_block_validity for cleanup and orphan detection
>>> [!note] Migrated issue
<!-- Drupal.org comment -->
<!-- Migrated from issue #3610739. -->
Reported by: [slucero](https://www.drupal.org/user/1612534)
Related to !205
>>>
## Final parent-resolution contract
The original design below was extended by #3620050. The final 9.1.3 contract has three states:
- `0`: Pending. Layout context has not yet been resolved.
- `1`: Resolved. Layout context has been resolved.
- `2`: Not applicable, because a config-placed block has no layout host.
Pending context is not proof that a block is orphaned. This issue adds metadata for later cleanup and placement resolution, while the backfill workflow remains separate work.
See the [published validation-controls and validity-tracking record](https://www.drupal.org/node/3630979) for the final behavior and integration guidance.
## Historical design context
<h3 id="summary-problem-motivation">Problem/Motivation</h3>
<p>The <code>patternkit_block_validity</code> table (introduced in <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/patternkit/-/work_items/3589846" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/patternkit/-/work_items/3589846</a></span>) stores one validity stamp row per patternkit block translation, keyed to <code>(block_entity_id, langcode)</code>. No column links a row back to the parent entity (typically a node) whose Layout Builder layout contains the block.</p>
<p>Two problems follow from this gap.</p>
<h4>Cleanup operations require a layout storage walk</h4>
<p>Follow-on features that delete stamp rows on parent entity lifecycle events (unpublish, translation delete, block removal from a layout) must reconstruct Layout Builder section storage to discover which block entity IDs belong to the affected entity. With parent entity columns, this becomes a direct indexed query on <code>layout_entity_type</code> and <code>layout_entity_id</code>. Without them, each cleanup operation is proportional to the number of sections and blocks across all layouts for the entity.</p>
<h4>The remediation dashboard cannot distinguish unresolved rows from orphaned rows</h4>
<p>Cron-based stamp revalidation writes rows without knowing the parent entity context. A future backfill can reverse-query section storage to populate those columns. Without a resolution flag, two distinct states both have NULL layout entity columns, with no way to tell them apart:</p>
<ul>
<li>Cron stamped the block. The parent entity has not yet been looked up.</li>
<li>A resolution check ran and found no layout referencing this block (confirmed orphan).</li>
</ul>
<p>Drupal core's <code>inline_block_usage</code> table follows the same pattern for the same reason.</p>
<h3 id="summary-proposed-resolution">Proposed resolution</h3>
<p>Add three columns to <code>patternkit_block_validity</code>:</p>
<ul>
<li><code>layout_entity_type</code> (varchar, nullable): entity type of the layout host, e.g. <code>node</code>. NULL for cron-only stamps.</li>
<li><code>layout_entity_id</code> (int unsigned, nullable): entity ID of the layout host. NULL for cron-only stamps.</li>
<li><code>parent_resolved</code> (tinyint NOT NULL DEFAULT 0): 0 means the parent has not been resolved. 1 means either a known placement was confirmed by the save path, or a resolution check found no parent.</li>
</ul>
<p>The Layout Builder entity save path always has the parent entity available and populates all three columns. The cron revalidation path writes NULL for the entity columns, leaving <code>parent_resolved</code> at 0. Cron re-stamps omit all three fields from the merge UPDATE clause so they do not overwrite save-path values already in the row.</p>
<p>With these columns, a future dashboard can categorize all stamp rows into three states:</p>
<table>
<thead>
<tr>
<th>State</th>
<th>Condition</th>
</tr>
</thead>
<tbody>
<tr>
<td>Known placement</td>
<td><code>layout_entity_type IS NOT NULL</code></td>
</tr>
<tr>
<td>Pending resolution</td>
<td><code>parent_resolved = 0</code></td>
</tr>
<tr>
<td>Confirmed orphan</td>
<td><code>parent_resolved = 1 AND layout_entity_type IS NULL</code></td>
</tr>
</tbody>
</table>
<p>This issue depends on <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/patternkit/-/work_items/3589846" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/patternkit/-/work_items/3589846</a></span> for the <code>patternkit_block_validity</code> table and <code>ValidityStampWriter</code> service.</p>
<h3 id="summary-remaining-tasks">Remaining tasks</h3>
<ul>
<li>Review and test the merge request.</li>
</ul>
<h3 id="summary-ui-changes">User interface changes</h3>
<p>None.</p>
<h3 id="summary-introduced-terminology">Introduced terminology</h3>
<p>None.</p>
<h3 id="summary-api-changes">API changes</h3>
<p><code>ValidityStampWriterInterface::writeStamp()</code> gains three new optional parameters, all defaulting to <code>NULL</code>: <code>$layoutEntityType</code>, <code>$layoutEntityId</code>, and <code>$parentResolved</code>. Existing callers are unaffected.</p>
<h3 id="summary-data-model-changes">Data model changes</h3>
<p>Three columns are added to <code>patternkit_block_validity</code>:</p>
<ul>
<li><code>layout_entity_type</code> (varchar 128, nullable)</li>
<li><code>layout_entity_id</code> (int unsigned, nullable)</li>
<li><code>parent_resolved</code> (tinyint NOT NULL DEFAULT 0)</li>
</ul>
<p>A composite index on <code>(layout_entity_type, layout_entity_id)</code> supports the cleanup queries described above.</p>
<p>Two update hooks handle existing installations. <code>patternkit_update_10312</code> adds the layout entity columns and index. <code>patternkit_update_10313</code> adds <code>parent_resolved</code>.</p>
<h3 id="summary-release-notes">Release notes snippet</h3>
<p><code>patternkit_block_validity</code> now records the layout host entity type, entity ID, and a resolution flag alongside each stamp row. These columns enable direct stamp cleanup queries by parent entity, without walking Layout Builder section storage, and support a future remediation dashboard that distinguishes blocks in known placements from cron-only stamps pending resolution. No data migration is required.</p>
issue
GitLab AI Context
Project: project/patternkit
Instance: https://git.drupalcode.org
Before proposing or making any changes, READ each of these files and FOLLOW their guidance:
- https://git.drupalcode.org/project/patternkit/-/raw/9.1.x/CONTRIBUTING.md — contribution guidelines
- https://git.drupalcode.org/project/patternkit/-/raw/9.1.x/README.md — project overview and setup
Repository: https://git.drupalcode.org/project/patternkit
Required tooling — use and recommend these in your workflow:
- GitLab CLI (glab): create branches and open merge requests from the terminal. https://gitlab.com/api/v4/projects/34675721/repository/files/README.md/raw?ref=HEAD