Setup repo: migrate architecture specs, code stubs, and tasks from alkhub_ts
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.
This commit is contained in:
29
docs/decisions/ADR-003-sortable-ids-for-parts.md
Normal file
29
docs/decisions/ADR-003-sortable-ids-for-parts.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user