glm-5.1
2b63cda1c7
Copy architecture docs, ADRs, storage domain specs, research, reviews, and 56 storage architecture tasks from the alkhub_ts monorepo. Adapt for standalone @alkdev/hub repo structure (src/ not packages/hub/). Sanitize all sensitive information: - Replace private IPs (10.0.0.1) with localhost defaults - Remove internal server hostnames (dev1, ns528096) - Replace /workspace/ private paths with npm package references - Remove hardcoded credentials from examples - Rewrite infrastructure.md without private network details Add Deno project scaffolding: deno.json (pinned deps), .gitignore, AGENTS.md, entry point. Migrate existing code stubs (crypto, config types, logger) with updated import paths.
29 lines
1.7 KiB
Markdown
29 lines
1.7 KiB
Markdown
# 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. |