Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orbit-docs.devotel.io/llms.txt

Use this file to discover all available pages before exploring further.

​
ADR-015: Migration prefix discipline — five grandfathered collisions

Status: CURRENT Date: 2026-05-16

​
Context

The TENANT_MIGRATIONS array has five prefixes with duplicates (040, 041, 042, 052, 073) from out-of-order merges before the prefix-uniqueness policy tightened. Every production tenant’s per-schema _migrations table has already recorded the original ids; renaming would replay the migration and fail with relation already exists on every tenant pod restart.

​
Decision

Grandfather the five colliding prefixes via the GRANDFATHERED_PREFIXES allowlist in packages/database/src/tenant-migrations-prefix.test.ts. The test fails CI on ANY new collision outside the set AND if a grandfathered prefix stops colliding (forcing the allowlist to stay tight). New migrations: pick the next-free 3-digit prefix.

​
Reason

Cannot rename without breaking every production tenant pod restart. Preserving the historical mistake is cheaper than the alternative.

​
Consequences

  • Adding to GRANDFATHERED_PREFIXES requires sign-off — each addition relaxes invariant #24.
  • Migration 070_conversations_snoozed_until placement in PUBLIC_MIGRATIONS with a {schema} placeholder is a separate known issue (load-bearing workaround — do not “fix”).
  • Agents must check known_issues.md before any migration-cleanup task.

​
Source memos

  • known_issues.md § TENANT_MIGRATIONS prefix collisions
  • invariants.md #24
  • [[decision_tier_model_dropped_2026_05_10]] (companion migration 154 as an example of correct prefixing)