feat(metadata): FR-016 canonical-serializer per-kind rewrite

Adds the round-trip canonicalization promised in FR-016: when a source.rdb
on input uses the pre-1.0 legacy @table spelling with a non-table @kind, the
canonical-serializer output renames the attr key to the kind-matching alias
(@view / @MaterializedView / @proc / @function). This pins per-kind naming
as the on-disk conformance contract.

Implementation: a post-parse pre-sort pass in canonicalSerialize and
canonicalSerializeEffective that walks the parsed JSON tree, finds source.rdb
node wrappers, and rewrites @table → kind-matching alias in place when the
canonical alias is set on the source's effective @kind. Idempotent; a no-op
for inputs already in canonical form (@table with @kind: "table" is preserved).

6 new behavior tests in fr016-source-name-and-kind-aliases.test.ts cover the
four non-table kinds, the canonical no-op case, and an already-canonical
@view round-trip. Full metadata suite: 1372 pass / 0 fail.

This closes the last metadata-side piece of FR-016 (the loader accepts +
warns on legacy; the serializer auto-canonicalizes on round-trip). What
remains for this workstream:
- 9 dedicated FR-016 conformance fixtures (formalize the legacy-rewrite +
  per-kind matrix in the cross-port corpus).
- Generator-stack sweep (codegen-ts / runtime-ts / codegen-spring /
  codegen-kotlin) to use MetaSource.physicalName instead of reading @table.
- Per-port fan-out (Java / Kotlin / C# / Python) for the alias registration
  + the canonical-serializer rewrite.

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

Author: dmealing

server/typescript/packages/metadata/src/serializer-json.ts

@@ -25,6 +25,16 @@ import {
   ATTR_SUBTYPE_BOOLEAN,
   ATTR_SUBTYPE_STRINGARRAY,
 } from "./core/attr/attr-constants.js";
+import {
+  SOURCE_SUBTYPE_RDB,
+  SOURCE_ATTR_KIND,
+  SOURCE_ATTR_TABLE,
+  DEFAULT_SOURCE_KIND,
+  PHYSICAL_NAME_ATTR_BY_KIND,
+} from "./persistence/source/source-constants.js";
+import { TYPE_SOURCE } from "./shared/base-types.js";
+
+const SOURCE_RDB_FUSED_KEY = `${TYPE_SOURCE}${TYPE_SUBTYPE_SEPARATOR}${SOURCE_SUBTYPE_RDB}`;
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -153,6 +163,10 @@ export function canonicalSerialize(model: MetaData): string {
   const raw = serializeJson(model, { indent: 2 });
 
   const parsed = JSON.parse(raw) as unknown;
+  // FR-016 / ADR-0018: rewrite legacy @table → kind-matching alias on source.rdb
+  // wrappers (run before alphabetical sort so the rewritten key sorts in its
+  // canonical position).
+  rewriteSourceRdbPhysicalNames(parsed);
   const sorted = sortAttrKeys(parsed);
   const out = JSON.stringify(sorted, null, 2);
 
@@ -170,12 +184,48 @@ export function canonicalSerializeEffective(model: MetaData): string {
   const raw = JSON.stringify(nodeObj, null, 2);
 
   const parsed = JSON.parse(raw) as unknown;
+  rewriteSourceRdbPhysicalNames(parsed);
   const sorted = sortAttrKeys(parsed);
   const out = JSON.stringify(sorted, null, 2);
 
   return out + "\n";
 }
 
+/**
+ * FR-016 / ADR-0018 — when a source.rdb wrapper carries @table with a non-table
+ * @kind (the pre-1.0 legacy spelling), rewrite the attr key in place to the
+ * kind-matching alias (@view / @materializedView / @proc / @function). Mutates
+ * the parsed JSON in place; idempotent and a no-op for canonical inputs.
+ */
+function rewriteSourceRdbPhysicalNames(value: unknown): void {
+  if (Array.isArray(value)) {
+    for (const item of value) rewriteSourceRdbPhysicalNames(item);
+    return;
+  }
+  if (value === null || typeof value !== "object") return;
+
+  const obj = value as Record<string, unknown>;
+  const rdbBody = obj[SOURCE_RDB_FUSED_KEY];
+  if (rdbBody !== undefined && rdbBody !== null && typeof rdbBody === "object" && !Array.isArray(rdbBody)) {
+    const body = rdbBody as Record<string, unknown>;
+    const kindRaw = body[`${ATTR_PREFIX}${SOURCE_ATTR_KIND}`];
+    const kind = typeof kindRaw === "string" && kindRaw !== "" ? kindRaw : DEFAULT_SOURCE_KIND;
+    const canonical = PHYSICAL_NAME_ATTR_BY_KIND.get(kind);
+    if (canonical !== undefined && canonical !== SOURCE_ATTR_TABLE) {
+      const legacyKey = `${ATTR_PREFIX}${SOURCE_ATTR_TABLE}`;
+      const canonicalKey = `${ATTR_PREFIX}${canonical}`;
+      const legacyValue = body[legacyKey];
+      if (legacyValue !== undefined && body[canonicalKey] === undefined) {
+        body[canonicalKey] = legacyValue;
+        delete body[legacyKey];
+      }
+    }
+  }
+
+  // Recurse through every value (in particular `children`).
+  for (const v of Object.values(obj)) rewriteSourceRdbPhysicalNames(v);
+}
+
 function sortAttrKeys(value: unknown): unknown {
   if (Array.isArray(value)) {
     return value.map(sortAttrKeys);

server/typescript/packages/metadata/test/fr016-source-name-and-kind-aliases.test.ts

@@ -292,3 +292,63 @@ describe("FR-016 loader validation", () => {
       .not.toContain("WARN_LEGACY_PHYSICAL_NAME_ALIAS");
   });
 });
+
+describe("FR-016 canonical-serializer rewrite (legacy @table → kind-matching alias)", () => {
+  test("input @kind: view + @table → output @kind: view + @view", async () => {
+    const { canonicalSerialize } = await import("../src/serializer-json.js");
+    const { root } = await load(
+      oneSourceEntity("OldStyleView", { "@kind": "view", "@table": "v_old" }),
+    );
+    const out = canonicalSerialize(root);
+    expect(out).toContain("\"@view\": \"v_old\"");
+    expect(out).not.toContain("\"@table\": \"v_old\"");
+  });
+
+  test("input @kind: storedProc + @table → output @kind: storedProc + @proc", async () => {
+    const { canonicalSerialize } = await import("../src/serializer-json.js");
+    const { root } = await load(
+      oneSourceEntity("OldStyleProc", { "@kind": "storedProc", "@table": "fn_x" }),
+    );
+    const out = canonicalSerialize(root);
+    expect(out).toContain("\"@proc\": \"fn_x\"");
+    expect(out).not.toContain("\"@table\": \"fn_x\"");
+  });
+
+  test("input @kind: materializedView + @table → output @kind: materializedView + @materializedView", async () => {
+    const { canonicalSerialize } = await import("../src/serializer-json.js");
+    const { root } = await load(
+      oneSourceEntity("OldStyleMV", { "@kind": "materializedView", "@table": "mv_x" }),
+    );
+    const out = canonicalSerialize(root);
+    expect(out).toContain("\"@materializedView\": \"mv_x\"");
+    expect(out).not.toContain("\"@table\": \"mv_x\"");
+  });
+
+  test("input @kind: tableFunction + @table → output @kind: tableFunction + @function", async () => {
+    const { canonicalSerialize } = await import("../src/serializer-json.js");
+    const { root } = await load(
+      oneSourceEntity("OldStyleFn", { "@kind": "tableFunction", "@table": "fn_list" }),
+    );
+    const out = canonicalSerialize(root);
+    expect(out).toContain("\"@function\": \"fn_list\"");
+    expect(out).not.toContain("\"@table\": \"fn_list\"");
+  });
+
+  test("input @kind: table + @table stays @table on output (no rewrite for the canonical case)", async () => {
+    const { canonicalSerialize } = await import("../src/serializer-json.js");
+    const { root } = await load(
+      oneSourceEntity("Customer", { "@table": "customers" }),
+    );
+    const out = canonicalSerialize(root);
+    expect(out).toContain("\"@table\": \"customers\"");
+  });
+
+  test("input @kind: view + @view (already canonical) round-trips unchanged", async () => {
+    const { canonicalSerialize } = await import("../src/serializer-json.js");
+    const { root } = await load(
+      oneSourceEntity("CustomerSummary", { "@kind": "view", "@view": "v_summary" }),
+    );
+    const out = canonicalSerialize(root);
+    expect(out).toContain("\"@view\": \"v_summary\"");
+  });
+});