feat(tables): add reference columns

J1
2mo ago
+2811-138

Summary

Tables can now store row IDs in a Reference column configured against another table in the same workspace. The type is preserved through contracts, import, persistence, validation, and column mutation paths, while the grid provides target configuration, row-ID copying, and direct navigation to the referenced table.

The foundation now owns the global table-reference-columns AppConfig flag, with TABLE_REFERENCE_COLUMNS as the off-AppConfig fallback. When disabled, the UI hides Reference from creation and conversion choices, navigation is unavailable, and server services reject creation, conversion, and retargeting. Existing Reference columns and cell values remain readable, writable, renamable, convertible away, and deletable for rollout safety.

Deleted columns retain explicit select, currency, and Reference metadata so undo restores each column without changing its meaning.

User-facing documentation is deferred until the feature is ready to roll out. Runtime contracts continue to accept Reference fields for compatibility, while the generated public OpenAPI omits both the reference enum value and referenceTableId.

Stack

This is the foundation layer of the Reference-row stack. #7106 adds inline referenced-row inspection and reuses this flag for preview fetching and rendering. #7390 contains the general column configuration and rename UX split out of this PR. The existing edit-sidebar rename path intentionally remains here so #7390 owns the complete sidebar-to-header rename migration.

Type of Change

  • Bug fix
  • New feature
  • Breaking change

Testing

  • bun run --cwd apps/sim type-check
  • bun run check:api-validation
  • bun run check:cli-api
  • bun run check:openapi (147 tests and 216 contracts cross-checked)
  • 7 focused flag, service, route, host-context, and sidebar/dropdown test files: 76 passing tests

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added or updated and passing
  • No new warnings introduced
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement

Screenshots/Videos

Not attached. The create, configure, copy-row-ID, and reference-navigation flows were exercised locally.

Post-Deploy Monitoring & Validation

  • No user-visible runtime change is expected while TABLE_REFERENCE_COLUMNS is disabled.
  • After enabling it, search application logs for Error updating column in table and Failed to update column.
  • Watch error rates for PATCH /api/table/:tableId/columns and table row writes during the first 24 hours of flag exposure.
  • Healthy signals: Reference columns can be created and retargeted, stored row IDs survive reloads and column renames, and undo restores select, currency, and Reference metadata.
  • Failure signals: elevated column-mutation errors, lost referenceTableId, or restored columns changing type/metadata. Disable TABLE_REFERENCE_COLUMNS and roll back the foundation change if these appear.
  • Validation owner: Tables team during the first 24 hours after flag enablement.

Companion PRs

The generated tool-catalog-v1.ts / tool-schemas-v1.ts in this PR are produced from the
contract on that branch — regenerating from it reproduces them byte for byte. These need to
land in lockstep.