---
id: resolve-message-id-adr-contradiction
name: Resolve ADR-003 vs sessions.md on message IDs
status: completed
depends_on: []
scope: narrow
risk: high
impact: component
level: implementation
---

## Description

Three-way inconsistency on message IDs:
1. **ADR-003** states: "Parts and messages tables use sortable timestamp-based IDs instead of commonCols.id"
2. **sessions.md** defines `messages` using `commonCols` (UUIDv4)
3. **table-reference.md** only mentions `parts` for sortable IDs

The composite index `idx_messages_session_id_created_at_id` on `(session_id, created_at, id)` relies on `created_at` for ordering, making UUIDv4 sortable IDs unnecessary — but this contradicts ADR-003's stated rationale.

## Decision (D2)

**Option B chosen**: Amend ADR-003 to state that only `parts` uses sortable IDs. `messages` keeps UUIDv4 and relies on the composite index for ordering.

**Rationale**:
- Composite index provides efficient ordering without requiring sortable IDs on messages
- Simpler opencode conversation import — opencode uses UUIDv4 message IDs natively
- Parts benefit more from sortable IDs (they're frequently paginated/ordered within a message)
- The `created_at` column in the composite index provides the ordering property that sortable IDs would give

## Acceptance Criteria

- [ ] ADR-003 is amended: scope sortable IDs to `parts` only, explain that `messages` uses composite index for ordering
- [ ] The `messages` table column spec in sessions.md keeps `commonCols` (UUIDv4)
- [ ] table-reference.md note on sortable IDs is updated: only `parts` uses sortable IDs, `messages` uses composite index
- [ ] The ordering rationale is explicitly stated in ADR-003 amendment
- [ ] All three sources are consistent after changes

## References

- docs/reviews/storage-architecture-review-2026-04-21.md#C02
- docs/decisions/ADR-003
- docs/decisions/storage-spec-phase1-resolutions.md#D2
- docs/architecture/storage/sessions.md:42-46
- docs/architecture/storage/table-reference.md:48

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion