feat!: Entity.field — flags live on the fields, options shrink to computed and invariants

[btravers]

Field modifiers move onto the fields that carry them, and the options object shrinks to the two things that are genuinely not field-shaped:

class Organization extends Entity("Organization")(
  {
    id:        Entity.field(OrgId, { generated: true, immutable: true }),
    createdAt: Entity.field(Instant, { generated: true, immutable: true }),
    slug:      Entity.field(Slug, { immutable: true }),
    name:      DisplayName,
  },
  {
    computed:   { /* inline is measured-impossible: the map would be self-referential, d → never */ },
    invariants: [ /* spans the entity, not one field */ ],
  },
) {}

The design, and the measurement that shaped it

Entity.field(schema, flags) returns a spec object the builder unwraps — never a schema impersonation, because entity classes are legal fields and make constructs through this (measured: anything standing in front of the class stops being a constructor). Fields widens to accept either shape; a SchemaOf unwrap threads through every derived type.

The emit problem was solved structurally, not fought. A spike had measured the naive shape at +57.8% consumer emitted size: GeneratedKeys<S> in type-argument position re-carries the entire field map, and de-aliasing it is measured-impossible three ways — the printer's union-origin tracking reconstitutes the alias on both compilers. The fix is arity reduction: EntityStatic<Tag, S, A, B> (was six parameters), AbstractEntity<Name, S, A>, BaseInstance<S, A>, with the key unions computed inside the bodies where S prints by name. The field map appears exactly once per emitted declaration, by construction.

Measured on the consumer fixture: baseline 23,729 B → 25,623 B = +1,894 B (+8.0%), 10 flagged fields, 21 appearances, ~90 B per appearance. Zero GeneratedKeys</ImmutableKeys< hits in any emitted .d.ts — the structural proof, checked by grep as an acceptance artifact. A mid-branch review reclaimed 874 B of that: field()'s parameter is bare T, because an OnlyNominal intersection at the inference site was measured to break zod's $ZodBranded alias preservation; the map-level check owns the nominal rejection instead (the error moves to the field-map key, pinned).

Compile-time guarantees, each pinned

mistake	what happens
unbranded schema inside Entity.field(...)	rejected at the field-map key, same named error as a bare field
misspelled flag ({ imutable: true })	TS2561 suggests the spelling
misspelled flag beside a correct one	rejected via UnknownFlagIsRejected — excess-property checking alone let this through, leaving the field silently mutable; found in review, closed, both shapes pinned
widened non-literal flag ({ generated: someBoolean })	rejected via RejectWidenedBoolean — the type said not-generated while the runtime generated; found in the final review, closed type-level after measuring it against const inference
redeclaring an inherited field on extend, flagged or not	FieldAlreadyDeclaredByTheRoot at compile time, plus a declaration-time defect naming the key and tag (Object.hasOwn, so a field legitimately named toString works — in walked the prototype chain)

Flags accumulate across extend by map union; relaxing remains inexpressible.

Breaking — four items, separately named in the changeset

1. The generated/immutable options keys are gone. Migration is mechanical: each key in a list becomes a flag on its own field. The changeset carries the table.
2. Arity changes: Entity.Static<Tag, S, A, B?> (was five), Entity.Abstract<Name, S, A> (was five), Entity.BaseInstance<S, A> (was three). Empty-case never arguments simply disappear.
3. A variant may not redeclare an inherited field, flagged or not — this breaks flag-free redeclaring variants too. Migration: declare the field once, on the root.
4. A variant can no longer flag a root-declared field. The old options accumulation allowed immutable: ["rootKey"] on a variant; a field's flags now live only at its declaration site. This fell out of composing the two design rulings and is named rather than buried.

minor, per 0.x.

Test plan

• Flag derivation drives createInput/updateInput/factories exactly as the option lists did; a flagged entity-class field still yields real instances (the make-through-this regression pin)
• Every compile-time guarantee above pinned in *.test-d.ts, with the load-bearing proofs recorded (directives flip to unused when the guard is reverted)
• Redeclaration defect pinned directly, through a behaviour-only intermediate root (discriminates the static-chain walk), and for the prototype-named-field false-positive
• examples/billing-domain fully converted; its spec untouched and green; the four-step consumer gate (emit on 7.0.2 and 5.9.3, then type-check of the emitted output on 5.9.3) green throughout
• The size table is in the conversion commit's body; the baseline was re-measured from a fresh worktree after a stale-premise catch, and a reviewer reproduced every number byte-for-byte
• format --check · lint · typecheck · test (179 package + example suites) · knip · build — green in CI order, uncached

For the reader of field.ts

Two spellings in that file are measured pins, not style: the bare T parameter (alias preservation) and the flag-rejection intersection (UnknownFlagIsRejected + RejectWidenedBoolean). Both comments say so with the numbers.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refactors the entity declaration API by moving generated/immutable modifiers from Entity(...)(fields, options) onto the fields themselves via Entity.field(schema, flags), shrinking the options object to only computed and invariants. This updates the core builder, type-level derivations (including arity reductions to protect .d.ts emit size), tests/fixtures, and documentation to match the new declaration shape.

Changes:

• Introduces Entity.field(schema, flags) (backed by a FieldSpec) and derives generated/immutable key sets from field-level flags at runtime.
• Updates type-level plumbing (Fields/Schemas split, SchemaOf unwrapping, internal key-union computation, and Entity.Static/Entity.Abstract/Entity.BaseInstance arity changes).
• Migrates examples, tests (*.spec.ts, *.test-d.ts), docs, and the changeset to the new API and breaking-change story.

Reviewed changes

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

Show a summary per file

File	Description
README.md	Updates top-level README examples/docs to field-level flags and reduced options.
packages/entity/src/types.ts	Reworks core helper types around FieldSpec, SchemaOf, and internal key-union derivation.
packages/entity/src/shape.ts	Unwraps flagged fields via schemaOf() before building the zod object shape.
packages/entity/src/index.ts	Re-exports FieldSpec for consumer declaration-emit stability.
packages/entity/src/field.ts	Adds Flags/FieldSpec and implements field() plus runtime helpers (isFieldSpec, schemaOf).
packages/entity/src/field.test-d.ts	Adds type-level guards for flags extraction, typo/widened-boolean rejection, and removed options.
packages/entity/src/field.spec.ts	Adds runtime tests proving flags drive createInput/updateInput, factories, and nested entity fields.
packages/entity/src/entity.ts	Derives generated/immutable keys from field specs; updates schema derivation and factory/update typings.
packages/entity/src/entity.test-d.ts	Migrates type-level entity tests from options-lists to field flags.
packages/entity/src/crud.spec.ts	Migrates runtime CRUD tests to field-level flags.
packages/entity/src/contract.spec.ts	Migrates contract tests to field-level flags.
packages/entity/src/computed.spec.ts	Migrates computed-field tests to field-level flags.
packages/entity/src/base.ts	Removes generated/immutable option merging; adds runtime redeclaration defect; retains computed/invariants merging.
packages/entity/src/base.test-d.ts	Updates type-level root/extend tests for flag inheritance and redeclaration rejection.
packages/entity/src/base.spec.ts	Updates runtime root/extend behavior tests for flags and redeclaration defects.
packages/entity/README.md	Updates package-level README examples and tables to reflect field-level flags.
examples/billing-domain/src/root.ts	Migrates example root entity to field flags; updates explanatory comment about arity.
examples/billing-domain/src/organization.ts	Migrates example entity to field flags; updates explanatory block comment.
examples/billing-domain/src/index.ts	Migrates example variants to field flags and removes generated/immutable option lists.
examples/billing-domain/src/emit-guards.ts	Updates emit guard types for new arities and adds Entity.FieldSpec coverage.
docs/typedoc.json	Updates excluded symbol list to reflect new internal/exported types related to field flags.
docs/tutorial/getting-started.md	Updates tutorial examples/explanations to use Entity.field and field-level flags.
docs/reference/types.md	Updates helper-type docs, declaration-emit list, and arity-change explanations for the new API.
docs/reference/schemas.md	Updates schema-member descriptions to reference field flags.
docs/reference/entry-points.md	Updates entry-point docs to describe generated/immutable as field flags.
docs/reference/declaration.md	Updates declaration reference: removes generated/immutable options, adds Entity.field section, and describes redeclaration defect.
docs/index.md	Updates homepage copy and code sample to reflect field flags and reduced options.
docs/how-to/test-domain-logic.md	Updates guidance wording from options to field flags.
docs/how-to/model-an-aggregate.md	Notes that nested entities can be flagged (e.g., immutable).
docs/how-to/http-contract.md	Updates HTTP contract guidance to reference field flags.
docs/how-to/evolve-an-entity.md	Updates evolution guidance for flag inheritance and redeclaration prohibition.
docs/examples/index.md	Updates examples overview wording to field flags.
docs/examples/billing-domain.md	Migrates billing-domain docs/examples to field flags and updated root/variant semantics.
docs/examples/billing-api.md	Updates billing API doc wording to field flags.
CLAUDE.md	Updates repository guidance to include field.ts module and new flag/arity/rules narrative.
.changeset/entity-field.md	Adds a changeset documenting the new API, migrations, arity changes, and breaking items.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.