gemstone-nexus · Phase 6

DIDYMUS-ARCH-01 — Didymus Hub Architecture

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
2DIDYMUS-ARCH-01DIDYMUS-ARCH-01 — Didymus Hub ArchitecturedidymusDevResources/docs/DIDYMUS-ARCH-01.mdDidymus is the AI-orchestration hub that registers build suggestions from AI tools and desktop workers, stores them under a schema-enforced approval gate, and presents every task through GemStone as the single universal approval surface. This document is the architecture reference named by DOCA1, DOC02 Phase 3C, and DOC06. Operator steps live in DIDYMUS-PLAYBOOK.md.962b59334e02a9730085a3c781af4bace46ddf7b2026-07-22 18:33:18

Content

# DIDYMUS-ARCH-01 — Didymus Hub Architecture

*Worker contract, task storage, and MCP tool surface for GemStone integration*

**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Approved for Build · **Date:** July 21, 2026

## 1. Purpose

Didymus is the AI-orchestration hub that registers build suggestions from AI tools and desktop workers, stores them under a schema-enforced approval gate, and presents every task through GemStone as the single universal approval surface. This document is the architecture reference named by DOCA1, DOC02 Phase 3C, and DOC06. Operator steps live in DIDYMUS-PLAYBOOK.md.

## 2. Hybrid Topology

```
Workers (Cursor, Claude, Gemini, future Ollama/desktop)
        |  submit_task / lease / report_status / verify_output
        v
Didymus Hub (task store + lease coordinator + MCP tools)
        |
        |  PENDING tasks projected identically
        v
GemStone UI (universal approval surface; Auth0-gated)
        |
        |  human sets approved_by + approved_at
        v
Worker lease -> RUNNING -> COMPLETED/FAILED -> VERIFIED
```

GemStone never executes worker code itself at MVP. GemStone Agent may submit tasks (`requested_by="GemStone"`) but cannot approve them (DOC03 Section 7).

## 3. DidymusWorker Contract

Every registered worker implements:

| Method | Responsibility |
| --- | --- |
| `get_capabilities()` | Returns worker_id, tool family, supported task_types, max concurrency, tier affinity |
| `execute_command(task)` | Runs only when task status is APPROVED and lease acquired; returns structured result |
| `report_status(task_id)` | Heartbeat and progress; lease renewal |
| `verify_output(task_id, result)` | Optional worker-side verification; GemStone may also verify |

Workers that cannot implement the full contract are not registered. Capability claims are advisory; the hub enforces lease and status transitions.

## 4. Task Storage Model

Logical table `didymus_tasks` (Postgres; mirrored summary rows may land in the SQLite Project Ledger for audit/UI):

| Field | Rules |
| --- | --- |
| `id` | UUID PK |
| `requested_by` | Human user_id or `"GemStone"` |
| `target_worker` | Registered worker_id |
| `task_type` | Allow-listed string |
| `payload` | JSON; no secrets |
| `status` | PENDING \| APPROVED \| RUNNING \| COMPLETED \| FAILED \| VERIFIED |
| `approved_by` | NULL until human approval |
| `approved_at` | NULL until human approval |
| `org_id` | Required; RLS / query scoping |
| `created_at` / `updated_at` | Timestamps |

Schema constraints (mandatory):

- CHECK: `status = 'RUNNING'` implies `approved_by IS NOT NULL AND approved_at IS NOT NULL`
- No direct transition PENDING -> RUNNING
- Lease claim is an atomic UPDATE that only succeeds when `status = 'APPROVED'`

## 5. State Machine

Identical to DOC03 Section 6:

```
PENDING --(human approved_by + approved_at)--> APPROVED
APPROVED --(worker lease)--> RUNNING
RUNNING --(report)--> COMPLETED | FAILED
COMPLETED --(verify)--> VERIFIED
```

Source never changes the path. Blind-source review: GemStone UI must not badge or color tasks by origin in the default queue view.

## 6. MCP Tool Surface

Didymus Hub exposes MCP tools consumed by GemStone and registered workers:

| Tool | Caller | Behavior |
| --- | --- | --- |
| `didymus.submit_task` | Workers, GemStone Agent | Creates PENDING task |
| `didymus.list_pending` | GemStone UI | Org-scoped PENDING/APPROVED queue |
| `didymus.approve_task` | Human roles only | Sets approved_by/approved_at; status APPROVED |
| `didymus.lease_task` | Workers | Atomic lease into RUNNING |
| `didymus.report_result` | Workers | COMPLETED/FAILED + payload |
| `didymus.verify_task` | GemStone or worker | VERIFIED |

Secrets and API keys never travel in MCP payloads; workers read credentials from the secrets tier (AWS Secrets Manager / host env) provisioned per DIDYMUS-PLAYBOOK.

## 7. GemStone Integration Points

- Phase 3C API: `POST /api/didymus/tasks`, `POST /api/didymus/tasks/{id}/approve` (DOC03 Section 4).
- Platform Dashboard Approval Queue view (DOC21).
- Incident runbook if RUNNING without approval (DOC08 Section 3).
- UAT: Universal Approval Queue script (DOC20).

## 8. MVP Worker Set

| Worker | Family | Notes |
| --- | --- | --- |
| Cursor | IDE agent | PAT / API credential in secrets tier |
| Claude | Cloud LLM agent | API key in secrets tier |
| Gemini | Cloud LLM agent | API key in secrets tier |

Deferred workers (DOC02 Section 3): Claude Code, AntiGravity, GemStone-as-worker runtime, SolidWorks, KiCad. Sovereign Ollama worker may be added under the same contract without changing the approval gate.

## 9. Security

- Cross-org isolation on every list/approve/lease path.
- Transcripts and session audio never appear in Didymus task payloads.
- Western-origin stack constraints (DOC17) apply to any hub dependencies.


---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505