docs(naming): CHANGELOG upgrade-impact notes; README per-port table covers every refusal test file

CHANGELOG: spell out, for an already-plural entity name, exactly what
changes on upgrade (REST path, generated hook/query/finder/list names,
DbSet/collection names — old doubled URLs 404, hand-written code importing
the old symbol fails to compile/import after regen), what does NOT change
(default physical table/column names, frozen on purpose), that there is no
per-entity override for a route or generated name (TS `overrides` renames
only the Drizzle variable), and that a same-scope Singular/Plural entity
pair is now a generation error rather than a silent collision.

README: the per-port table only named the FIRST test file touched for
C#/Java/Python, missing the dedicated collision-refusal test files/theories
each port ended up with (CSharpNamingTests.cs's own theory, Java's
RouteNamingTest additions, Python's separate test_collection_name_collision.py).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M1mRRB1K2WdYy82kntMQdx

Author: dmealing

CHANGELOG.md

@@ -19,23 +19,48 @@ here.**
   ending in "s" as already-plural UNLESS the character before that final "s" is one of
   s/u/i/a (so `Stats`/`Settings`/`Series`/`News`/`Analytics`/`Photos` stay unchanged, while
   `Status`/`Address`/`Bonus`/`Alias`/`Gas`/`Analysis` keep pluralizing exactly as before —
-  the heuristic's one documented miss is `Lens` → `Lens`, correct plural `Lenses`). The
-  DEFAULT PHYSICAL table/column name derivation is explicitly **frozen** at the old
-  suffix-only rule in every port (a new, separately-named/byte-for-byte-preserved function
-  where the two pluralizers were previously the same function), so an adopter's existing
-  database never sees `meta migrate` propose a rename for an already-plural entity it
-  didn't touch. Fixing the doubling surfaced two further, narrower defects it was
-  incidentally masking: a TypeScript already-plural entity's generated Drizzle collection
-  variable name could collide with its own singular row variable in the same statement
-  (`const [x] = await db.insert(x)...`, a TDZ compile error) — the colliding local variable
-  now gets a `Row` suffix only in that exact case; and a C# already-plural entity's own
-  `DbSet` property name could collide with its own entity TYPE name inside `OnModelCreating`
-  (C# resolves a bare same-named reference to the DbSet member before the type, same
+  the heuristic's one documented miss is `Lens` → `Lens`, correct plural `Lenses`).
+
+  **Upgrade impact — read before regenerating.** If any entity name in your model is
+  already a plural noun (`Stats`, `Settings`, `Series`, and the like):
+  - **The REST collection path changes.** `/program_purchase_statses` becomes
+    `/program_purchase_stats`. A client still calling the old doubled URL gets a plain
+    404, not a redirect — update callers before or alongside the regen.
+  - **Generated hook, query, finder, and list function/method names change too**
+    (`useProgramPurchaseStatses` → `useProgramPurchaseStats`, `listProgramPurchaseStatses`
+    → `listProgramPurchaseStats`, the C# DbSet property, the Java/Python finder/router
+    names). Any hand-written code importing or calling the OLD doubled symbol fails to
+    compile (TS/C#/Kotlin) or import (Python) after you regenerate — grep for the old
+    spelling across your own code, not just generated output.
+  - **There is no per-entity override for a route or generated hook/finder/list name.**
+    TypeScript's `variableNameFromEntity`/`CollectionNameOptions.overrides` renames only
+    the Drizzle collection VARIABLE — it does not touch the REST path or any hook/query/
+    finder/list name. If the new spelling is wrong for your API, the fix is to rename the
+    entity itself; there is no config knob that renames only the generated surface.
+  - **Default PHYSICAL table and column names do NOT change.** The fallback used when
+    metadata declares no explicit physical name is explicitly **frozen** at the old
+    suffix-only rule in every port (a new, separately-named, byte-for-byte-preserved
+    function where the two pluralizers were previously the same one) — `meta migrate`
+    proposes no rename for an already-plural entity you didn't touch.
+  - **Two entities in one generation run whose names now land on the same API-surface
+    collection name is a GENERATION ERROR, not a silent collision.** `Address` + `Addresses`
+    (or `Order` + `Orders`) both resolve to `/addresses` / `/orders` once an already-plural
+    name stops doubling — before this fix they did not collide (`Addresses` doubled to
+    `addresseses`). Every port now refuses such a model outright, before any generator
+    runs, naming both entities and the colliding name; rename one entity to proceed. New
+    cross-port fixture corpus `fixtures/naming-conformance/` carries both the already-plural
+    cases and the expected-collision cases, run by every port.
+
+  Fixing the doubling also surfaced two further, narrower defects it was incidentally
+  masking: a TypeScript already-plural entity's generated Drizzle collection variable name
+  could collide with its own singular row variable in the same statement (`const [x] =
+  await db.insert(x)...`, a TDZ compile error) — the colliding local variable now gets a
+  `Row` suffix only in that exact case; and a C# already-plural entity's own `DbSet`
+  property name could collide with its own entity TYPE name inside `OnModelCreating` (C#
+  resolves a bare same-named reference to the DbSet member before the type, the same
   shadowing class as the pre-existing `Address`/`Addresses` cross-entity hazard) — the
   TPH-discriminator and int-backed-enum nested-type references are now `global::`-qualified
-  when (and only when) the owning entity's name is itself already-plural. New cross-port
-  fixture corpus `fixtures/naming-conformance/` proves all five ports agree on both the
-  API-surface and frozen-legacy pluralizers for the same input set.
+  when, and only when, the owning entity's name is itself already-plural.
 
 - **Kotlin: two pre-existing generated-controller compile defects, found extending the
   `exposedApi=1` controller-tier compile check.** Both were excluded (not fixed) when that

fixtures/naming-conformance/README.md

@@ -93,9 +93,9 @@ Each port's existing naming unit-test file reads this JSON and asserts both
 | Port | Test file |
 |---|---|
 | TypeScript | `server/typescript/packages/metadata/test/naming.test.ts` (pluralizers); `server/typescript/packages/codegen-ts/test/naming/collection-name-collision.test.ts` (refusal — `assertNoCollectionNameCollisions`, wired into `runGen` in `runner.ts`) |
-| C# | `server/csharp/MetaObjects.Codegen.Tests/CSharpNamingTests.cs` (pluralizers); `server/csharp/MetaObjects.Codegen.Tests/DbContextForeignKeyConfigTests.cs` (refusal — the historical Address/Addresses fixture, now an expected-error test) |
-| Java / Kotlin | `server/java/codegen-base/src/test/java/com/metaobjects/generator/util/RouteNamingTest.java` (pluralizers; Kotlin inherits — `KotlinNaming.collectionSegment` delegates to the same `RouteNaming.pluralize`) |
-| Python | `server/python/tests/codegen/test_route_path_naming.py` (pluralizers) |
+| C# | `server/csharp/MetaObjects.Codegen.Tests/CSharpNamingTests.cs` (pluralizers + refusal — `CSharpNaming.AssertNoCollectionNameCollisions`, wired into `CodegenRunner.Run`); `server/csharp/MetaObjects.Codegen.Tests/DbContextForeignKeyConfigTests.cs` (the historical Address/Addresses fixture, now an expected-error test at both the unit and `CodegenRunner.Run` integration level) |
+| Java / Kotlin | `server/java/codegen-base/src/test/java/com/metaobjects/generator/util/RouteNamingTest.java` (pluralizers + refusal — `RouteNaming.assertNoCollectionNameCollisions`, wired into `MetaDataGeneratorMojo#executeGenerators`; Kotlin inherits both — it runs through the same Maven goal) |
+| Python | `server/python/tests/codegen/test_route_path_naming.py` (pluralizers); `server/python/tests/codegen/test_collection_name_collision.py` (refusal — `assert_no_collection_name_collisions`, wired into `run_gen` in `runner.py`) |
 
 No HTTP server, no database — this corpus is intentionally a pure function
 check, unlike `api-contract-conformance` (which is the right place for the