diff --git a/‎.changeset/22482-spec-projections-generated-at-publish.md‎
Lines changed: 19 additions & 0 deletions b/‎.changeset/22482-spec-projections-generated-at-publish.md‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎.github/workflows/cut-rc.yml‎
Lines changed: 28 additions & 1 deletion b/‎.github/workflows/cut-rc.yml‎
Lines changed: 28 additions & 1 deletion
diff --git a/‎.github/workflows/lint.yml‎
Lines changed: 32 additions & 2 deletions b/‎.github/workflows/lint.yml‎
Lines changed: 32 additions & 2 deletions
diff --git a/‎.github/workflows/release.yml‎
Lines changed: 26 additions & 12 deletions b/‎.github/workflows/release.yml‎
Lines changed: 26 additions & 12 deletions
diff --git a/‎packages/spec/package.json‎
Lines changed: 2 additions & 1 deletion b/‎packages/spec/package.json‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎packages/spec/scripts/build-spec-changes.ts‎
Lines changed: 49 additions & 31 deletions b/‎packages/spec/scripts/build-spec-changes.ts‎
Lines changed: 49 additions & 31 deletions
@@ -0,0 +1,19 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): the protocol upgrade guide ships inside `@objectstack/spec`, and both ADR-0087 projections are generated and verified at publish
+
+Clause-②: no
+
+`@objectstack/spec` now ships `protocol-upgrade-guide.md` beside `spec-changes.json`. An upgrading project reads the guide for the exact version it installed, offline:
+
+```bash
+cat node_modules/@objectstack/spec/protocol-upgrade-guide.md
+```
+
+The same file is attached to the package's GitHub Release, next to `spec-changes.json`. Its content is unchanged: one section per protocol major from the chain's support floor on, generated from the ADR-0087 conversion table and migration chain.
+
+Both projections are now generated by the release lane, from the registries, right before the tarball is packed. The lane refuses to publish an artifact whose copies differ from a fresh generation. This covers the per-major records and aggregate of `spec-changes.json`, and the whole guide. The rc lane takes the same step, so an rc tarball no longer carries a copy that was committed earlier. The per-release `release` section of `spec-changes.json` is generated and verified exactly as before.
+
+Nothing changes for an author, and nothing is renamed or removed.
@@ -876,6 +876,31 @@ jobs:
             echo "::warning::hotcrm@${HOTCRM_REF} is incompatible with the pre-release train — expected for this window's deliberate removals. Ship a migrated hotcrm release, bump it, and set BLOCKING=1 in .github/workflows/release.yml to re-arm this gate."
           fi
 
+      # ────────────────────────────────────────────────────────────────────────
+      # ADR-0087 D4 — the two generated projections, under the #22449 B′ ruling.
+      #
+      # spec-changes.json and the protocol upgrade guide are generated from the
+      # registries at publish and nowhere else that ships; no committed copy is
+      # kept current any more. This lane used to pack whatever copy the tree
+      # held, so it now generates both into the package (`--generate`: the
+      # registry projections and NO per-release section — what an rc tarball has
+      # always carried) and refuses a tarball whose copies differ from a fresh
+      # generation (`--verify`), before anything reaches npm. Same order, same
+      # reason as release.yml's publish job: after `changeset publish` the
+      # tarball is immutable.
+      # ────────────────────────────────────────────────────────────────────────
+      - name: Generate the ADR-0087 projections into the package (ADR-0087 D4)
+        if: ${{ !inputs.dry_run }}
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: bash scripts/release-spec-changes.sh --generate
+
+      - name: Correctness gate — the packed projections must match the registries
+        if: ${{ !inputs.dry_run }}
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: bash scripts/release-spec-changes.sh --verify
+
       # ────────────────────────────────────────────────────────────────────────
       # PUBLISH. `pnpm run release` = build + build-console + release-publish.sh,
       # which is `changeset publish` followed by ONE atomic `git push origin --tags`
@@ -928,7 +953,9 @@ jobs:
 
       - name: Attach spec-changes.json to the GitHub Release (ADR-0087 D4)
         # Ordering is load-bearing: `gh release upload` needs the Release the step
-        # above created.
+        # above created. Uploads BOTH projections `--generate` wrote and `--verify`
+        # proved — spec-changes.json and protocol-upgrade-guide.md — so the Release
+        # assets and the tarball are the same bytes.
         if: ${{ !cancelled() && steps.publish.outputs.published == 'true' }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -5621,12 +5621,42 @@ jobs:
       - name: Check the meta-url-spelling data module is current and spellings agree
         run: pnpm --filter @objectstack/spec check:meta-url-spelling
 
-      - name: Check spec-changes.json is regenerated with the ADR-0087 registries
+      # The two ADR-0087 D4 projections, under the #22449 B′ ruling. They are
+      # generated where they ship — at publish, by scripts/release-spec-changes.sh,
+      # which also verifies the packed copies against a fresh generation — so
+      # these two steps compare NO committed copy. They generate both from the
+      # registries in memory and go red only when generation fails, so a pull
+      # request that only adds a registry entry needs no regeneration commit.
+      # Like their neighbours they read source via tsx and need no build.
+      - name: Check spec-changes.json generates from the ADR-0087 registries
         run: pnpm --filter @objectstack/spec check:spec-changes
 
-      - name: Check the protocol upgrade guide is regenerated with the ADR-0087 registries
+      - name: Check the protocol upgrade guide generates from the ADR-0087 registries
         run: pnpm --filter @objectstack/spec check:upgrade-guide
 
+      # The ruling's condition (1): the review value the committed copies carried
+      # — the generated diff — stays on the pull request. Both sides are generated
+      # by the same `--out` generators the publish lane runs: this checkout's, and
+      # the base's own in a `git archive` of HEAD^1 (on a pull request, the base
+      # tip the merge ref sits on; on every other event, the previous commit). The
+      # diff renders into this job's summary and a notice annotation, which need
+      # no token that can write, and the step below uploads it as an artifact.
+      # Red only when a side cannot be generated; a diff is never red. Measured
+      # locally at ~6 s, no build needed.
+      - name: Render the generated spec-changes and upgrade-guide diff against the base
+        run: >-
+          pnpm --filter @objectstack/spec exec tsx scripts/render-projection-diff.ts
+          --base HEAD^1 --out-dir "$RUNNER_TEMP/spec-projections" --summary "$GITHUB_STEP_SUMMARY"
+
+      # Written only when the diff is non-empty, so an unchanged run uploads nothing.
+      - name: Upload the generated spec-projections diff
+        uses: actions/upload-artifact@v7
+        with:
+          name: spec-projections-diff
+          path: ${{ runner.temp }}/spec-projections/spec-projections.diff
+          if-no-files-found: ignore
+          retention-days: 14
+
       # The #4796 declaration-origin baseline. `export-origins/` records which
       # SOURCE DECLARATION every public entry point exports under every name, and
       # seventeen export-surface pin tests compare against it instead of each
 
@@ -444,11 +444,16 @@ jobs:
       #                                 without the whole spec suite, which
       #                                 this comment used to say it was not.
       #     check:spec-changes, check:upgrade-guide
-      #                                 the two committed artifacts DERIVED from
-      #                                 PROTOCOL_MAJOR (2-3 s each). Measured
-      #                                 RED on the boundary train: the version
-      #                                 pass moves the constant and regenerates
-      #                                 neither.
+      #                                 the two projections DERIVED from
+      #                                 PROTOCOL_MAJOR (2-3 s each). Before the
+      #                                 #22449 B′ ruling they compared committed
+      #                                 copies, and were measured RED on the
+      #                                 boundary train (the version pass moves
+      #                                 the constant and regenerated neither).
+      #                                 They now generate both in memory, since
+      #                                 the publish job generates the shipped
+      #                                 copies: red only when the post-version
+      #                                 tree cannot generate them.
       #
       # ⛔ WHAT IS DELIBERATELY NOT RUN, AND WHY IT IS NOT AN OMISSION.
       #   The whole derived farm. Fed this 313-path change set,
@@ -1253,7 +1258,9 @@ jobs:
         # `--prepare` regenerates the manifest against the previously published
         # tarball exactly as the publish job does: in the version commit's
         # tree, with that commit's generator. So the asset this repair uploads
-        # carries the same per-release section the npm artifact does. It cannot
+        # carries the same per-release section the npm artifact does — and, from
+        # the version commit that taught `--prepare` the upgrade guide on, the
+        # same guide. It cannot
         # repair the npm artifact itself — that tarball is immutable — and this
         # lane never publishes one.
         if: steps.audit.outputs.releases-missing == 'true'
@@ -1783,9 +1790,15 @@ jobs:
       # is immutable and the only remaining repair is another version.
       #
       # `--no-git-checks` is what `changeset publish` passes to `pnpm publish`
-      # (its own source), so the working-tree edit `--prepare` makes does not
-      # block the publish. The committed copy is untouched: it stays the
-      # registry-only projection `check:spec-changes` gates on every PR.
+      # (its own source), so the working-tree edits `--prepare` makes do not
+      # block the publish.
+      #
+      # Since the #22449 B′ ruling this is also where BOTH registry projections
+      # are generated for the tarball — spec-changes.json's per-major records and
+      # aggregate, and packages/spec/protocol-upgrade-guide.md — and `--verify`
+      # refuses a packed copy that differs from a fresh generation. No committed
+      # copy is read: the pull-request check generates the same projections in
+      # memory and renders their diff, and compares nothing.
       # ──────────────────────────────────────────────────────────────────────
       - name: Generate the per-release spec-changes section (ADR-0087 D4)
         env:
@@ -1886,13 +1899,14 @@ jobs:
 
       - name: Attach spec-changes.json to the GitHub Release (ADR-0087 D4)
         # Ordering is load-bearing: `gh release upload` needs the Release the
-        # step above created.
+        # step above created. Uploads both projections: spec-changes.json and
+        # protocol-upgrade-guide.md.
         if: ${{ !cancelled() && steps.publish.outputs.published == 'true' }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           RELEASE_VERSION: ${{ steps.guards.outputs.version }}
-        # Uploads the file the two steps above generated and verified — the
-        # Release asset and the npm artifact are the same bytes by construction,
+        # Uploads the files the two steps above generated and verified — the
+        # Release assets and the npm artifact are the same bytes by construction,
         # not by two runs agreeing.
         run: bash scripts/release-spec-changes.sh --attach
 
 
@@ -260,7 +260,8 @@
     "src/**/*.zod.ts",
     "CHANGELOG.md",
     "api-surface",
-    "spec-changes.json"
+    "spec-changes.json",
+    "protocol-upgrade-guide.md"
   ],
   "scripts": {
     "build": "pnpm gen:schema && pnpm gen:openapi && tsup && if [ -z \"$OS_SKIP_DTS\" ]; then NODE_OPTIONS=\"--max-old-space-size=6144\" BUILD_DTS=true tsup; fi && node ../../scripts/check-dts-emitted.mjs && node ../../scripts/check-dts-references.mjs && node ../../scripts/check-dev-prereqs.mjs --stamp",
 
@@ -8,19 +8,27 @@
  * conversion table and the D3 migration chain — folded per major from the
  * support floor to the current protocol major, plus one aggregate record for
  * the whole range. Because it is generated, it can never drift from what the
- * loader and `migrate meta` actually do; a CI `--check` enforces that the
- * committed copy is regenerated with any registry change (the ADR-0049
- * enforce-or-remove discipline applied to release artifacts).
+ * loader and `migrate meta` actually do.
  *
- *   pnpm --filter @objectstack/spec gen:spec-changes     # regenerate + write
- *   pnpm --filter @objectstack/spec check:spec-changes   # CI: fail on drift
+ * WHERE it is generated (#22449 B′): at publish, by
+ * `scripts/release-spec-changes.sh`, which writes it into the package before
+ * `npm pack` and verifies the packed copy against a fresh generation. The
+ * pull-request stage generates it IN MEMORY (`--check`) and compares no
+ * committed copy, so a pull request that only adds a registry entry needs no
+ * regeneration commit; `render-projection-diff.ts` renders the generated diff
+ * against the base on the pull request instead. The command-line contract is
+ * `lib/projection-cli.ts`.
+ *
+ *   pnpm --filter @objectstack/spec gen:spec-changes     # write the committed copy (until it is deleted)
+ *   pnpm --filter @objectstack/spec check:spec-changes   # CI: generate in memory, red when generation fails
+ *   tsx scripts/build-spec-changes.ts --out <file>       # write the generated bytes anywhere
  *
  * Release-time surface join: `--previous-surface <path>` diffs the current
  * committed export surface against a previously *published* one (both ship in
  * the npm artifact from protocol 15 on) and fills the `added[]`/`removed[]`
  * arrays of the aggregate record. The Release workflow runs this against the
  * last published spec tarball and attaches the result to the GitHub Release; the
- * committed copy keeps `added`/`removed` empty (registry-derived content only)
+ * registry-only projection (no previous artifact) keeps `added`/`removed` empty
  * so it stays deterministic.
  *
  * ⚠️ That diff is ONE RELEASE wide while the aggregate record is keyed by
@@ -43,9 +51,9 @@
  * (its `package.json`), the previous export surface and the previous
  * `spec-changes.json`, and writes a `release` section — `from → to` at
  * PACKAGE-VERSION resolution — into the manifest that is about to be packed.
- * The committed copy never carries it (generating it needs a published tarball,
- * so it could not be deterministic), which is exactly how the ruling answers
- * the determinism concern: publish time only.
+ * The registry-only projection never carries it (generating it needs a
+ * published tarball, so it could not be deterministic), which is exactly how the
+ * ruling answers the determinism concern: publish time only.
  *
  * ⛔ The section is OMITTED, loudly, rather than emitted empty when the previous
  * tarball lacks either input — an empty `release` is indistinguishable from
@@ -66,7 +74,7 @@
  * the PR. Measurement table: `../src/migrations/entries/README.md`.
  */
 
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -83,6 +91,7 @@ import {
   type SpecSurfaceRemove,
   type SpecSurfaceScope,
 } from '../src/migrations/spec-changes';
+import { exitWith, runProjectionCli } from './lib/projection-cli';
 import { API_SURFACE_DIR_NAME, readApiSurfaceFrom } from './lib/sharded-artifacts';
 
 const PKG_DIR = resolve(fileURLToPath(new URL('.', import.meta.url)), '..');
@@ -294,26 +303,35 @@ function build(): string {
   return `${JSON.stringify(doc, null, 2)}\n`;
 }
 
-const next = build();
+if (CHECK && (PREV_SURFACE || PREV_PACKAGE)) {
+  // The pull-request check is the REGISTRY-ONLY projection; the per-release
+  // section and the export diff need a published tarball and exist only at publish.
+  console.error(
+    'check mode generates the registry-only manifest in memory; drop ' +
+      (PREV_PACKAGE ? '--previous-package' : '--previous-surface'),
+  );
+  process.exit(2);
+}
 
-if (CHECK) {
-  if (PREV_SURFACE || PREV_PACKAGE) {
-    console.error(
-      'check mode compares the committed (registry-only) manifest; drop ' +
-        (PREV_PACKAGE ? '--previous-package' : '--previous-surface'),
-    );
-    process.exit(2);
-  }
-  const current = existsSync(SNAPSHOT) ? readFileSync(SNAPSHOT, 'utf8') : '';
-  if (current !== next) {
-    console.error(
-      'spec-changes.json is stale — the ADR-0087 registries changed without regenerating the manifest.\n' +
-        'Run: pnpm --filter @objectstack/spec gen:spec-changes  (and commit the result)',
-    );
-    process.exit(1);
-  }
-  console.log('spec-changes.json is up to date.');
-} else {
-  writeFileSync(SNAPSHOT, next);
-  console.log(`Wrote ${SNAPSHOT}`);
+/** One clause naming what a generated manifest holds, for `--check`'s success line. */
+function describeManifest(bytes: string): string {
+  const doc = JSON.parse(bytes) as {
+    protocolVersion: string;
+    perMajor: unknown[];
+    aggregate: { converted: unknown[]; migrated: unknown[] };
+  };
+  return (
+    `protocol ${doc.protocolVersion}, ${doc.perMajor.length} per-major record(s), aggregate ` +
+    `${doc.aggregate.converted.length} converted / ${doc.aggregate.migrated.length} migrated, ${Buffer.byteLength(bytes)} bytes`
+  );
 }
+
+exitWith(
+  runProjectionCli({
+    name: 'spec-changes.json',
+    committedPath: SNAPSHOT,
+    build,
+    describe: describeManifest,
+    argv: process.argv,
+  }),
+);