feat(server): Entity Expose API — unified field, filter, sort & relation control

[viniciusdacal]

Summary

• Replaces the old relations config on entities with a unified expose config that controls the entire VertzQL query surface
• expose.select restricts which fields appear in API responses (with AccessRule descriptor support for conditional visibility)
• expose.allowWhere / expose.allowOrderBy restrict which fields clients can filter/sort on
• expose.include controls relation exposure with fractal structure mirroring the DB query API
• Descriptor-guarded fields return null (not field omission) — typed as T | null in the SDK
• Full documentation page at guides/server/entity-exposure

Public API Changes

Breaking (pre-v1)

• EntityConfig.relations → removed, replaced by EntityConfig.expose
• EntityDefinition.relations → removed, replaced by EntityDefinition.expose

Additions

• ExposeConfig<TTable, TModel> — top-level expose configuration type
• RelationExposeConfig<R> — relation-level expose with fractal structure
• ExposeValidationConfig — interface for VertzQL validation
• evaluateExposeDescriptors() — pre-evaluates AccessRule descriptors per request
• nullGuardedFields() — sets descriptor-guarded fields to null in responses
• applySelect() signature widened to Record<string, unknown>

Backwards compatible

• Entities without expose continue to work as before (all non-hidden fields exposed)
• Old include config shape ({ select: { field: true }, allowWhere, allowOrderBy }) works through expose.include

Phases

1. Core types, factory, runtime — ExposeConfig/RelationExposeConfig types, entity factory update, expose.select enforcement in CRUD pipeline, entity-level allowWhere/allowOrderBy validation in VertzQL parser
2. Descriptor runtime evaluation — evaluateExposeDescriptors() engine, nullGuardedFields(), route-generator wiring for per-request descriptor evaluation
3. Documentation — Full entity-exposure.mdx guide covering select, filters, descriptors, null semantics, fractal structure

Known limitations

• Relation-level AccessRule descriptors are not evaluated at runtime yet (entity-level only). Tracked for follow-up.

Test plan

• 381 entity tests pass (0 failures)
• Type-level tests for ExposeConfig generic inference, PublicColumnKeys, allowWhere/allowOrderBy field validity
• expose.select restricts fields across all CRUD operations (list, get, create, update)
• Entity-level allowWhere/allowOrderBy validation returns 400 for disallowed fields
• Descriptor-guarded fields return null when descriptor fails
• Evaluated descriptors override static validation for where/orderBy
• Backwards compatibility: entities without expose expose all non-hidden fields
• Server typecheck clean

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 95.86466% with 11 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/server/src/entity/expose-evaluator.ts	86.58%	11 Missing ⚠️

📢 Thoughts on this report? Let us know!