feat(migrate-ts): resolveReferentialActions (subtype default + explicit override + no-action omission)

Adds `resolveReferentialActions(entity, ref)` in migrate-ts — correlates a
MetaReferenceIdentity with its sibling MetaRelationship (matched on
objectRef === targetEntity) and returns the { onDelete, onUpdate } pair.
Subtype defaults: composition→cascade, aggregation→set-null,
association→restrict; onUpdate defaults to cascade. Explicit @onDelete /
@onUpdate override defaults. Normalized "no-action" → undefined to keep
expected-schema round-trip diffs clean (mirrors introspect behavior).
No correlated relationship → both undefined (preserves current no-clause behavior).
All metadata barrel exports were already present (no index.ts changes needed).
FkAction == REFERENTIAL_ACTIONS invariant confirmed: identical four-value set.
5 new unit tests; migrate-ts suite 222 pass / 0 fail; full server suite 2371 pass / 0 fail.

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

Author: dmealing

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

@@ -0,0 +1,51 @@
+import {
+  ON_DELETE_DEFAULT_BY_SUBTYPE,
+  ON_UPDATE_DEFAULT,
+  type MetaObject,
+  type MetaReferenceIdentity,
+} from "@metaobjectsdev/metadata";
+import type { FkAction } from "./types.js";
+
+/**
+ * Resolve the referential actions for a foreign key inferred from an
+ * identity.reference, by correlating it with a sibling relationship on the
+ * same entity (matched on target-entity name).
+ *
+ * - No correlated relationship → both undefined (no ON DELETE / ON UPDATE clause).
+ * - With a relationship: onDelete defaults from the relationship subtype
+ *   (composition→cascade, aggregation→set-null, association→restrict);
+ *   onUpdate defaults to "cascade". Explicit @onDelete / @onUpdate override.
+ * - Resolved "no-action" → undefined: introspection in introspect/{postgres,sqlite}.ts
+ *   omits actions when the DB value is "no-action", so the expected side does the same
+ *   to keep round-trip diffs clean.
+ *
+ * If multiple relationships target the same entity (rare), the first one is used.
+ *
+ * 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.
+ */
+export function resolveReferentialActions(
+  entity: MetaObject,
+  ref: MetaReferenceIdentity,
+): { onDelete: FkAction | undefined; onUpdate: FkAction | undefined } {
+  const target = ref.targetEntity;
+  if (target === undefined) return { onDelete: undefined, onUpdate: undefined };
+
+  const rel = entity.relationships().find((r) => r.objectRef === target);
+  if (rel === undefined) return { onDelete: undefined, onUpdate: undefined };
+
+  const onDeleteRaw = rel.onDelete ?? ON_DELETE_DEFAULT_BY_SUBTYPE[rel.subType];
+  const onUpdateRaw = rel.onUpdate ?? ON_UPDATE_DEFAULT;
+  return {
+    onDelete: normalize(onDeleteRaw),
+    onUpdate: normalize(onUpdateRaw),
+  };
+}
+
+function normalize(a: string | undefined): FkAction | undefined {
+  if (a === undefined || a === "no-action") return undefined;
+  return a as FkAction;
+}

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

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { resolveReferentialActions } from "../../src/referential-actions.js";
+import { MetaDataLoader, InMemorySource } from "@metaobjectsdev/metadata";
+
+async function loadDoc(doc: unknown) {
+  return new MetaDataLoader().load([new InMemorySource(JSON.stringify(doc))]);
+}
+
+function weekDoc(rel: Record<string, unknown> | undefined) {
+  return { "metadata.root": { package: "acme", children: [
+    { "object.entity": { name: "Program", children: [
+      { "field.long": { name: "id" } },
+      { "identity.primary": { "@fields": "id" } },
+    ] } },
+    { "object.entity": { name: "Week", children: [
+      { "field.long": { name: "id" } },
+      { "field.long": { name: "programId" } },
+      ...(rel ? [rel] : []),
+      { "identity.reference": { name: "ref_program", "@fields": ["programId"], "@references": "Program" } },
+      { "identity.primary": { "@fields": "id" } },
+    ] } },
+  ] } };
+}
+
+async function loadWeek(rel: Record<string, unknown> | undefined) {
+  const { root, errors } = await loadDoc(weekDoc(rel));
+  expect(errors).toHaveLength(0);
+  const week = root.objects().find((o) => o.name === "Week")!;
+  const ref = week.referenceIdentities()[0]!;
+  return { week, ref };
+}
+
+describe("resolveReferentialActions", () => {
+  test("composition → cascade / cascade(default)", async () => {
+    const { week, ref } = await loadWeek({
+      "relationship.composition": { name: "program", "@objectRef": "Program", "@cardinality": "one" }
+    });
+    expect(resolveReferentialActions(week, ref)).toEqual({ onDelete: "cascade", onUpdate: "cascade" });
+  });
+
+  test("aggregation → set-null / cascade(default)", async () => {
+    const { week, ref } = await loadWeek({
+      "relationship.aggregation": { name: "program", "@objectRef": "Program", "@cardinality": "one" }
+    });
+    expect(resolveReferentialActions(week, ref)).toEqual({ onDelete: "set-null", onUpdate: "cascade" });
+  });
+
+  test("association → restrict / cascade(default)", async () => {
+    const { week, ref } = await loadWeek({
+      "relationship.association": { name: "program", "@objectRef": "Program", "@cardinality": "one" }
+    });
+    expect(resolveReferentialActions(week, ref)).toEqual({ onDelete: "restrict", onUpdate: "cascade" });
+  });
+
+  test("explicit override wins; no-action normalizes to undefined", async () => {
+    const { week, ref } = await loadWeek({
+      "relationship.composition": { name: "program", "@objectRef": "Program",
+          "@onDelete": "set-null", "@onUpdate": "no-action" }
+    });
+    expect(resolveReferentialActions(week, ref)).toEqual({ onDelete: "set-null", onUpdate: undefined });
+  });
+
+  test("no correlated relationship → both undefined", async () => {
+    const { week, ref } = await loadWeek(undefined);
+    expect(resolveReferentialActions(week, ref)).toEqual({ onDelete: undefined, onUpdate: undefined });
+  });
+});