Skip to content
Clasper Core

Architecture

Architecture

Section titled “Architecture”

Overview

Section titled “Overview”

Clasper Core is a governance authority for AI execution with:

  • policy as data + decision explainability

  • async approvals (pending decisions + decision tokens)

  • trust status and verifiable exports (offline verification)

  • signed telemetry + active tool enforcement (v2.1 foundations)

  • Clasper Core (mandatory): decides whether execution is allowed (RBAC, risk, cost/budgets), issues a scoped decision, and stores an auditable record (traces + audit).

  • Execution adapters (optional): request permission, execute strictly within granted scope, and ingest telemetry back to Core.

    • Telemetry can be signed and tool calls can require authorization tokens.

Non-negotiable principles

Section titled “Non-negotiable principles”
  1. Governance is mandatory
  2. Execution is optional
  3. Default-deny
  4. Everything is attributable
  5. Humans can always intervene
  6. Adapters are clients, never peers
  7. No hidden autonomy

High-level architecture

Section titled “High-level architecture”
┌────────────────────────────┐
│        Clasper Core        │
│   (Governance Plane)       │
│                            │
│  RBAC • Risk • Cost        │
│  Traces • Audit • Ops UI   │
│  Workspaces • Promotions   │
└────────────┬───────────────┘
             │ governed execution
             │ (approval + scope)
┌────────────▼───────────────┐
│     Execution Adapters     │
│   (optional, pluggable)     │
│  Built-in Runtime (opt)     │
│  External adapters (opt)    │
└─────────────────────────────┘

Two contracts (keep them separate)

Section titled “Two contracts (keep them separate)”
  • Control Plane Contract: Clasper Core ↔ your backend (tasks/messages/documents, notifications, tool proxy)
  • Adapter Contract: Clasper Core ↔ execution adapters (decision + telemetry ingest)

Keeping these separate prevents “god mode” execution paths and makes execution provider-agnostic.

Governed execution flow

Section titled “Governed execution flow”

1) Decision phase (Core)

Section titled “1) Decision phase (Core)”

Adapters request permission:

  • POST /api/execution/request

Core evaluates:

  • RBAC
  • adapter risk class + requested capabilities
  • budgets / cost ceilings
  • policies (data-driven)
  • decision trace + explanation (why allow/deny/require approval)
  • overrides / approvals (audited)

If the outcome requires human gating, Core returns a pending decision with:

  • decision_id
  • expires_at
  • required_role

2) Execution phase (Adapter)

Section titled “2) Execution phase (Adapter)”

If allowed, adapter executes only within the granted scope (capabilities, steps, cost, expiry).

If pending, the adapter must pause, then poll:

  • GET /api/decisions/:id

On approval, Core issues a decision token which the adapter consumes once:

  • POST /api/decisions/:id/consume with X-Decision-Token

3) Telemetry phase (Adapter → Core)

Section titled “3) Telemetry phase (Adapter → Core)”

Adapters ingest:

  • POST /api/ingest/trace
  • POST /api/ingest/audit
  • POST /api/ingest/cost
  • POST /api/ingest/metrics
  • POST /api/ingest/violations

Ingest is idempotent so adapters can safely retry.

4) Integrity + enforcement (v2.1)

Section titled “4) Integrity + enforcement (v2.1)”
  • Telemetry is signed and verified on ingest.
  • Trace steps can be hash-chained to detect tampering.
  • Tool authorization tokens are validated and marked single-use.

Verifiability & evidence (v2.2)

Section titled “Verifiability & evidence (v2.2)”

Clasper Core can produce evidence suitable for security review and compliance:

  • Trust status is attached to traces (verified, verified_with_violations, unverified, compromised)
  • Verifiable exports bundle traces + audits + integrity manifest (npx clasper-core export ... to download)

Adapter-aware observability

Section titled “Adapter-aware observability”

Traces are adapter-aware and include:

  • adapter_id
  • granted_scope and used_scope
  • violations[]

This lets operators answer: what ran, who allowed it, what was granted, and what was actually used.

Deployment profiles

Section titled “Deployment profiles”

These are the same product, with the same guarantees:

  • Governance-only: Core + external adapters (or no adapters enabled)
  • Governance + runtime: Core + built-in runtime adapter enabled (developer convenience)
Section titled “Related”