docs(migrate-ts): make referential-actions doc claims match reality

Final-reviewer Minor findings:
- JSDoc claimed 'a test in this file guards [FkAction == REFERENTIAL_ACTIONS]
  at runtime', but no such test existed. Added it (1-line set-equality assert).
- Inline-comment the bare-name correlation assumption next to the find(): the
  corpus uses bare entity names everywhere; an FQN value would silently lose
  intent. Cross-language ports should match the same correlation rule.

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

Author: dmealing

server/typescript/packages/migrate-ts/src/referential-actions.ts

@@ -29,9 +29,10 @@ import { SetNullNotNullableError } from "./errors.js";
  *
  * The single `as FkAction` cast in normalize() is safe because REFERENTIAL_ACTIONS
  * (metadata package) and FkAction (migrate-ts/src/types.ts) are the same four-value
- * set: "cascade" | "set-null" | "restrict" | "no-action". The comment in
- * relationship-constants.ts documents this invariant; a test in this file guards it
- * at runtime.
+ * set: "cascade" | "set-null" | "restrict" | "no-action". The invariant is
+ * documented in relationship-constants.ts and enforced by both the type system
+ * (FkAction is the union literal) and a runtime-set-equality test in
+ * referential-actions.test.ts.
  */
 export function resolveReferentialActions(
   entity: MetaObject,
@@ -40,6 +41,13 @@ export function resolveReferentialActions(
   const target = ref.targetEntity;
   if (target === undefined) return { onDelete: undefined, onUpdate: undefined };
 
+  // Correlation is by exact-string match. Every fixture in the corpus uses
+  // bare entity names for @objectRef and @references (no `::`-FQN form), so
+  // bare-vs-bare matching is sufficient today. If a future author writes an
+  // FQN value on either side, this find returns undefined and both actions
+  // resolve to undefined (no clause emitted) — surfacing the mismatch as a
+  // silent loss of intent rather than a wrong action. Cross-language ports
+  // should match the same correlation rule.
   const rel = entity.relationships().find((r) => r.objectRef === target);
   if (rel === undefined) return { onDelete: undefined, onUpdate: undefined };
 

server/typescript/packages/migrate-ts/test/unit/referential-actions.test.ts

@@ -3,7 +3,19 @@ import { resolveReferentialActions } from "../../src/referential-actions.js";
 import { buildExpectedSchema } from "../../src/expected-schema.js";
 import { diff } from "../../src/diff/index.js";
 import { emit } from "../../src/emit/index.js";
-import { MetaDataLoader, InMemorySource } from "@metaobjectsdev/metadata";
+import { MetaDataLoader, InMemorySource, REFERENTIAL_ACTIONS } from "@metaobjectsdev/metadata";
+
+// Invariant referenced by the as-FkAction cast in resolveReferentialActions:
+// REFERENTIAL_ACTIONS (metadata) and FkAction (migrate-ts) MUST be the same
+// four-value kebab-case set. Tested here so a cross-package divergence is
+// caught immediately rather than silently shipping wrong DDL.
+describe("REFERENTIAL_ACTIONS / FkAction invariant", () => {
+  test("REFERENTIAL_ACTIONS is exactly the FkAction union literal set", () => {
+    expect([...REFERENTIAL_ACTIONS].sort()).toEqual(
+      ["cascade", "no-action", "restrict", "set-null"],
+    );
+  });
+});
 
 async function loadDoc(doc: unknown) {
   return new MetaDataLoader().load([new InMemorySource(JSON.stringify(doc))]);