fix(database): keep package models out of the migration generator's scope (#2428)

#2427 merged package models into the set the generator diffs, which is the
wrong side of the framework. A package owns its tables through the hand-written
SQL it ships, so a package model in scope means `generate:migrations` emits a
second CREATE TABLE for a table that already has one.

That duplicate is not inert. `preprocessSqliteMigrations` prunes duplicate
create-table files by keeping the earliest filename and calling
`deleteMigration()` on the rest, and once package migrations are staged into
the corpus the file it deletes can be the package's own. The plan's one
standing constraint on this work is that the generator must never delete a
package's migration, and the merged version walked straight into it.

Package models now report through `excludedTables` instead, which already
means "something else owns this table" and already feeds `protectedTables`, so
the generator knows the table exists and has no authority to drop it. That is
the same mechanism excluded framework defaults use, for the same reason.

The collision guards are unchanged and still worth having: two packages
shipping one model name, or a package shipping a model the framework owns,
both still stop the run.

Being a global is a separate question this does not answer. A package model is
still absent from `globalThis`, because that comes from the auto-import barrel
in @stacksjs/server rather than from here. That wiring is its own change, and
it carries its own hazards: discovery runs after the barrel is built on boot,
and the barrel's staleness check is mtime-based, which a package manager
preserving tarball mtimes will not trip.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: glennmichael123

storage/framework/core/database/src/model-sources.ts

@@ -317,7 +317,7 @@ export function resolveModelSources(options: {
 
   assertPackageModelsAreUsable(packaged, framework)
 
-  if (user.length === 0 && framework.length === 0 && packaged.length === 0)
+  if (user.length === 0 && framework.length === 0)
     return null
 
   const merge = options.includeFrameworkDefaults ?? shouldIncludeFrameworkDefaults()
@@ -345,26 +345,32 @@ export function resolveModelSources(options: {
       shadowed.push({ name: model.name, userFile: model.file, frameworkFile: replaced.file })
   }
 
-  // Precedence, lowest to highest: framework defaults, then packages, then
-  // userland. A package's models are MERGED rather than treated as a fallback,
-  // because an application that installed the package asked for its schema.
-  // Userland still wins over both, which is how an app customises either.
+  // Packages are deliberately NOT here. A package owns its tables through the
+  // hand-written SQL it ships, so putting its models in the generator's scope
+  // would emit a second CREATE TABLE for each one. Those duplicates then meet
+  // the earliest-filename-wins pruning in `preprocessSqliteMigrations`, which
+  // deletes the loser - and the loser can be the package's own file, which is
+  // the one thing a package's migrations must never suffer.
+  //
+  // They are reported through `excludedTables` instead, so the generator knows
+  // those tables exist and has no authority to drop them. Being a global is a
+  // separate question, answered by the auto-import barrel rather than here.
   const byName = new Map<string, ModelSource>()
   for (const model of contributing) byName.set(model.name, model)
-  for (const model of packaged) byName.set(model.name, model)
   for (const model of user) byName.set(model.name, model)
 
   const models = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name))
 
   const roots: string[] = []
   if (user.length > 0)
     roots.push(userRoot)
-  for (const root of new Set(packaged.map(model => model.file.replace(/\/[^/]+$/, ''))))
-    roots.push(root)
   if (contributing.length > 0)
     roots.push(frameworkRoot)
 
-  const excludedTables = [...new Set(excluded.map(declaredTableName))].sort()
+  // A package's tables are out of the generator's scope for the same reason an
+  // excluded framework default's are: something else owns them, and "not mine
+  // to generate" is not "safe to drop".
+  const excludedTables = [...new Set([...excluded, ...packaged].map(declaredTableName))].sort()
 
   // Fast path: a single root whose models are all top level needs no staging,
   // so the common userland-only project keeps reading its own directory.

storage/framework/core/database/tests/package-models.test.ts

@@ -98,7 +98,7 @@ describe('package model roots', () => {
 })
 
 describe('resolving models with packages installed', () => {
-  test('a package contributes its models alongside the application own', () => {
+  test('a package model stays OUT of the generator scope, and its table is protected', () => {
     const root = project()
     try {
       const userRoot = models(join(root, 'app/Models'), ['Post'])
@@ -111,14 +111,18 @@ describe('resolving models with packages installed', () => {
         packageRoots: [{ package: 'loghq', dir: pkg }],
       })
 
-      // Userland has models, so the framework defaults stay out (#2220). The
-      // package's models come in regardless, because the app asked for them.
-      expect(resolved?.models.map(m => m.name).sort()).toEqual(['LogEntry', 'Post'])
+      // The package owns log_entries through the SQL it ships, so generating a
+      // second CREATE TABLE for it would produce a duplicate that the pruning
+      // resolves by deleting a file, possibly the package's own.
+      expect(resolved?.models.map(m => m.name).sort()).toEqual(['Post'])
+
+      // But the generator must know the table exists, or it proposes a DROP.
+      expect(resolved?.excludedTables).toContain('log_entries')
     }
     finally { rmSync(root, { recursive: true, force: true }) }
   })
 
-  test('userland still overrides a model a package shipped', () => {
+  test('a userland model of the same name is the one that generates', () => {
     const root = project()
     try {
       const userRoot = models(join(root, 'app/Models'), ['LogEntry'])
@@ -154,7 +158,8 @@ describe('resolving models with packages installed', () => {
       // A package bringing models is not the app having models of its own, so
       // the defaults still stand in. Removing them here would take User away
       // from a fresh app the moment it installed anything.
-      expect(resolved?.models.map(m => m.name).sort()).toEqual(['LogEntry', 'User'])
+      expect(resolved?.models.map(m => m.name).sort()).toEqual(['User'])
+      expect(resolved?.excludedTables).toContain('log_entries')
     }
     finally { rmSync(root, { recursive: true, force: true }) }
   })