docs(contracts): apply compat-fallback taxonomy to resolved-layout fragmentIndex (SD-2923) (#3112)

The four `fragmentIndex` fields on ResolvedFragmentItem / Table / Image /
Drawing previously used the word "legacy" with three different shades
across the layout-engine - older path, current fallback, and removed
code - all conflated. In this file, "legacy" actually means the *current
load-bearing fallback* the painter uses to read inner content from
Fragment until ResolvedFragmentItem carries full content directly.

Apply the compat-fallback term from comment-policy.md uniformly: each
fragmentIndex field now carries an AIDEV-NOTE: compat-fallback anchor
naming what triggers the fallback (ResolvedFragmentItem missing
content) and the retirement condition (paint items become
self-describing). Drop "legacy content lookup" trailer from
ResolvedFragmentItem.blockId and rewrite the type-level docstring to
reference the per-field anchor instead of "legacy fragment renderers".

This is the first in-the-wild use of the loaded-term taxonomy added in
#3103. No behavior change.

Author: caio-pizzol

packages/layout-engine/contracts/src/resolved-layout.ts

@@ -89,8 +89,9 @@ export type ResolvedGroupItem = {
 
 /**
  * A resolved fragment wrapper item.
- * Carries positioning and metadata needed to create the fragment's DOM wrapper,
- * while inner content rendering is delegated to legacy fragment renderers via fragmentIndex.
+ * Carries positioning and metadata needed to create the fragment's DOM wrapper.
+ * Inner content rendering is delegated to the Fragment-based render path via
+ * fragmentIndex; see the compat-fallback note on that field.
  */
 export type ResolvedFragmentItem = {
   kind: 'fragment';
@@ -110,9 +111,16 @@ export type ResolvedFragmentItem = {
   zIndex?: number;
   /** Source fragment kind — used by the painter for wrapper style decisions. */
   fragmentKind: Fragment['kind'];
-  /** Block ID — written to data-block-id and used for legacy content lookup. */
+  /** Block ID. Written to data-block-id. */
   blockId: string;
-  /** Index within page.fragments — bridge to legacy content rendering. */
+  /**
+   * Index back into page.fragments.
+   *
+   * AIDEV-NOTE: compat-fallback. The painter currently reads inner content from
+   * Fragment via this index because ResolvedFragmentItem does not carry full
+   * content yet. Becomes unused once paint items are self-describing; do not
+   * promote this to a permanent API surface.
+   */
   fragmentIndex: number;
   /** ProseMirror start position for click-to-position mapping. */
   pmStart?: number;
@@ -240,7 +248,14 @@ export type ResolvedTableItem = {
   zIndex?: number;
   /** Block ID — written to data-block-id. */
   blockId: string;
-  /** Index within page.fragments — bridge to legacy rendering. */
+  /**
+   * Index back into page.fragments.
+   *
+   * AIDEV-NOTE: compat-fallback. The painter currently reads inner content from
+   * Fragment via this index because ResolvedFragmentItem does not carry full
+   * content yet. Becomes unused once paint items are self-describing; do not
+   * promote this to a permanent API surface.
+   */
   fragmentIndex: number;
   /** ProseMirror start position for click-to-position mapping. */
   pmStart?: number;
@@ -294,7 +309,14 @@ export type ResolvedImageItem = {
   zIndex?: number;
   /** Block ID — written to data-block-id. */
   blockId: string;
-  /** Index within page.fragments — bridge to legacy rendering. */
+  /**
+   * Index back into page.fragments.
+   *
+   * AIDEV-NOTE: compat-fallback. The painter currently reads inner content from
+   * Fragment via this index because ResolvedFragmentItem does not carry full
+   * content yet. Becomes unused once paint items are self-describing; do not
+   * promote this to a permanent API surface.
+   */
   fragmentIndex: number;
   /** ProseMirror start position for click-to-position mapping. */
   pmStart?: number;
@@ -340,7 +362,14 @@ export type ResolvedDrawingItem = {
   zIndex?: number;
   /** Block ID — written to data-block-id. */
   blockId: string;
-  /** Index within page.fragments — bridge to legacy rendering. */
+  /**
+   * Index back into page.fragments.
+   *
+   * AIDEV-NOTE: compat-fallback. The painter currently reads inner content from
+   * Fragment via this index because ResolvedFragmentItem does not carry full
+   * content yet. Becomes unused once paint items are self-describing; do not
+   * promote this to a permanent API surface.
+   */
   fragmentIndex: number;
   /** ProseMirror start position for click-to-position mapping. */
   pmStart?: number;