refactor(codegen+metadata): FR-016 generator-stack sweep — physicalName everywhere

Routes every codegen / runtime call site that resolves a source's physical
SQL name through MetaSource.physicalName instead of the legacy @table-only
slot accessor. With this in place, an entity declared with @kind: "view" +
@view: "v_x" (or any kind-aware alias) emits the correct physical name in
Drizzle / Kysely / view-projection / extract-view-spec output without
per-call-site special-casing.

Changes:
- packages/metadata/src/core/object/meta-object.ts — MetaObject.dbTable now
  delegates to source.physicalName (still scoped to writable + primary so
  CQRS read-side accessors don't get confused with the write target).
- packages/codegen-ts/src/projection/extract-view-spec.ts — viewName() reads
  source.physicalName instead of source.tableName, so projection sources can
  use @view (canonical) or legacy @table interchangeably.
- packages/metadata/test/meta/meta-object.test.ts — the "empty @table"
  back-compat test was asserting pre-FR-016 behavior (undefined). Post-FR-016
  the resolver falls through to step 4 (entity-name pluralize); the test
  now exercises that path explicitly and asserts "users" for entity "User".

migrate-ts equivalents (expected-schema.ts, expected-views.ts, rename-heuristic.ts)
remain on the sister plan's Task A — this commit deliberately doesn't touch them.

Pre-existing extract-codegen test failures unrelated to this change.

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

Author: dmealing

server/typescript/packages/codegen-ts/src/projection/extract-view-spec.ts

@@ -46,12 +46,20 @@ function findRelationship(obj: MetaData, name: string): MetaData | undefined {
 }
 
 function viewName(projection: MetaObject, ctx: ExtractContext): string {
-  // The read-only source carries the physical view name (@table).
+  // The read-only source carries the physical view name. FR-016: physicalName
+  // implements the four-step rule (kind-matching alias → legacy @table →
+  // source.name → entity-name fallback), so the call below correctly resolves
+  // @view / @materializedView / legacy @table for projection sources.
   const viewSource = projection.ownChildren().find(
     (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
   );
-  const explicit = viewSource?.tableName;
-  return explicit ?? viewNameFromProjection(projection.name, ctx.columnNamingStrategy);
+  const explicit = viewSource?.physicalName;
+  // physicalName always returns a string; empty string means the source had
+  // neither alias nor a name and the owning entity name was empty (impossible
+  // for a real projection). Fall through to the helper anyway for safety.
+  return explicit !== undefined && explicit !== ""
+    ? explicit
+    : viewNameFromProjection(projection.name, ctx.columnNamingStrategy);
 }
 
 /**

server/typescript/packages/metadata/src/core/object/meta-object.ts

@@ -39,12 +39,17 @@ import type { MetaValidator } from "../validator/meta-validator.js";
 export class MetaObject extends MetaData {
   get dbTable(): string | undefined {
     return this.cached("dbTable", () => {
-      // The primary writable source carries the physical table name (@table).
+      // The primary writable source carries the physical table name. FR-016:
+      // physicalName respects per-kind aliases + the four-step resolution rule.
+      // We still scope to writable + primary because dbTable is the WRITE target
+      // (CQRS read-side via dbView/dbProc is a different accessor).
       const source = this.children().find(
         (c): c is MetaSource =>
           c instanceof MetaSource && c.isWritable() && c.role === SOURCE_ROLE_PRIMARY,
       );
-      return source?.tableName;
+      if (source === undefined) return undefined;
+      const name = source.physicalName;
+      return name !== "" ? name : undefined;
     });
   }
 

server/typescript/packages/metadata/test/meta/meta-object.test.ts

@@ -104,13 +104,19 @@ describe("MetaObject.dbTable", () => {
     expect(obj.dbTable).toBeUndefined();
   });
 
-  it("returns undefined when source exists but @table is empty string", () => {
+  it("falls back to entity-name pluralization when @table is empty (FR-016 four-step rule)", () => {
+    // FR-016: empty @table is treated as absent at the resolution layer; the
+    // loader validation pass separately rejects literal "" with ERR_BAD_ATTR_VALUE.
+    // This programmatic test asserts the resolver's step-4 fallback when neither
+    // an alias nor a source.name is present.
     const obj = makeObject("User");
-    const source = new MetaSource(new TypeId(TYPE_SOURCE, SOURCE_SUBTYPE_RDB), SOURCE_SUBTYPE_RDB);
+    // Pass empty string as source.name so step 3 (source.name) doesn't apply
+    // and we cleanly exercise step 4 (entity-name pluralize).
+    const source = new MetaSource(new TypeId(TYPE_SOURCE, SOURCE_SUBTYPE_RDB), "");
     source.setAttr(SOURCE_ATTR_TABLE, "");
     obj.addChild(source);
     obj.freeze();
-    expect(obj.dbTable).toBeUndefined();
+    expect(obj.dbTable).toBe("users");
   });
 });