Skip to main content

SDK & Runtime Overview

The SDK & Runtime layer is where Actra’s declarative DSL becomes real runtime enforcement.

This section explains how schemas, policies, governance, and runtime inputs flow through the compiler and into deterministic admission decisions.

It is the bridge between:

  • DSL authoring
  • production integration
  • runtime enforcement
  • governed execution workflows

Core Flow​

Every Actra admission pipeline follows the same mental model:

Schema -> Policy -> Compile -> Runtime -> Admit -> Execute

This is the core lifecycle that turns YAML policy logic into application enforcement.

Main SDK Components​

The SDK is built around a small set of deterministic building blocks.

Compiler​

Responsible for:

  • schema validation
  • policy validation
  • governance validation
  • operator checks
  • IR generation
  • optimized evaluation plan creation

The compiler converts human-readable YAML into a reusable compiled policy artifact.

Runtime​

The runtime applies compiled policies before execution.

Responsibilities include:

  • resolving actor context
  • building action payload
  • resolving snapshot state
  • evaluating matching rules
  • returning allow / block / approval effects

This powers calls such as:

runtime.admit("refund", refund)

Actor Resolver​

Provides who is calling.

Typical sources:

  • JWT claims
  • service identity
  • workflow system
  • AI agent name
  • internal automation user

Snapshot Resolver​

Provides current external state.

Typical sources:

  • database lookups
  • Redis flags
  • fraud systems
  • deployment state
  • quota systems
  • approval status

Governance Validator​

Runs before compilation.

This enforces:

  • required controls
  • forbidden policy patterns
  • allowed fields
  • approval coverage
  • organizational policy standards

Approval Hooks​

Used when a rule returns:

effect: require_approval

Later, the SDK will integrates this with external approval systems and workflow engines.

Runtime Lifecycle​

A typical request follows this sequence:

Application Call
 -> Resolve Actor
 -> Build Action Payload
 -> Resolve Snapshot
 -> Evaluate Rules
 -> Return Effect
 -> Execute or Block

This lifecycle is deterministic and identical across SDKs.

Deterministic Guarantees​

Actra’s runtime is intentionally compiler-grade and predictable.

Deterministic Evaluation​

The same input always produces the same effect.

First-Match Wins​

Within a rule set, the first matching rule decides the outcome.

Action > Global Precedence​

Action-scoped rules are evaluated before global rules.

This makes action routing the highest-priority decision path.

Fail-Safe Missing Fields​

If actor, action, or snapshot fields are missing:

  • field resolution returns non-match
  • condition evaluates to false
  • execution safely falls through

Default Allow​

If no rule matches, the runtime returns:

allow

This keeps behavior explicit and predictable.

Governance Before Compilation​

Governance validation always happens before runtime artifacts are produced.

This ensures unsafe policies never reach execution.

Multi-Language SDKs​

The Rust compiler core enables portable SDKs across environments.

Current integration layers:

  • JavaScript SDK
  • Python SDK
  • WASM runtime
  • Edge environments
  • Rust native core

Planned ecosystem directions:

  • Embedded systems
  • Policy gateways

Production Use Cases​

Actra is designed for real runtime control systems.

Common production use cases include:

  • API authorization
  • AI agent tool gating
  • workflow approval chains
  • deployment governance
  • financial transaction controls
  • SaaS tenant isolation
  • destructive action protection
  • production environment safety

Mental Model​

A useful production mental model is:

Actor   -> who is calling
Action  -> what is being attempted
Snapshot -> current system state
Policy  -> what should happen
Runtime -> enforce before execution

This model scales naturally from APIs to agents and CI/CD governance.

Next Steps​

  • Explore JavaScript SDK
  • Explore Python SDK
  • Learn Runtime Semantics
  • Build Actor Resolvers
  • Add Snapshot Resolvers
  • Enforce Governance Workflows