fix(docs,migrate-ts): the remap hazard, measured instead of reasoned about

The previous commit claimed a member re-mapping is invisible to `meta migrate`
and that a swap emits no migration at all. Probing the real diff says otherwise,
and the corrected picture is both narrower and more useful:

- The CHECK list renders in @values order, so ANY remap changes its text. That
  emits drop-check + add-check, and drop-check is BLOCKED by default
  (allow.dropCheck) — migrate refuses. The refusal is an ACCIDENT: it fires
  because dropping a CHECK is destructive, not because anything recognises that
  the meaning of stored data just changed.
- Once allowed, the migration only refreshes the constraint and never touches
  the data. Moving a member to an unused int then applies a CHECK the existing
  rows violate and the database refuses it, loudly. SWAPPING two members leaves
  the admitted set identical, so it applies cleanly and every row has quietly
  changed meaning.
- Only one shape is invisible to the diff: a remap plus a compensating @values
  reorder renders a byte-identical CHECK, so there is no diff to block.

All three are now pinned in expected-schema-enum-intvaluemap.test.ts rather than
asserted in prose — including the known gap, marked KNOWN so a future change that
closes it updates the test instead of reverting the behaviour. Pinning the
accident matters most: nothing else stops `allow.dropCheck` from being relaxed
into a general auto-allow and taking the only protection with it.

CHANGELOG gains the adopter-facing version: do not remap on a populated table;
treat it as the same two-step backfill a backing-mode change needs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

CHANGELOG.md

@@ -67,6 +67,16 @@ that already has a column is a cross-kind `change-column-type`, which `meta migr
 blocks by default and requires an explicit `allow.typeChange` to pass. There is no
 auto-recast — the tool will not rewrite your data behind a metadata edit.
 
+**Do not RE-map a member's integer on a populated table.** Nothing understands that change:
+the column holds bare integers, and neither introspection nor the committed snapshot records
+which member an integer stood for. A remap changes the rendered `CHECK` list, so it trips the
+blocked `drop-check` and `meta migrate` refuses — but that refusal is incidental (dropping a
+`CHECK` is destructive), and once allowed the migration only refreshes the constraint and
+never touches your rows. Swap two members' integers and the new `CHECK` admits the same set,
+applies cleanly, and every stored row has quietly changed meaning. Reorder `@values` to
+compensate and the diff is empty outright. Treat a remap as the same two-step backfill a
+backing-mode change needs.
+
 Design: `docs/superpowers/specs/2026-07-23-int-backed-enum-values-design.md`. Adopter view:
 [`docs/features/field-types.md`](docs/features/field-types.md).
 

docs/superpowers/specs/2026-07-23-int-backed-enum-values-design.md

@@ -267,21 +267,33 @@ just golden-snapshot codegen.
 
 - Safe backing-mode migration (varchar↔integer recast with data preservation) — no
   current consumer; D8's manual path covers the only known need.
-- **RE-mapping an existing member's integer is not detected, and one shape of it is
-  silent.** D8 covers ADDING or REMOVING `@intValueMap`; it does not cover changing a
-  value inside a map that stays present. Two cases, only one of which is safe by
-  accident: changing a member to an integer not already in the set (`DRAFT: 0` → `1`)
-  alters the `CHECK`, so the migration applies a constraint every existing `0` row
-  violates and the database refuses it — loud, at apply time. But **swapping two members'
-  integers** (`DRAFT: 0, PUBLISHED: 5` → `DRAFT: 5, PUBLISHED: 0`) leaves the value SET
-  identical, so the `CHECK` is byte-identical, the diff is EMPTY, no migration is emitted
-  at all — and every stored row silently changes meaning. Nothing in the pipeline can see
-  it: the column holds bare integers, and neither the introspected schema nor the
-  committed schema snapshot records which member an integer stood for. Closing it needs
-  the mapping itself carried in gen-state or the snapshot so a diff can compare
-  member→int pairs rather than the value set — a design decision, not a patch. No current
-  consumer remaps; documented here rather than left implied by D8's "migration safety"
-  heading.
+- **RE-mapping an existing member's integer is not understood by anything; what saves you
+  is incidental.** D8 covers ADDING or REMOVING `@intValueMap`, not changing a value inside
+  a map that stays present. Measured against the real diff rather than reasoned about:
+
+  - **A remap that changes the rendered `CHECK` list** — which is every remap, since the
+    list renders in `@values` order — emits `drop-check` + `add-check`, and the `drop-check`
+    is **BLOCKED by default** (`allow.dropCheck`). So `meta migrate` refuses. That refusal
+    is a happy accident: it fires because dropping a `CHECK` is destructive, not because
+    anything recognises that the meaning of stored data just changed.
+  - **Once allowed, the migration only refreshes the constraint — it never touches the
+    data.** Moving a member to an int not already in the set (`DRAFT: 0` → `1`) then applies
+    a `CHECK` every existing `0` row violates, and the database refuses it: loud, at apply
+    time. But **swapping** two members' ints (`DRAFT: 0, PUBLISHED: 5` → `5, 0`) leaves the
+    admitted SET identical, so the new `CHECK` applies cleanly and every stored row has
+    quietly changed meaning.
+  - **One shape is invisible even to the diff:** a remap combined with a compensating
+    `@values` reorder renders a byte-identical `CHECK`, so the diff is EMPTY and no
+    migration is emitted at all.
+
+  Nothing in the pipeline can see the meaning change in any of these: the column holds bare
+  integers, and neither introspection nor the committed schema snapshot records which member
+  an integer stood for. Closing it needs the mapping itself carried in gen-state or the
+  snapshot so a diff can compare member→int PAIRS rather than the value set — a design
+  decision, not a patch. No current consumer remaps; documented here rather than left
+  implied by D8's "migration safety" heading, and pinned by
+  `expected-schema-enum-intvaluemap.test.ts` so the accident that currently protects the
+  common case cannot be removed silently.
 - Value aliasing (`allow_alias`-style opt-out of the duplicate-value rejection) — no
   current consumer.
 - Native Postgres `CREATE TYPE ... AS ENUM` — unrelated to this design, still deferred

server/typescript/packages/migrate-ts/test/expected-schema-enum-intvaluemap.test.ts

@@ -203,3 +203,51 @@ describe("int-backed enum — backing-mode change is blocked by the existing gua
     expect(r.changes.find((c) => c.kind === "change-column-type")).toBeUndefined();
   });
 });
+
+// RE-mapping a member inside a map that stays present is a different animal from D8's
+// add/remove, and nothing in the pipeline understands it: the column holds bare integers,
+// and neither introspection nor the committed snapshot records which member an integer
+// stood for. What currently protects the common case is an ACCIDENT — dropping a CHECK is
+// destructive, so the remap trips `allow.dropCheck` on its way past. These tests pin that
+// accident (so it cannot be relaxed silently) and pin the one shape it does not cover.
+describe("int-backed enum — re-mapping a member's integer", () => {
+  const MAP_SWAPPED = { DRAFT: 5, PUBLISHED: 0, ARCHIVED: 9 };
+  const MAP_MOVED = { DRAFT: 1, PUBLISHED: 5, ARCHIVED: 9 };
+
+  async function remapDiff(afterMap: Record<string, number>, afterValues = VALUES) {
+    const before = buildExpectedSchema(
+      await loadJson(entityModel({ name: "status", "@values": VALUES, "@intValueMap": INT_MAP })),
+    );
+    const after = buildExpectedSchema(
+      await loadJson(
+        entityModel({ name: "status", "@values": afterValues, "@intValueMap": afterMap }),
+      ),
+    );
+    return diff(after, before, { dialect: "postgres" });
+  }
+
+  // The CHECK list renders in @values order, so ANY remap changes its text — which is the
+  // only reason migrate sees a remap at all.
+  test("a swap trips the blocked drop-check rather than passing silently", async () => {
+    const r = await remapDiff(MAP_SWAPPED);
+    const drop = r.changes.find((c) => c.kind === "drop-check");
+    expect(drop).toBeDefined();
+    expect(drop!.status.state).toBe("blocked");
+    expect(r.changes.find((c) => c.kind === "add-check")).toBeDefined();
+  });
+
+  test("moving a member to an unused int behaves the same way", async () => {
+    const r = await remapDiff(MAP_MOVED);
+    expect(r.changes.find((c) => c.kind === "drop-check")!.status.state).toBe("blocked");
+  });
+
+  // The gap the two tests above do NOT cover: reorder @values to compensate for the swap
+  // and the rendered CHECK is byte-identical, so there is no diff to block. Every stored
+  // row changes meaning with no migration emitted at all. Pinned as KNOWN, not as desired
+  // — if a future change makes this produce a diff, this test should be updated, not the
+  // behaviour reverted.
+  test("KNOWN GAP: a compensating @values reorder makes the remap invisible to the diff", async () => {
+    const r = await remapDiff(MAP_SWAPPED, ["PUBLISHED", "DRAFT", "ARCHIVED"]);
+    expect(r.changes).toEqual([]);
+  });
+});