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.
1.7 KiB
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:
- Messages already have a composite index
(session_id, created_at, id)that provides efficient chronological ordering without sortable IDs. - UUIDv4 is sufficient for messages since ordering is driven by
created_at, not by ID sortability. - 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.