typia 13.1.1 → 13.2.0

package/native/cmd/ttsc-typia/compare_template_literal_union_transform_test.go

@@ -0,0 +1,241 @@
+package main
+
+import (
+  "os"
+  "os/exec"
+  "path/filepath"
+  "strings"
+  "testing"
+)
+
+// TestCompareTemplateLiteralUnionTransform verifies template-literal object
+// union members retain their runtime domains during equality dispatch.
+//
+// The #2225 first-match fallback must use the same structural template
+// membership decision as is and clone. Weakening both template domains to
+// `typeof string` routes valid `b_*` values through the `a_*` comparator and
+// drops `b`.
+//
+//  1. Transform direct and factory is, clone, and equals calls for a tag-free
+//     template-literal object union and the same union nested in an object.
+//  2. Prove is accepts both witnesses and clone selects the `b_*` member while
+//     preserving their different `b` values.
+//  3. Exercise equal, cross-member, invalid-discriminator, nested, literal-
+//     discriminated, non-discriminable, and non-union controls at runtime.
+func TestCompareTemplateLiteralUnionTransform(t *testing.T) {
+  project := compareTemplateLiteralUnionProject(t)
+  out, errText, code := ttscTypiaTestCapture(func() int {
+    return runTransform([]string{
+      "--cwd", project,
+      "--tsconfig", "tsconfig.json",
+      "--file", "src/main.ts",
+      "--output", "js",
+    })
+  })
+  if code != 0 {
+    t.Fatalf("compare template-literal union transform failed: code=%d stderr=\n%s", code, errText)
+  }
+  compareTemplateLiteralUnionRunRuntimeCases(t, project, out)
+}
+
+func compareTemplateLiteralUnionProject(t *testing.T) string {
+  t.Helper()
+  root := ttscTypiaTestRepoRoot(t)
+  base := filepath.Join(root, "packages", "typia", "native", ".tmp-ttsc-typia-tests")
+  if err := os.MkdirAll(base, 0o755); err != nil {
+    t.Fatalf("mkdir temp base: %v", err)
+  }
+  dir, err := os.MkdirTemp(base, "compare-template-literal-union-")
+  if err != nil {
+    t.Fatalf("create temp fixture: %v", err)
+  }
+  t.Cleanup(func() {
+    _ = os.RemoveAll(dir)
+  })
+  src := filepath.Join(dir, "src")
+  if err := os.MkdirAll(src, 0o755); err != nil {
+    t.Fatalf("mkdir fixture src: %v", err)
+  }
+  if err := os.WriteFile(filepath.Join(dir, "tsconfig.json"), []byte(compareTemplateLiteralUnionTSConfig), 0o644); err != nil {
+    t.Fatalf("write tsconfig: %v", err)
+  }
+  if err := os.WriteFile(filepath.Join(src, "main.ts"), []byte(compareTemplateLiteralUnionSource), 0o644); err != nil {
+    t.Fatalf("write source: %v", err)
+  }
+  return dir
+}
+
+func compareTemplateLiteralUnionRunRuntimeCases(t *testing.T, project string, js string) {
+  t.Helper()
+  node, err := exec.LookPath("node")
+  if err != nil {
+    t.Skip("node executable not found")
+  }
+  runtimeDir := filepath.Join(project, "runtime")
+  if err := os.MkdirAll(runtimeDir, 0o755); err != nil {
+    t.Fatalf("mkdir runtime dir: %v", err)
+  }
+  ttscTypiaTestWriteCommonRuntimeStubs(t, runtimeDir)
+  if err := os.WriteFile(filepath.Join(runtimeDir, "throw-type-guard-error-stub.cjs"), []byte(compareTemplateLiteralUnionThrowStub), 0o644); err != nil {
+    t.Fatalf("write throw stub: %v", err)
+  }
+  js = strings.ReplaceAll(js, `require("typia/lib/internal/_throwTypeGuardError")`, `require("./throw-type-guard-error-stub.cjs")`)
+  runtimeJS := ttscTypiaTestRewriteCommonJS(t, js)
+  if err := os.WriteFile(filepath.Join(runtimeDir, "main.cjs"), []byte(runtimeJS), 0o644); err != nil {
+    t.Fatalf("write runtime module: %v", err)
+  }
+  runner := filepath.Join(runtimeDir, "run.cjs")
+  if err := os.WriteFile(runner, []byte(compareTemplateLiteralUnionRuntimeRunner), 0o644); err != nil {
+    t.Fatalf("write runtime runner: %v", err)
+  }
+  cmd := exec.Command(node, runner)
+  cmd.Dir = runtimeDir
+  output, err := cmd.CombinedOutput()
+  if err != nil {
+    t.Fatalf("compare template-literal union runtime cases failed: %v\n%s", err, output)
+  }
+}
+
+const compareTemplateLiteralUnionTSConfig = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "bundler",
+    "ignoreDeprecations": "6.0",
+    "types": ["*"],
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+`
+
+const compareTemplateLiteralUnionThrowStub = `module.exports._throwTypeGuardError = (props) => {
+  const error = new Error("guard: " + props.expected);
+  error.name = "TypeGuardError";
+  throw error;
+};
+`
+
+const compareTemplateLiteralUnionSource = `import typia from "typia";
+
+type TemplateUnion =
+  | { kind: ` + "`a_${string}`" + `; common: string }
+  | { kind: ` + "`b_${string}`" + `; common: string; b?: string };
+type Nested = { value: TemplateUnion };
+
+export const isTemplate = typia.createIs<TemplateUnion>();
+export const cloneTemplate = typia.plain.createClone<TemplateUnion>();
+export const eqTemplateFactory = typia.compare.createEquals<TemplateUnion>();
+export const eqTemplateDirect = (x: TemplateUnion, y: TemplateUnion) =>
+  typia.compare.equals<TemplateUnion>(x, y);
+
+export const isNested = typia.createIs<Nested>();
+export const cloneNested = typia.plain.createClone<Nested>();
+export const eqNestedFactory = typia.compare.createEquals<Nested>();
+export const eqNestedDirect = (x: Nested, y: Nested) =>
+  typia.compare.equals<Nested>(x, y);
+
+export const eqLiteral = typia.compare.createEquals<
+  { kind: "a"; value: number } | { kind: "b"; value: string }
+>();
+export const eqOptional = typia.compare.createEquals<
+  { a?: number } | { b?: string }
+>();
+export const eqPlain = typia.compare.createEquals<{
+  kind: string;
+  common: string;
+  b?: string;
+}>();
+`
+
+const compareTemplateLiteralUnionRuntimeRunner = `const mod = require("./main.cjs");
+
+let failures = 0;
+const expect = (label, actual, expected) => {
+  if (actual !== expected) {
+    console.log("FAIL " + label + ": expected " + expected + ", got " + actual);
+    failures++;
+  }
+};
+const expectJson = (label, actual, expected) =>
+  expect(label, JSON.stringify(actual), JSON.stringify(expected));
+
+const left = { kind: "b_x", common: "same", b: "left" };
+const right = { kind: "b_x", common: "same", b: "right" };
+expect("is left b member", mod.isTemplate(left), true);
+expect("is right b member", mod.isTemplate(right), true);
+expectJson("clone left preserves b", mod.cloneTemplate(left), left);
+expectJson("clone right preserves b", mod.cloneTemplate(right), right);
+expect("factory different b", mod.eqTemplateFactory(left, right), false);
+expect("direct different b", mod.eqTemplateDirect(left, right), false);
+
+expect("factory equal b", mod.eqTemplateFactory(
+  { kind: "b_x", common: "same", b: "same" },
+  { kind: "b_x", common: "same", b: "same" },
+), true);
+expect("direct equal b", mod.eqTemplateDirect(
+  { kind: "b_x", common: "same", b: "same" },
+  { kind: "b_x", common: "same", b: "same" },
+), true);
+expect("a member different common", mod.eqTemplateFactory(
+  { kind: "a_x", common: "left" },
+  { kind: "a_x", common: "right" },
+), false);
+expect("a member equal", mod.eqTemplateFactory(
+  { kind: "a_x", common: "same" },
+  { kind: "a_x", common: "same" },
+), true);
+expect("a versus b", mod.eqTemplateFactory(
+  { kind: "a_x", common: "same" },
+  { kind: "b_x", common: "same" },
+), false);
+
+const invalidLeft = { kind: "c_x", common: "same" };
+const invalidRight = { kind: "c_x", common: "same" };
+expect("is rejects invalid discriminator", mod.isTemplate(invalidLeft), false);
+expect("factory rejects invalid discriminator", mod.eqTemplateFactory(invalidLeft, invalidRight), false);
+expect("direct rejects invalid discriminator", mod.eqTemplateDirect(invalidLeft, invalidRight), false);
+
+const nestedLeft = { value: left };
+const nestedRight = { value: right };
+expect("nested is left", mod.isNested(nestedLeft), true);
+expect("nested is right", mod.isNested(nestedRight), true);
+expectJson("nested clone left preserves b", mod.cloneNested(nestedLeft), nestedLeft);
+expectJson("nested clone right preserves b", mod.cloneNested(nestedRight), nestedRight);
+expect("nested factory different b", mod.eqNestedFactory(nestedLeft, nestedRight), false);
+expect("nested direct different b", mod.eqNestedDirect(nestedLeft, nestedRight), false);
+expect("nested factory equal b", mod.eqNestedFactory(
+  { value: { kind: "b_x", common: "same", b: "same" } },
+  { value: { kind: "b_x", common: "same", b: "same" } },
+), true);
+expect("nested invalid discriminator", mod.eqNestedFactory(
+  { value: invalidLeft },
+  { value: invalidRight },
+), false);
+
+expect("literal member different", mod.eqLiteral(
+  { kind: "a", value: 1 },
+  { kind: "a", value: 2 },
+), false);
+expect("literal cross member", mod.eqLiteral(
+  { kind: "a", value: 1 },
+  { kind: "b", value: "1" },
+), false);
+expect("optional member different", mod.eqOptional({ a: 1 }, { a: 2 }), false);
+expect("optional second payload follows first match", mod.eqOptional({ b: "left" }, { b: "right" }), true);
+expect("plain different", mod.eqPlain(
+  { kind: "b_x", common: "same", b: "left" },
+  { kind: "b_x", common: "same", b: "right" },
+), false);
+expect("plain equal", mod.eqPlain(
+  { kind: "b_x", common: "same", b: "same" },
+  { kind: "b_x", common: "same", b: "same" },
+), true);
+
+if (failures > 0) {
+  throw new Error(failures + " assertion(s) failed");
+}
+console.log("all compare template-literal union cases passed");
+`

package/native/cmd/ttsc-typia/compare_union_discrimination_transform_test.go

@@ -0,0 +1,289 @@
+package main
+
+import (
+  "os"
+  "os/exec"
+  "path/filepath"
+  "testing"
+)
+
+// TestCompareUnionDiscriminationTransform pins compare.equals over a union of
+// object types (issue #2214).
+//
+// CompareEqualProgrammer.schema assembled an object union as a flat OR of member
+// comparators (`_eo0(x,y) || _eo1(x,y) || ...`) with no discrimination. A wrong
+// member's comparator matched spuriously: its constant discriminant passed via
+// the always-prepended `x.type === y.type` branch (both agree, even when neither
+// is that member) and its absent payload keys compared `undefined === undefined`.
+// So `equals({type:"a",x:1}, {type:"a",x:2})` was `true` for two distinct
+// references. Every other object-union programmer (is/clone/classify/prune/json/
+// notations/protobuf) discriminates so a member comparator only runs for the
+// member both values actually are. `equals` must do the same: decide which member
+// each operand is, return false if they differ, and compare within the one shared
+// member — and must agree with `is` on membership.
+//
+// All fixtures compare DISTINCT references (fresh object literals) so the
+// `x === y` identity fast path never hides the flaw.
+//
+//  1. Transform is + compare.createEquals over discriminated, non-discriminated
+//     disjoint, narrower-masks-wider, 3-member, array/union-member, and nested
+//     object unions, plus primitive/array-union and non-union controls.
+//  2. Require distinct-but-different pairs to compare not-equal, distinct-but-
+//     identical pairs to compare equal, and equals to imply is on both operands.
+//  3. Require primitive/array unions and non-union objects to be unchanged.
+func TestCompareUnionDiscriminationTransform(t *testing.T) {
+  project := compareUnionDiscriminationProject(t)
+  out, errText, code := ttscTypiaTestCapture(func() int {
+    return runTransform([]string{
+      "--cwd", project,
+      "--tsconfig", "tsconfig.json",
+      "--file", "src/main.ts",
+      "--output", "js",
+    })
+  })
+  if code != 0 {
+    t.Fatalf("compare union discrimination transform failed: code=%d stderr=\n%s", code, errText)
+  }
+  compareUnionDiscriminationRunRuntimeCases(t, project, out)
+}
+
+func compareUnionDiscriminationProject(t *testing.T) string {
+  t.Helper()
+  root := ttscTypiaTestRepoRoot(t)
+  base := filepath.Join(root, "packages", "typia", "native", ".tmp-ttsc-typia-tests")
+  if err := os.MkdirAll(base, 0o755); err != nil {
+    t.Fatalf("mkdir temp base: %v", err)
+  }
+  dir, err := os.MkdirTemp(base, "compare-union-disc-")
+  if err != nil {
+    t.Fatalf("create temp fixture: %v", err)
+  }
+  t.Cleanup(func() {
+    _ = os.RemoveAll(dir)
+  })
+  src := filepath.Join(dir, "src")
+  if err := os.MkdirAll(src, 0o755); err != nil {
+    t.Fatalf("mkdir fixture src: %v", err)
+  }
+  if err := os.WriteFile(filepath.Join(dir, "tsconfig.json"), []byte(compareUnionDiscriminationTSConfig), 0o644); err != nil {
+    t.Fatalf("write tsconfig: %v", err)
+  }
+  if err := os.WriteFile(filepath.Join(src, "main.ts"), []byte(compareUnionDiscriminationSource), 0o644); err != nil {
+    t.Fatalf("write source: %v", err)
+  }
+  return dir
+}
+
+func compareUnionDiscriminationRunRuntimeCases(t *testing.T, project string, js string) {
+  t.Helper()
+  node, err := exec.LookPath("node")
+  if err != nil {
+    t.Skip("node executable not found")
+  }
+  runtimeDir := filepath.Join(project, "runtime")
+  if err := os.MkdirAll(runtimeDir, 0o755); err != nil {
+    t.Fatalf("mkdir runtime dir: %v", err)
+  }
+  ttscTypiaTestWriteCommonRuntimeStubs(t, runtimeDir)
+  runtimeJS := ttscTypiaTestRewriteCommonJS(t, js)
+  if err := os.WriteFile(filepath.Join(runtimeDir, "main.cjs"), []byte(runtimeJS), 0o644); err != nil {
+    t.Fatalf("write runtime module: %v", err)
+  }
+  runner := filepath.Join(runtimeDir, "run.cjs")
+  if err := os.WriteFile(runner, []byte(compareUnionDiscriminationRuntimeRunner), 0o644); err != nil {
+    t.Fatalf("write runtime runner: %v", err)
+  }
+  cmd := exec.Command(node, runner)
+  cmd.Dir = runtimeDir
+  output, err := cmd.CombinedOutput()
+  if err != nil {
+    t.Fatalf("compare union discrimination runtime cases failed: %v\n%s", err, output)
+  }
+}
+
+const compareUnionDiscriminationTSConfig = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "bundler",
+    "ignoreDeprecations": "6.0",
+    "types": ["*"],
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+`
+
+const compareUnionDiscriminationSource = `import typia from "typia";
+
+// 1. discriminated union
+type Disc = { type: "a"; x: number } | { type: "b"; y: string };
+export const isDisc = typia.createIs<Disc>();
+export const eqDisc = typia.compare.createEquals<Disc>();
+
+// 2. non-discriminated union with disjoint keys
+type Disjoint = { x: number } | { y: string };
+export const isDisjoint = typia.createIs<Disjoint>();
+export const eqDisjoint = typia.compare.createEquals<Disjoint>();
+
+// 3. narrower-masks-wider
+type Mask = { a: number } | { a: number; b: string };
+export const isMask = typia.createIs<Mask>();
+export const eqMask = typia.compare.createEquals<Mask>();
+
+// 4. three-member discriminated union
+type Three =
+  | { type: "a"; x: number }
+  | { type: "b"; y: string }
+  | { type: "c"; z: boolean };
+export const isThree = typia.createIs<Three>();
+export const eqThree = typia.compare.createEquals<Three>();
+
+// 5. a member whose payload is itself an array / element union
+type ArrMember =
+  | { kind: "multi"; values: (number | string)[] }
+  | { kind: "single"; value: number };
+export const isArrMember = typia.createIs<ArrMember>();
+export const eqArrMember = typia.compare.createEquals<ArrMember>();
+
+// 6. nested object-union property
+type Nested = { wrap: { type: "a"; x: number } | { type: "b"; y: string } };
+export const isNested = typia.createIs<Nested>();
+export const eqNested = typia.compare.createEquals<Nested>();
+
+// 7. recursive discriminated union (exercises _vctx capture through the IIFE)
+type Tree =
+  | { type: "leaf"; value: number }
+  | { type: "node"; left: Tree; right: Tree };
+export const isTree = typia.createIs<Tree>();
+export const eqTree = typia.compare.createEquals<Tree>();
+
+// 8. native alongside a discriminated object union (notNatives guard + ladder)
+type WithNative = Date | { kind: "a"; x: number } | { kind: "b"; y: string };
+export const eqWithNative = typia.compare.createEquals<WithNative>();
+
+// control: a native unioned with a SINGLE object keeps the flat guarded branch
+type DateOrStamp = Date | { timestamp: number };
+export const eqDateStamp = typia.compare.createEquals<DateOrStamp>();
+
+// controls: primitive union, array union, non-union object
+export const eqPrim = typia.compare.createEquals<string | number>();
+export const eqArrUnion = typia.compare.createEquals<number[] | string[]>();
+export const eqObj = typia.compare.createEquals<{ a: number; b: string }>();
+`
+
+const compareUnionDiscriminationRuntimeRunner = `const mod = require("./main.cjs");
+
+let failures = 0;
+const expect = (label, actual, expected) => {
+  if (actual !== expected) {
+    console.log("FAIL " + label + ": expected " + expected + ", got " + actual);
+    failures++;
+  }
+};
+
+// --- 1. discriminated union: {type:"a";x} | {type:"b";y} ---
+expect("disc a distinct-different", mod.eqDisc({ type: "a", x: 1 }, { type: "a", x: 2 }), false);
+expect("disc b distinct-different", mod.eqDisc({ type: "b", y: "p" }, { type: "b", y: "q" }), false);
+expect("disc a distinct-identical", mod.eqDisc({ type: "a", x: 1 }, { type: "a", x: 1 }), true);
+expect("disc b distinct-identical", mod.eqDisc({ type: "b", y: "p" }, { type: "b", y: "p" }), true);
+expect("disc cross-arm a vs b", mod.eqDisc({ type: "a", x: 1 }, { type: "b", y: "p" }), false);
+
+// --- 2. non-discriminated disjoint keys: {x} | {y} ---
+expect("disjoint x distinct-different", mod.eqDisjoint({ x: 1 }, { x: 2 }), false);
+expect("disjoint y distinct-different", mod.eqDisjoint({ y: "p" }, { y: "q" }), false);
+expect("disjoint x distinct-identical", mod.eqDisjoint({ x: 1 }, { x: 1 }), true);
+expect("disjoint cross-arm x vs y", mod.eqDisjoint({ x: 1 }, { y: "p" }), false);
+
+// --- 3. narrower-masks-wider: {a} | {a,b} ---
+expect("mask wider distinct-different", mod.eqMask({ a: 1, b: "x" }, { a: 1, b: "y" }), false);
+expect("mask narrower distinct-identical", mod.eqMask({ a: 1 }, { a: 1 }), true);
+expect("mask wider distinct-identical", mod.eqMask({ a: 1, b: "x" }, { a: 1, b: "x" }), true);
+expect("mask narrower vs wider", mod.eqMask({ a: 1 }, { a: 1, b: "x" }), false);
+
+// --- 4. three-member ---
+expect("three a-different", mod.eqThree({ type: "a", x: 1 }, { type: "a", x: 2 }), false);
+expect("three b-different", mod.eqThree({ type: "b", y: "p" }, { type: "b", y: "q" }), false);
+expect("three c-different", mod.eqThree({ type: "c", z: true }, { type: "c", z: false }), false);
+expect("three c-identical", mod.eqThree({ type: "c", z: true }, { type: "c", z: true }), true);
+expect("three cross a vs c", mod.eqThree({ type: "a", x: 1 }, { type: "c", z: true }), false);
+
+// --- 5. array/element-union member ---
+expect("arrmember multi different length", mod.eqArrMember({ kind: "multi", values: [1, 2] }, { kind: "multi", values: [1] }), false);
+expect("arrmember multi different elem", mod.eqArrMember({ kind: "multi", values: [1, "a"] }, { kind: "multi", values: [1, "b"] }), false);
+expect("arrmember multi identical", mod.eqArrMember({ kind: "multi", values: [1, "a"] }, { kind: "multi", values: [1, "a"] }), true);
+expect("arrmember single different", mod.eqArrMember({ kind: "single", value: 1 }, { kind: "single", value: 2 }), false);
+expect("arrmember cross multi vs single", mod.eqArrMember({ kind: "multi", values: [1] }, { kind: "single", value: 1 }), false);
+
+// --- 6. nested object-union property ---
+expect("nested inner different", mod.eqNested({ wrap: { type: "a", x: 1 } }, { wrap: { type: "a", x: 2 } }), false);
+expect("nested inner identical", mod.eqNested({ wrap: { type: "a", x: 1 } }, { wrap: { type: "a", x: 1 } }), true);
+expect("nested cross arm", mod.eqNested({ wrap: { type: "a", x: 1 } }, { wrap: { type: "b", y: "p" } }), false);
+
+// --- controls: primitive / array unions, non-union object ---
+expect("prim number-different", mod.eqPrim(1, 2), false);
+expect("prim string-identical", mod.eqPrim("x", "x"), true);
+expect("prim cross string vs number", mod.eqPrim("1", 1), false);
+expect("arrunion number-different", mod.eqArrUnion([1, 2], [1, 3]), false);
+expect("arrunion number-identical", mod.eqArrUnion([1, 2], [1, 2]), true);
+expect("arrunion string-identical", mod.eqArrUnion(["a"], ["a"]), true);
+expect("obj different", mod.eqObj({ a: 1, b: "x" }, { a: 1, b: "y" }), false);
+expect("obj identical", mod.eqObj({ a: 1, b: "x" }, { a: 1, b: "x" }), true);
+
+// --- recursive discriminated union (distinct references throughout) ---
+const mkTree = () => ({ type: "node", left: { type: "leaf", value: 1 }, right: { type: "leaf", value: 2 } });
+expect("tree identical", mod.eqTree(mkTree(), mkTree()), true);
+expect("tree leaf value differs", mod.eqTree({ type: "leaf", value: 1 }, { type: "leaf", value: 2 }), false);
+expect("tree deep differs", mod.eqTree(mkTree(), { type: "node", left: { type: "leaf", value: 1 }, right: { type: "leaf", value: 9 } }), false);
+expect("tree leaf vs node", mod.eqTree({ type: "leaf", value: 1 }, mkTree()), false);
+expect("tree shape differs", mod.eqTree({ type: "node", left: { type: "leaf", value: 1 }, right: { type: "leaf", value: 2 } }, { type: "node", left: { type: "leaf", value: 1 }, right: { type: "node", left: { type: "leaf", value: 2 }, right: { type: "leaf", value: 3 } } }), false);
+
+// --- native alongside a discriminated object union ---
+expect("withnative same date", mod.eqWithNative(new Date(0), new Date(0)), true);
+expect("withnative diff date", mod.eqWithNative(new Date(0), new Date(5000)), false);
+expect("withnative obj a different", mod.eqWithNative({ kind: "a", x: 1 }, { kind: "a", x: 2 }), false);
+expect("withnative obj a identical", mod.eqWithNative({ kind: "a", x: 1 }, { kind: "a", x: 1 }), true);
+expect("withnative date vs obj", mod.eqWithNative(new Date(0), { kind: "a", x: 1 }), false);
+expect("withnative cross arm", mod.eqWithNative({ kind: "a", x: 1 }, { kind: "b", y: "p" }), false);
+
+// --- native unioned with a single object (control) ---
+expect("datestamp same date", mod.eqDateStamp(new Date(0), new Date(0)), true);
+expect("datestamp diff date", mod.eqDateStamp(new Date(0), new Date(5000)), false);
+expect("datestamp stamp identical", mod.eqDateStamp({ timestamp: 5 }, { timestamp: 5 }), true);
+expect("datestamp stamp different", mod.eqDateStamp({ timestamp: 5 }, { timestamp: 9 }), false);
+expect("datestamp date vs stamp", mod.eqDateStamp(new Date(0), { timestamp: 0 }), false);
+
+// --- equals must imply is on both operands (agree with is) ---
+const discSamples = [
+  { type: "a", x: 1 }, { type: "a", x: 2 }, { type: "b", y: "p" }, { type: "b", y: "q" },
+];
+for (const a of discSamples)
+  for (const b of discSamples) {
+    // fresh distinct references
+    const x = JSON.parse(JSON.stringify(a));
+    const y = JSON.parse(JSON.stringify(b));
+    if (mod.eqDisc(x, y)) {
+      expect("agree-is disc lhs " + JSON.stringify(a), mod.isDisc(x), true);
+      expect("agree-is disc rhs " + JSON.stringify(b), mod.isDisc(y), true);
+      // equal implies structurally same JSON
+      expect("equal implies same json " + JSON.stringify(a) + "|" + JSON.stringify(b), JSON.stringify(x) === JSON.stringify(y), true);
+    }
+  }
+
+const maskSamples = [{ a: 1 }, { a: 1, b: "x" }, { a: 1, b: "y" }, { a: 2 }];
+for (const a of maskSamples)
+  for (const b of maskSamples) {
+    const x = JSON.parse(JSON.stringify(a));
+    const y = JSON.parse(JSON.stringify(b));
+    if (mod.eqMask(x, y)) {
+      expect("agree-is mask same json " + JSON.stringify(a) + "|" + JSON.stringify(b), JSON.stringify(x) === JSON.stringify(y), true);
+    }
+  }
+
+if (failures > 0) {
+  throw new Error(failures + " assertion(s) failed");
+}
+console.log("all compare-union-discrimination cases passed");
+`