# ADR-003: Sortable IDs for parts

- **Status**: Accepted
- **Date**: 2026-04-19
- **Deciders**: alkdev

## Context

Parts must be ordered chronologically within a message. UUIDv4 from crypto.randomUUID() is not sortable. Opencode uses prefix-based sortable IDs (prt_{timestamp_hex}{random}).

## Decision

Parts use sortable timestamp-based IDs instead of commonCols.id. Enables ORDER BY id ASC for chronological ordering without a separate position column. Use a monotonic ID generator (e.g., @std/ulid or custom prefix+sortable scheme).

Messages continue to use UUIDv4 (via `commonCols.id`) and rely on the composite index `idx_messages_session_id_created_at_id` on `(session_id, created_at, id)` for ordering. This avoids changing the message ID scheme when messages already have a reliable ordering mechanism via the composite index.

## Amendment (2026-04-22)

Sortable IDs apply to the `parts` table only. Messages retain UUIDv4 from `commonCols.id` because:

1. Messages already have a composite index `(session_id, created_at, id)` that provides efficient chronological ordering without sortable IDs.
2. UUIDv4 is sufficient for messages since ordering is driven by `created_at`, not by ID sortability.
3. Changing message IDs would cascade into opencode/AI SDK compatibility layers for no ordering benefit.

Parts are the primary beneficiary of sortable IDs because they are ordered `BY id ASC` within a message, and a separate `position` column would otherwise be required.

## Consequences

Sortable IDs reveal creation timestamps (mitigated by random suffix). Slightly larger than UUIDv4. Ordering benefit outweighs both concerns. Positive: eliminates need for separate position/sort columns, natural chronological ordering. Negative: timestamp leakage and larger ID size.