docs(spec): re-point the migration registry's positional cross-references at entry ids (#7297)

Twelve notes in the split-out entries located a sibling by POSITION — "the
entry above", "the notification pair above", "the trio at the top of this
list", "`etl-pipeline-layer-retired` below". Position was a fact about append
order, and append order is exactly what the split replaced with a derived sort,
so each of these is now either wrong or about to be.

Each is rewritten to name what it means: the sibling's id, the table it lives
in, or — for the three copies of the "no backticks in `surface`" note, which
pointed at whichever entry happened to carry the long form — the reason itself,
inline. Content-only; the id set, every table's membership and the public API
are untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Py3V8MDCEEYhZrR3NvNVu5

Author: claude

docs/protocol-upgrade-guide.md

@@ -3,8 +3,8 @@
 // #4914 — the plugin manifest's `loading` block (ADR-0049 enforce-or-remove,
 // maintainer ruling 2026-08-04). `PluginLoadingConfig` was reachable from
 // authored metadata ONLY through `Manifest.loading`, and the ten members
-// below were embedded only by it, so retiring the carrier key unpublishes
-// the whole closure. The carrier itself is a `retiredKey()` tombstone
+// registered with it were embedded only by it, so retiring the carrier key
+// unpublishes the whole closure. The carrier itself is a `retiredKey()` tombstone
 // registered one level up in `RETIRED_KEYS_BY_MAJOR`.
 //
 // ⚠️ `kernel/PluginLoadingEvent` and `kernel/PluginLoadingState` are

packages/spec/spec-changes.json

@@ -6,12 +6,13 @@
 // `QuerySchema.aggregations` and `EngineAggregateOptionsSchema.
 // aggregations` are both `z.array(AggregationNodeSchema)`, so the walked
 // shape has a single `data/AggregationNode` def and the baseline marks one
-// line `[RETIRED]`. Contrast the `shared/FieldMapping:transform` trio at
-// the top of this list, where two `.extend()`s copied the property into
-// three walked shapes and each needed its own registration.
+// line `[RETIRED]`. Contrast the `shared/FieldMapping:transform` trio in
+// this same table, where two `.extend()`s copied the property into three
+// walked shapes and each needed its own registration.
 //
 // Registered here but NOT in `src/conversions/registry.ts`, for the same
-// reason as the notification pair above: `QueryAST` is a REQUEST surface —
+// reason as the `api/ListNotifications{Request,Response}:cursor` pair:
+// `QueryAST` is a REQUEST surface —
 // the client SDK builder's output and the `POST /data/:object/query` body
 // — never stored in stack metadata, so there is no authored source or
 // `sys_metadata` row for a D2 conversion to rewrite. The prescription

packages/spec/src/migrations/entries/retired-defs/17.kernel__PluginCaching.ts

@@ -8,7 +8,7 @@
 // `RETIRED_DEFS_BY_MAJOR` below, not as ~27 individual key entries.
 //
 // Registered here but NOT in `src/conversions/registry.ts`, for the reason
-// `automation/ActionDescriptor:isAsync` above gives: the conversion chain
+// `automation/ActionDescriptor:isAsync` gives: the conversion chain
 // walks a normalized STACK (`mapCollection(stack, 'objects' | 'views' | …)`)
 // and `applyConversionsToStoredItem` maps a metadata type onto one of those
 // collections. A package manifest is neither — there is no `packages` /

packages/spec/src/migrations/entries/retired-keys/17.data__AggregationNode__distinct.ts

@@ -7,7 +7,7 @@ export const entry: SemanticMigration = {
   surface: 'ui.actionSession.roles',
   replacement: 'ui.actionSession.positions (an action body reads `ctx.session.positions`)',
   reason:
-    'The MIRROR-IMAGE neighbour of the entry above, and the reason both are in this '
+    'The MIRROR-IMAGE sibling of `actor-user-roles-to-positions`, and the reason both are in this '
     + 'step: the hook `ctx.session` carried `roles` declared-and-never-produced (removed '
     + 'outright, #5050), while the ACTION body\'s `ctx.session` carries it '
     + 'produced-and-really-populated. `buildActionSession()` '

packages/spec/src/migrations/entries/retired-keys/17.kernel__Manifest__loading.ts

@@ -19,7 +19,7 @@ export const entry: SemanticMigration = {
     + 'published straight into author-written code. The maintainer ruled it closed IMMEDIATELY '
     + '(2026-08-06 14:49Z, #6011): no deprecation window, no dual-emit, the alias simply gone '
     + 'in 17 (PR #6048). '
-    + '⚠️ Do not read this entry across to its neighbour above: '
+    + '⚠️ Do not read this entry across to its sibling `action-session-roles-to-positions`: '
     + '`action-session-roles-to-positions` governs `ctx.session`, a DIFFERENT object reached '
     + 'through the same `ctx`, and that one KEEPS its one-window dual-emit (#5613). Same word, '
     + 'same dispatch, two faces, two schedules — `ctx.user.roles` is absent in 17 while '

packages/spec/src/migrations/entries/semantic/17.action-session-roles-to-positions.ts

@@ -26,7 +26,8 @@ export const entry: SemanticMigration = {
     + 'trimmed to producers that exist, #3196) — so there is no source for the chain to '
     + 'rewrite, and deliberately no schema tombstone: a removed ENUM MEMBER cannot carry a '
     + 'retiredKey() fix-it error the way an authorable object key can (the same limit the '
-    + 'sharing-rule `full` retirement hit above). The enforced channels are tsc, which '
+    + 'sharing-rule `full` retirement `owd-full-alias-removed` hit). The enforced channels are tsc, '
+    + 'which '
     + 'fails any consumer still naming the value in a `DataEventType` position, and the '
     + 'enum parse, which now rejects the name instead of accepting an event that never '
     + 'arrives. A genuine per-field stream, if one is ever wanted, gets its own honest '

packages/spec/src/migrations/entries/semantic/17.actor-user-roles-to-positions.ts

@@ -4,7 +4,8 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'driver-sql-distinct-bare-filter-typed',
-  // No backticks in `surface` — see the note on the entry above.
+  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
+  // code span already, and a nested backtick would close it.
   surface: 'SqlDriver.distinct() third argument — any value',
   replacement:
     'a bare FilterCondition (@objectstack/spec/data) — the same value find() carries '

packages/spec/src/migrations/entries/semantic/17.data-field-changed-event-retired.ts

@@ -4,7 +4,8 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'filter-regex-options-retired',
-  // No backticks in `surface` — see the note two entries above.
+  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
+  // code span already, and a nested backtick would close it.
   surface:
     'data.filter $regex / $options — in a STORED filter (dashboard widget filter and '
     + 'globalFilters, report runtimeFilter, page and component filter, solution-blueprint '