📚 Say what the relation-overlay comments mean, not which tracker entry they cite

Eight comments and docstrings in the relation-overlay sync namespace and
its suite cited internal work-tracker ids, nine in all. A code reader
cannot resolve them, and one had already been renamed in the tracker.
Each comment now says the point in plain words: the sibling ordinal is an
attribute of its own because the intervals answer containment only, the
move decision is not copied because a copy would drift, a refused move
is not a skip because a skip marks the index stale for good, and what
the design-system file measured. No code changes.

AI-assisted-by: claude-opus-5-5
Signed-off-by: Álvaro Tejero Cantero <alvorithm@teje.ro>

backend/src/app/graph/relation_overlay/sync.clj

@@ -33,11 +33,10 @@
   `:shape/order`, the sibling ordinal the builder derives from each
   container's `:shapes` vector. The fold keeps it **equal to a rebuild's**,
   because a consumer holding an index and no document reads it to learn a
-  shape's position among its siblings
-  (`pp:graph:sibling-order-needs-an-authored-attribute`,
-  `pp:graph:mirror-the-reorder-children-change`); the two derived layers
-  above are pinned by their invariants instead, because their values are
-  not comparable between the two paths.
+  shape's position among its siblings, and the Euler intervals answer
+  containment only. The two derived layers above are pinned by their
+  invariants instead, because their values are not comparable between the
+  two paths.
 
   Everything here is pure: db value in, db value out. The session layer
   owns the atom and the revision bookkeeping, and `staleness` tells it
@@ -528,9 +527,10 @@
 
   The predicate takes the objects-shaped view rather than an index, so
   this is the view: the index is not a second way to answer which moves
-  are legal (`pp:graph:database-is-the-boundary`). Parent and child ids
-  are shape ids, as they are in the document, so a shape the index parents
-  on its container — the page root frame, the root copy of a component
+  are legal, because a second copy of that rule would drift from the
+  document's with no test failing. Parent and child ids are shape ids, as
+  they are in the document, so a shape the index parents on its
+  container — the page root frame, the root copy of a component
   container — arrives with no parent, and the walk up stops where the
   document's stops.
 
@@ -569,7 +569,8 @@
   the index holds it at this point in the change list, and where the
   document leaves its objects untouched the index rewrites no datom. That
   is an applied change rather than a skip, because the fold still equals a
-  rebuild of the changed document (`pp:graph:stale-index-gate`)."
+  rebuild of the changed document, and a skip would mark the index stale
+  for good."
   [db {:keys [parent-id shapes index after-shape allow-altering-copies syncing] :as change}]
   (let [ceid (queries/container-eid db (change-container-id change))
         peid (when ceid (queries/shape-eid db ceid parent-id))]
@@ -959,10 +960,9 @@
   `:db.fn/retractEntity` retracts the entity's own datoms and every
   reference datom whose value is the entity, which here is every
   `:shape/fill-color`, `:shape/stroke-color`, `:shape/text-color` and
-  `:shape/uses-typography` pointing at the asset. On the design-system
-  file measured by
-  `pp:vcs:the-real-change-stream-is-attribute-shaped` one skipped
-  `:del-color` left up to 10,304 of those ref datoms behind."
+  `:shape/uses-typography` pointing at the asset. Measured on Penpot's
+  design-system file of 21,219 objects, one skipped `:del-color` left up
+  to 10,304 of those ref datoms behind."
   [db id-attr id]
   (if-let [eid (d/entid db [id-attr id])]
     (ok (d/db-with db [[:db.fn/retractEntity eid]]))

backend/test/backend_tests/relation_overlay_sync_test.clj

@@ -312,8 +312,8 @@
 
    {:type :purge-component :id comp-id}
 
-   ;; ---- library colours, the largest unsupported class in the stream
-   ;; measured by pp:vcs:the-real-change-stream-is-attribute-shaped
+   ;; ---- library colours, the largest unsupported class in the change
+   ;; stream of Penpot's 21,219-object design-system file
 
    ;; a fill on rect naming a colour the library does not hold yet: the raw
    ;; id lands in the index and no reference does, because a rebuild
@@ -813,10 +813,10 @@
 (t/deftest a-token-written-onto-a-taken-name-leaves-one-token
   ;; The two writes a taken token name can arrive from, each folded as a
   ;; list of two changes and compared against the rebuild. The rename is
-  ;; the branch whose document outcome reads the token map's order
-  ;; (`pp:graph:token-rename-displacement-is-order-dependent`); this list
-  ;; is the ordering where the holder is the one that goes, which is the
-  ;; reading the mirror takes.
+  ;; the branch whose document outcome reads the token map's order: the
+  ;; holder goes when it precedes the renamed token, and the renamed token
+  ;; goes when it follows the holder. This list is the ordering where the
+  ;; holder is the one that goes, which is the reading the mirror takes.
   (let [check (fn [label change-list displaced kept]
                 (let [result (sync/apply-changes (overlay/build (base-data)) change-list)
                       folded (:db result)
@@ -1014,8 +1014,7 @@
 ;; vector, and it is the one piece of order the index owns: the intervals
 ;; answer containment and are excluded from the comparison, so a consumer
 ;; holding an overlay and no document reads this attribute to learn which
-;; child of which parent a shape is
-;; (`pp:graph:sibling-order-needs-an-authored-attribute`).
+;; child of which parent a shape is.
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 (defn- ordinals
@@ -1173,11 +1172,10 @@
      :skipped  (:skipped result)}))
 
 (t/deftest a-move-the-gate-refuses-leaves-the-parent-edges-alone
-  ;; The measurement `pp:graph:the-move-mirror-ignores-the-validity-gate`
-  ;; records, on this fixture: the destination is a component copy, so the
-  ;; document refuses to move the main instance's child into it, and the fold
-  ;; used to follow the move anyway, leaving the fold with a parent edge the
-  ;; document never had.
+  ;; What this fixture measured before the fix: the destination is a
+  ;; component copy, so the document refuses to move the main instance's
+  ;; child into it, and the fold used to follow the move anyway, leaving
+  ;; the fold with a parent edge the document never had.
   (let [change (conj with-a-copy-on-the-page
                      {:type :mov-objects :page-id page-id
                       :parent-id copy-root-id :shapes [comp-child-id]})