alkdev/hub
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Setup repo: migrate architecture specs, code stubs, and tasks from alkhub_ts

Browse Source 
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:
glm-5.1
2026-05-25 10:56:32 +00:00
parent 3e3f12d2d5
commit 2b63cda1c7
120 changed files with 11714 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
docs/architecture/storage/coordination.md Normal file
View File

@@ -0,0 +1,54 @@
---
status: draft
last_updated: 2026-04-19
---
# Table Schemas: Coordination
Mapping and detection tables for coordinator operations. For cross-cutting reference (cascade behavior, index reference, status enums, relations), see [table-reference.md](./table-reference.md). For design decisions, see [../../../decisions/](../../../decisions/). For coordination architecture, see [../../coordination.md](../../coordination.md).
### `mappings`
Worktree/session/spoke relationships. Links spawned sessions to their parent coordinator, the spoke they're running on, and the git branch. This is the coordination table that drives `coord.spawn`, `coord.status`, `coord.message`, and `coord.abort`.
| Column | Type | Notes |
|--------|------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| sessionId | text NOT NULL | FK → sessions.id |
| spokeId | text | FK → spokes.id |
| workspaceId | text | FK → workspaces.id |
| parentSessionId | text | FK → sessions.id — Coordinator's session. onDelete: SET NULL — deleting the coordinator detaches the mapping but preserves it. |
| taskId | text | FK → tasks.id — The task this mapping is assigned to. Nullable — some mappings aren't task-scoped. |
| task | text | Denormalized task display name (slug or name) for quick reference without a JOIN. |
| status | text NOT NULL | Enum: `active`, `completed`, `aborted`, `failed`. Default: `active` |
**Indexes**: `idx_mappings_session_id` on `(sessionId)`, `idx_mappings_parent_session_id` on `(parentSessionId)`, `idx_mappings_spoke_id` on `(spokeId)`, `idx_mappings_task_id` on `(taskId)`, `idx_mappings_workspace_id` on `(workspaceId)` — workspace-scoped mapping queries.
`projectId` is derived from the session's project context, not stored directly. A mapping's project scope comes from its session. `workspaceId` is the workspace within that project.
**Status transitions**: `active` → `completed` (successful finish), `active` → `failed` (error), `active` → `aborted` (coordinator cancelled). No transition back to `active` from terminal states.
See coordination.md for the operations that create and query these mappings.
### `detections`
Anomaly detection records produced by the hub's monitoring heuristics. See coordination.md for the detection heuristics and `coord.detect` operation.
| Column | Type | Notes |
|--------|------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| sessionId | text NOT NULL | FK → sessions.id |
| anomalyType | text NOT NULL | `MODEL_DEGRADATION`, `HIGH_ERROR_COUNT`, `SESSION_STALL`. Extensible — new types can be added without schema migration. |
| severity | text NOT NULL | `high`, `medium`, `low` |
| details | jsonb | Detection-specific details (thresholds, counters, timestamps) |
| resolvedAt | timestamp with tz | When the detection was resolved/dismissed. Null if still active. |
| resolvedBy | text | FK → accounts.id — Who resolved it. onDelete: SET NULL |
| resolution | text | How it was resolved: `acknowledged`, `dismissed`, `escalated`, `fixed`. Null if still active. |
| dedupKey | text | Deterministic key for deduplication (e.g., hash of type+context). If a new detection has the same dedupKey as an active (unresolved) one, increment `occurrenceCount` instead of creating a new row. |
| occurrenceCount | integer NOT NULL DEFAULT 1 | Number of times this detection pattern has occurred. Incremented on dedup matches. |
**Indexes**: `idx_detections_session_id` on `(sessionId)` — find detections for a session, `idx_detections_type` on `(anomalyType)` — filter by detection type, `idx_detections_resolved_at` on `(resolvedAt)` — find active (unresolved) detections, `idx_detections_dedup_key` on `(dedupKey)` — dedup lookups.
**Deduplication**: When a new detection is created, compute a `dedupKey` from the detection type and relevant context. If an active (unresolved) detection with the same `dedupKey` exists, increment its `occurrenceCount` and update `details`/`updatedAt` instead of inserting a new row. This prevents persistent `MODEL_DEGRADATION` from creating a new row every check interval.
**Resolution**: A detection is active when `resolvedAt` is null. Setting `resolvedAt` (with `resolvedBy` and `resolution`) marks it as resolved. On session close (`sessions.status → archived`), consider auto-resolving active detections for that session.