feat(tables): add reference columns

[j15z]

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

• simstudioai/mothership#503

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.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
docs	Skipped		Sep 16, 2026 3:13am UTC

[greptile-apps]

Greptile Summary

This PR adds workspace-scoped Reference table columns while preserving compatibility when the feature is disabled.

• Adds Reference metadata, validation, persistence, import, mutation, and undo support.
• Adds feature-gated configuration, navigation, row-ID copying, and server-side enforcement.
• Keeps public OpenAPI output hidden while retaining runtime contract compatibility.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/table/column-types/registry.server.ts	Adds workspace and active-table validation for Reference targets while intentionally preserving metadata across target archival.
apps/sim/lib/table/columns/service.ts	Integrates Reference metadata and feature-gate enforcement into column creation and mutation paths.
apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/column-config-sidebar/column-config-sidebar.tsx	Adds feature-gated Reference target configuration for column creation and editing.
apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/table-grid.tsx	Wires Reference-column row-ID copying and navigation without changing the inherited rename undo path.
apps/sim/hooks/use-table-undo.ts	Preserves Reference, select, and currency metadata when deleted columns are restored.
scripts/openapi/generator.ts	Keeps Reference fields available to runtime contracts while excluding them from generated public OpenAPI output.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  UI[Table column UI] -->|create or update Reference| API[Table columns API]
  API --> Gate[Reference feature gate]
  Gate --> Validation[Workspace and active-target validation]
  Validation --> Persistence[Column schema persistence]
  Persistence --> Grid[Reference cells in table grid]
  Grid -->|copy row ID| Clipboard[Clipboard]
  Grid -->|navigate| Target[Referenced table]

Loading

_{Reviews (4): Last reviewed commit: "fix(tables): keep reference navigation a..." | Re-trigger Greptile}

[cubic-dev-ai]

No issues found across 42 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>

[j15z]

@greptile

[j15z]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@j15z I have started the AI code review. It will take a few minutes to complete.

[j15z]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@j15z I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

All reported issues were addressed across 56 files

_{Fix all with cubic | Re-trigger cubic}

[cubic-dev-ai]

@cubic-dev-ai review this PR

@j15z I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 58 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>You've manually re-run cubic several times on this PR. Each manual re-review checks the full PR again and counts toward your usage quota. To preserve your usage limits, we recommend letting cubic automatically review new commits.

Re-trigger cubic</sub>

[github-actions]

⚠️ Cross-repo companion check

One or more companion PRs aren't merged into staging yet. Merging this without them will leave copilot and sim out of sync — merge them in lockstep.

• ❌ simstudioai/mothership#503 — OPEN, not merged (targets staging) — feat(tables): expose reference columns to copilot