System Overview

Cordum is an agent control plane. Work enters as a job, moves through submit → dispatch → output, and leaves as a recorded result — with every transition observable and every decision attributable.

Governance is inline, not bolted on. Every job is evaluated against policy before it dispatches. Every result is re-evaluated after it executes. Decisions that require human sign-off pause the run; decisions that deny end it. Approvals, throttles, and constraints are first-class outcomes recorded against the job, not side channels.

Clients/UI
  |
  v
API Gateway (HTTP/WS + gRPC)
  | writes ctx/res/artifact pointers
  v
Redis (ctx/res/artifacts, job meta, workflows, config, DLQ, schemas, locks)
  |
  v
NATS bus (sys.* + job.* + worker.<id>.jobs)
  |
  +--> Scheduler (safety gate + routing + job state)
  |       |
  |       +--> Safety Kernel (gRPC policy check)
  |
  +--> External Workers (user-provided)
  |
  +--> Workflow Engine (run orchestration)

Components

API Gateway

Single entrypoint for HTTP, WebSocket, and gRPC traffic. Accepts job submissions, exposes workflow and run state, brokers approvals and remediations, streams bus events. Evaluates submit-time policy before anything is persisted — denials never touch the bus, throttles surface as 429, and jobs requiring approval are created in paused state.

Dashboard

React UI served at /, connected to the gateway's HTTP and streaming APIs. Governance surfaces — policy replay, rule analytics, approval detail with blast radius and rollback guidance — live alongside the operational views for jobs, workflows, and runs.

Scheduler

Consumes submit, result, cancel, and heartbeat subjects from the bus. Calls the Safety Kernel before dispatch and routes approved jobs to the appropriate pool or worker subject. Persists job state, retries stuck jobs, reconciles timeouts, and emits dead-letter entries for terminal failures.

Safety Kernel

The policy decision point. Given a job, returns allow, deny, require-approval, throttle, or allow-with-constraints. Policy is sourced from file or URL, layered with config-service fragments, hot-reloaded on change, and optionally cached for repeated checks. A sibling Output Policy Service re-evaluates results post-execution.

Workflow Engine

Runs DAGs of jobs with retries, timeouts, approvals, and fan-out. Tracks each run's timeline, supports rerun-from-step and dry-run, and honours workflow and step-level schema validation. Denied steps are a first-class terminal outcome distinct from failures.

Context Engine

Provides context windows and memory for agents. Serves BuildWindow and UpdateMemory over gRPC and stores chat history, chunks, and summaries keyed by memory identity.

MCP Server

Bridges Cordum capabilities to the Model Context Protocol so agents speaking MCP can submit jobs, read workflow state, and inspect policy outcomes as tools and resources.

Licensing

Loads and verifies Ed25519-signed licenses for Community, Team, and Enterprise tiers. Entitlements feed the gateway (rate limits), scheduler (concurrency), workflow engine (step limits), Safety Kernel (bundle quotas), and audit subsystem (retention). Expired licenses degrade gracefully to Community.

Telemetry

Structured metrics collected across every service and exposed at each service's metrics port. Retention and export controls are license-tier aware.

External Workers

Live outside this repo. Subscribe to job topics or direct subjects, honour cancel, write results to Redis, and publish to the result subject. The CAP runtime provides typed handlers, pointer hydration, and worker helpers for heartbeats, progress, and cancellation.

Cordum Edge

Compliance firewall for AI agents on the Claude Code command-hook path (core/edge, cmd/cordum-agentd, cmd/cordum-hook). cordum-hook maps a Claude hook payload to a local cordum-agentd, which calls the Gateway /api/v1/edge/* routes for tenant-aware policy evaluation, approvals, and action-gate enforcement. It records an EdgeSession → AgentExecution → AgentActionEvent evidence trail (distinct from Cordum Jobs) with redacted summaries, hashes, and artifact pointers. See the Edge docs.

Job lifecycle (single job)

1. Client or gateway writes input JSON to Redis at ctx:<job_id>.
   • Before persisting, the gateway evaluates submit-time policy via the Safety Kernel. Jobs denied by policy are rejected immediately (HTTP 403 / gRPC PermissionDenied) and never reach the bus or scheduler. Throttled jobs receive 429 / ResourceExhausted. Jobs requiring approval are created in APPROVAL state without publishing.
2. Publish BusPacket{JobRequest} to sys.job.submit with context_ptr.
3. Scheduler:
   • Sets job state PENDING, resolves effective config, runs safety check.
   • Picks a subject (worker.<id>.jobs or job.*) and dispatches.
   • Pending replayer replays old PENDING jobs past the dispatch timeout.
   • If approval is required, state becomes APPROVAL_REQUIRED; approvals are bound to the policy snapshot + job hash before requeueing.
   • If remediations are returned, the gateway can apply one via POST /api/v1/jobs/{id}/remediate (creates a new job).
4. Worker:
   • Loads context from context_ptr, runs work, writes res:<job_id>.
   • Publishes BusPacket{JobResult} to sys.job.result.
5. Scheduler:
   • Updates terminal state and stores result_ptr.
   • Emits DLQ entry for terminal failures except FAILED_RETRYABLE.
   • FAILED_FATAL triggers saga rollback (compensation stack).
6. Reconciler marks stale jobs TIMEOUT based on timeout configuration.
7. Cancellation: API or workflow engine publishes BusPacket{JobCancel} to sys.job.cancel; workers cancel in-flight jobs.

Workflow runs

• Workflows are persisted in Redis and composed of steps with declared dependencies.
• A run is created via POST /api/v1/workflows/{id}/runs.
• Steps are dispatched as jobs using job IDs run_id:step_id@attempt.
• Step input supports simple expressions and template expansion.
• for_each steps fan out child jobs with foreach_index and foreach_item env fields.
• Approval steps pause the run until /approve is called.
• Runs and workflows can be deleted via DELETE /api/v1/workflow-runs/{id} and DELETE /api/v1/workflows/{id}.
• Runs support idempotency keys via the Idempotency-Key header on run creation.

Protocols

Bus packets and safety exchanges use CAP v2: BusPacket, JobRequest, JobResult, Heartbeat, and the PolicyCheck* message family. Cordum adds two local gRPC surfaces — a Cordum API for job submission and status, and a Context Engine for windows and memory.

Bus subjects and delivery

Subjects:

• sys.job.submit, sys.job.result, sys.job.progress, sys.job.dlq, sys.job.cancel, sys.heartbeat, sys.workflow.event
• job.* pool subjects
• worker.<id>.jobs direct worker subjects

JetStream (optional):

• Enable with NATS_USE_JETSTREAM=1.
• Durable subjects: sys.job.submit, sys.job.result, sys.job.dlq, job.*, worker.<id>.jobs.
• Best-effort: sys.heartbeat, sys.job.cancel, sys.job.progress, sys.workflow.event.
• Handlers are idempotent via Redis locks and retryable error NAKs.

Reference

Reference (binaries, code paths, env vars, metrics endpoints)

Binaries

• cordum-api-gateway
• cordum-scheduler
• cordum-safety-kernel
• cordum-workflow-engine
• cordum-context-engine
• cordumctl (CLI)
• cordum-mcp (MCP server)

Code paths

Component	Package	Binary
API Gateway	core/controlplane/gateway	cmd/cordum-api-gateway → cordum-api-gateway
Dashboard	dashboard/	— (static build served by nginx)
Scheduler	core/controlplane/scheduler	cmd/cordum-scheduler → cordum-scheduler
Safety Kernel	core/controlplane/safetykernel	cmd/cordum-safety-kernel → cordum-safety-kernel
Workflow Engine	core/workflow	cmd/cordum-workflow-engine → cordum-workflow-engine
Context Engine	core/contextwindow/engine	cmd/cordum-context-engine → cordum-context-engine
MCP Server	core/mcp	cmd/cordum-mcp → cordum-mcp
Licensing	core/licensing	— (library)
Telemetry	core/telemetry	— (library)

Repo layout

• core/ — control plane, infra, protocols, workflow engine.
• cmd/ — platform binaries.
• config/ — pools, safety, output-scanner, timeout configuration.
• dashboard/ — React UI.

Redis key map (selected)

• Context/result:
  • ctx:<job_id> — input payload
  • res:<job_id> — result payload
  • art:<id> — artifact payload
• Job store:
  • job:meta:<job_id> (state + metadata)
  • job:state:<job_id> (state)
  • job:recent (sorted set)
  • job:index:<state> (sorted sets for reconciliation)
  • job:deadline (sorted set of deadlines)
  • job:events:<job_id> (state transition log)
  • trace:<trace_id> (set of job ids)
• Context engine:
  • mem:<memory_id>:events, mem:<memory_id>:chunks, mem:<memory_id>:summary
• Workflow engine:
  • wf:def:<workflow_id> (definitions)
  • wf:run:<run_id> plus run indexes (wf:runs:*)
  • wf:run:timeline:<run_id> (append-only timeline)
  • wf:run:idempotency:<key> (idempotency mapping)
• DLQ:
  • dlq:entry:<job_id>, dlq:index
• Config service:
  • cfg:<scope>:<id>
  • cfg:system:policy (policy fragments bundle)
  • cfg:system:packs (installed pack registry)
• Schema registry:
  • schema:<id>, schema:index
• Locks:
  • lock:<key> (plus owner/ttl metadata)

Metrics endpoints

• Scheduler metrics: :9090/metrics
• API gateway metrics: :9092/metrics
• Workflow engine health: :9093/health

Protocol file paths

• CAP v2 types — github.com/cordum-io/cap/v2/cordum/agent/v1
• Cordum API — core/protocol/proto/v1/api.proto
• Context Engine — core/protocol/proto/v1/context.proto
• Generated Go types — core/protocol/pb/v1

Topics and pools

See config/pools.yaml for the full map. Topics are config-driven; no core topics are enforced.

Testing

• Run go test ./... (use GOCACHE=$(pwd)/.cache/go-build if needed).
• If modifying .proto, run make proto.
• Platform smoke: bash ./tools/scripts/platform_smoke.sh.