Core Concepts

What Stellrai governs

Stellrai is not where you build your app — it's where your app becomes accountable.

Your app continues to own its UI, database reads, in-memory state, and business logic. Stellrai governs the specific class of actions that need to be authorized, traced, and recoverable:

Governed by Stellrai	Stays in your app
Payment initiations	UI rendering
AI agent decisions	Local DB reads/writes
Identity resolution	In-memory computation
External API calls (fraud, KYC)	Draft/ephemeral state
Audit-required state changes	App configuration
Webhook triggers	Session management

The runtime contract

Build your app with any tools you choose. To run on Stellrai, conform to the runtime contract — so every governed action is decided, executed, and audited by default.

The contract has four parts:

Request decision  →  Execute pipeline  →  Audit written  →  Rollback available

Every call through the SDK runs this loop. You do not opt in to individual pieces — they are always active.

Actors

An actor is the identity unit inside Stellrai. Every decision and execution is attributed to an actor.

// Actor ID format — always namespaced
'user:alice'
'service:payments-api'
'agent:fraud-detector'
'org:acme-corp'

Actors are created automatically on signup. For service-to-service calls, use a service actor with a dedicated API key.

Decisions

A decision is a policy evaluation. Before any governed action executes, a decision must be requested and approved.

POST /api/v1/decisions

Decision outcomes:

Outcome	Meaning
approved	Policy rules satisfied — execution may proceed
blocked	Policy rules not satisfied — execution must not proceed
escalated	Requires human review before execution

A decision is valid for one pipeline trigger. After use it cannot be reused (idempotencyKey controls deduplication).

Decision input fields:

Field	Type	Description
decisionType	string	Category of decision, e.g. payment.authorize
action	string	Specific action, e.g. payment.initiate
inputData	object	Context the policy engine evaluates against
resourceType	string?	Optional resource category
resourceId	string?	Optional specific resource ID
idempotencyKey	string?	Prevents duplicate decisions

Pipelines

A pipeline is a named sequence of steps that executes a governed action. Pipelines are defined once and triggered by name.

// Define a pipeline (done once, usually at setup)
await hdb.pipelines.create({
  name: 'payment.execute.standard',
  steps: [
    { id: 'validate',  type: 'action', name: 'Validate payload' },
    { id: 'route',     type: 'action', name: 'Route to provider', dependsOn: ['validate'] },
    { id: 'execute',   type: 'action', name: 'Execute payment',   dependsOn: ['route'] },
    { id: 'record',    type: 'action', name: 'Record outcome',    dependsOn: ['execute'] },
  ],
});

// Trigger it
const execution = await hdb.triggerPipelineByName('payment.execute.standard', {
  decisionId: decision.decisionId,
  input: { amount: 15000, to: 'acct_9k2x' },
});

Execution status values

Status	Meaning
pending	Queued, not yet started
running	Steps executing
completed	All steps succeeded
failed	One or more steps failed — compensation may be running
compensated	Rolled back to pre-execution state
replaying	Being replayed from a checkpoint

Checkpoints

Every pipeline step automatically writes a checkpoint — a snapshot of execution state at that point. Checkpoints are what make rollback and replay possible.

// Inspect checkpoints for a running execution
const checkpoints = await hdb.reversibility.getCheckpoints(execution.id);
// [{ id, stepId, state, createdAt }, ...]

You do not write checkpoints manually. The runtime creates them.

Reversibility

Every completed execution is reversible within its reversibility window (default: 30 minutes). Two operations are available:

Rollback — undo: runs compensation handlers for each step in reverse order.

await hdb.reversibility.rollback(execution.id, { reason: 'user_request' });

Replay — redo from a checkpoint: re-runs the pipeline from a specific saved state.

await hdb.reversibility.replay(execution.id, {
  fromCheckpointId: 'chk_xyz',
});

Audit trail

Every decision, execution, and rollback produces an immutable audit entry. You cannot delete audit entries.

const log = await hdb.queryAuditLog({
  actorId: 'user:alice',
  action:  'payment.initiate',
  from:    '2026-01-01T00:00:00Z',
  limit:   50,
});

Audit entries are queryable from the SDK, the REST API, and the Stellrai dashboard.

API keys and scopes

API keys authenticate SDK and direct API calls. Each key has a set of scopes that limit what it can do.

Scope	Access
decision:request	Request decisions
pipeline:trigger	Trigger pipelines
pipeline:read	Read execution state
reversibility:write	Rollback / replay executions
audit:read	Query audit log
policy:read	Read policies
policy:write	Create / update policies

Manage keys at Dashboard → Settings → API Keys.