fix: correct equality, union dispatch, schema identity and the freeze

[btravers]

Five bugs found reviewing the source. Each was reproduced before being fixed and is now pinned by a test. None needed an exotic declaration to hit — OnlyNominal admits any branded schema, freeze.ts explicitly contemplates Map/Set fields, and shape.ts blesses z.enum as nominal.

equals used JSON.stringify

Three failures, measured on the pinned zod 4.4.3:

bigint field   a.equals(b) → THREW: Do not know how to serialize a BigInt
Set field      Set(["x"]) vs Set(["totally","different"]) → equals = true
nested record  {a:1,b:2} vs {b:2,a:1} → equals = false

The bigint case is the sharpest: equals returns a bare boolean with no Result channel, so the TypeError escaped uncaught — a direct breach of the errors-as-values rule. The Set case is a false positive on identity, the worse direction. The third meant a repository reading a row back with different JSON key order reported the entity as changed.

New equal.ts compares structurally: Set/Map by contents, Date by timestamp, typed arrays and ArrayBuffer bytewise, RegExp by source and flags, nested objects key-by-key. Arrays stay order-sensitive. Its traversal mirrors freeze.ts's, so the two agree on which shapes exist.

Union discriminant assumed a single-valued literal

union.ts read .value, which only z.literal("a") has. An enum member registered under undefined:

U.input.safeParse({kind:"b",…})  → true
U.make({kind:"b",…})             → err: Invalid discriminant "b"; expected one of "a", 
U.make({id})  (no discriminant)  → routed to B, reported B's own field error
z.literal(["c","d"]) member      → THREW at union construction

Four distinct problems: the two halves of the same public API disagreed; a payload missing the discriminant was captured by whichever member held the undefined key, defeating the dispatch design the docstring describes; the message rendered that key as empty (note the trailing "a", ); and a multi-value literal threw inside a builder.

Now reads the plural accessors (.values for literals, .options for enums) and registers a member under every value it claims. A member whose discriminant yields no values registers under no key, so a malformed declaration reports Invalid discriminant rather than silently capturing traffic.

Three of the four schema members were one object

omitBy returned its argument for an empty key list, and output was input with no computed fields. For an entity with neither generated nor computed:

input === output === createInput  → true

The design rule is "contracts compose the four plain ZodObjects", so consumers key registries by schema identity — and registering the three under distinct ids kept only the last write, with z.toJSONSchema emitting one $def all three $ref'd. contract.spec.ts missed it because its fixture declares both options.

The freeze broke z.custom callers

freeze.ts promises a z.custom/z.instanceof value is left alone, citing the exact risk that "the value may still be referenced by the caller who passed it in". It wasn't: dispatch was on runtime shape, and z.custom hands the caller's reference straight back, so a plain-object one was deep-frozen and the caller's next write threw.

The runtime genuinely cannot tell a passed-through object from decoded data — only the schema can. entity.ts now computes the skip set from the field schemas (z.custom, z.instanceof and a branded z.custom all report custom; brand is type-level in zod v4 and adds no wrapper).

Verification

Full gate green: format --check, lint, typecheck (three passes), test (138 passed, up from 122), knip, build.

New tests: equal.spec.ts covers bigint / Set / Map / nested-record / array-order / Date; union.spec.ts gains enum routing, input-and-make agreement, the missing-discriminant message, and multi-value literals; contract.spec.ts gains schema distinctness and registry independence; freeze.spec.ts gains the z.custom passthrough and confirms ordinary object fields are still frozen.

Note on sequencing

Branched from main, so it does not include #25. Both touch entity.ts — in different regions (equals/omitBy here, construct/extend/options there) — so whichever merges second needs a small rebase.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes several correctness issues in the @btravstack/entity core runtime (equality, union dispatch, schema identity, and freezing behavior) and adds regression tests + documentation/changeset updates to pin the intended semantics.

Changes:

• Replace equals()’s JSON.stringify comparison with structural deep equality (deepEqual) and add coverage for bigint/Set/Map/Date/records.
• Fix union member dispatch to support enum and multi-value literal discriminants consistently across input and make.
• Ensure the four contract schema members are always distinct objects; adjust freezing to skip schema-declared passthrough (z.custom/z.instanceof) fields.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/entity/src/union.ts	Dispatch map now registers members for all discriminant values (enum + multi-literal).
packages/entity/src/union.spec.ts	Adds tests covering enum routing, input/make agreement, missing discriminant, multi-value literals.
packages/entity/src/freeze.spec.ts	Adds regression tests for z.custom passthrough and ordinary object freezing.
packages/entity/src/equal.ts	Introduces deepEqual structural equality implementation used by equals().
packages/entity/src/equal.spec.ts	Adds test coverage for structural equality across supported stored types.
packages/entity/src/entity.ts	Wires in deepEqual, fixes schema identity rebuilding, and adds schema-based passthrough freeze skipping.
packages/entity/src/contract.spec.ts	Adds tests ensuring contract schema members are distinct and registry identity is stable.
docs/reference.md	Updates equals documentation to reflect structural comparison semantics.
docs/explanation.md	Clarifies freezing behavior and schema-based passthrough skipping rationale.
CLAUDE.md	Updates architecture docs to include the new equal.ts module and freeze behavior note.
.changeset/fix-equality-union-freeze.md	Adds a patch changeset documenting the fixed bugs and behavioral corrections.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.