docs(spec): say in the shipped artifact that a withdrawal is not reported

The per-release section carries ADR-0087 D4's four arrays, and the boundary
they draw — an id that disappeared from the published chain is deliberately
NOT reported — lived only in `composeReleaseChanges`'s JSDoc and the PR body.
A consumer reads `release.converted: []` as "no conversion change" while an id
really did leave the chain between the two releases.

Say it where a consumer reads it: the shipped manifest's `$comment` and the
upgrading page's "what it does not tell you" callout, with the two-manifest
comparison that does answer the question. Documentation of an existing
boundary — no fifth array, no shape change, and the generator and the release
gate are untouched.

Claude-Session: https://claude.ai/code/session_01LvwGppdonww4zGLWZo5rho
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

content/docs/upgrading.mdx

@@ -368,6 +368,16 @@ enforcing a constraint that was declared and inert, without adding or removing a
 single export. A delta of `0 added, 0 removed` is a real measurement of the
 export surface and says nothing about the accept-sets behind it — the release
 checklist above is still the record for those.
+
+**And it does not report withdrawals.** All four arrays report what a release
+**added**: `converted` and `migrated` list the ADR-0087 ids *first registered*
+in it. An id that **left** the published chain between the two releases is in
+none of them — `converted: []` means "this release registered none", never
+"none was withdrawn". ADR-0087 D4 names these four arrays and this section
+carries exactly those four; to see a withdrawal, compare the `aggregate`
+records of the two installed manifests (`.aggregate.converted[].conversionId`
+and `.aggregate.migrated[].migrationId`) — an id present in the older one and
+absent from the newer one was withdrawn.
 </Callout>
 
 ### The per-package changelogs are the exhaustive record

packages/spec/scripts/build-spec-changes.ts

@@ -203,7 +203,12 @@ function build(): string {
     $comment:
       'GENERATED (ADR-0087 D4) — do not edit. Regenerate with: pnpm --filter @objectstack/spec gen:spec-changes. ' +
       'A projection of the D2 conversion table + D3 migration chain; the upgrade guide and the MCP spec_changes ' +
-      'tool derive from this same data.',
+      'tool derive from this same data. ' +
+      'When a `release` section is present, its four ADR-0087 D4 arrays report what that release ADDED: ' +
+      '`added`/`removed` are the export-surface diff of the two published tarballs, and `converted`/`migrated` ' +
+      'are the D2/D3 ids FIRST REGISTERED in it. An id that LEFT the published chain between the two releases ' +
+      'is reported in none of them — `converted: []` means "this release registered none", never "none was ' +
+      'withdrawn"; a withdrawal is visible only by comparing two published manifests.',
     protocolVersion: PROTOCOL_VERSION,
     supportFloor: MIGRATION_SUPPORT_FLOOR,
     migrateCommand: `objectstack migrate meta --from <N>  (N >= ${MIGRATION_SUPPORT_FLOOR})`,

packages/spec/spec-changes.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "GENERATED (ADR-0087 D4) — do not edit. Regenerate with: pnpm --filter @objectstack/spec gen:spec-changes. A projection of the D2 conversion table + D3 migration chain; the upgrade guide and the MCP spec_changes tool derive from this same data.",
+  "$comment": "GENERATED (ADR-0087 D4) — do not edit. Regenerate with: pnpm --filter @objectstack/spec gen:spec-changes. A projection of the D2 conversion table + D3 migration chain; the upgrade guide and the MCP spec_changes tool derive from this same data. When a `release` section is present, its four ADR-0087 D4 arrays report what that release ADDED: `added`/`removed` are the export-surface diff of the two published tarballs, and `converted`/`migrated` are the D2/D3 ids FIRST REGISTERED in it. An id that LEFT the published chain between the two releases is reported in none of them — `converted: []` means \"this release registered none\", never \"none was withdrawn\"; a withdrawal is visible only by comparing two published manifests.",
   "protocolVersion": "17.0.0",
   "supportFloor": 10,
   "migrateCommand": "objectstack migrate meta --from <N>  (N >= 10)",