Skip to main content

Snapshot Resolvers

The snapshot resolver defines the current system or business state available during policy evaluation.

It is the runtime bridge between Actra and your external state sources such as databases, caches, fraud engines, workflow systems, and deployment controls.

The resolver is configured using the real runtime API:

runtime.setSnapshotResolver((ctx) => ({
  is_locked: ctx.account.locked,
}))

Core Mental Model​

Snapshot = current world state at decision time

Typical snapshot data includes:

  • account lock status
  • balance
  • quota usage
  • deployment environment state
  • approval status
  • workflow stage
  • fraud flags
  • ownership

Policies reference these fields using:

subject:
  domain: snapshot
  field: is_locked

Basic Resolver​

The most common pattern is mapping business state from an already loaded context.

runtime.setSnapshotResolver((ctx) => ({
  is_locked: ctx.account.locked,
  balance: ctx.account.balance,
  tier: ctx.account.tier,
}))

Ideal for:

  • account controls
  • payment approvals
  • tenant plans
  • feature access

Database-backed Snapshot​

A common service pattern is attaching DB-loaded state to request context.

runtime.setSnapshotResolver((req) => ({
  order_status: req.order.status,
  owner_id: req.order.ownerId,
  total: req.order.total,
}))

Best for:

  • order systems
  • resource ownership
  • document lifecycle
  • workflow routing

Redis / Cache Flags​

Excellent for fast-moving operational controls.

runtime.setSnapshotResolver((ctx) => ({
  is_fraud_suspected: ctx.flags.fraud,
  quota_exceeded: ctx.flags.quotaExceeded,
}))

Useful for:

  • fraud systems
  • rate limits
  • quota enforcement
  • emergency kill switches

Deployment Safety Checks​

A very strong DevOps governance use case.

runtime.setSnapshotResolver((deployCtx) => ({
  environment_locked: deployCtx.prodLocked,
  active_incident: deployCtx.incidentOpen,
}))

Great for:

  • CI/CD gates
  • production deploy safety
  • freeze windows
  • incident response

Workflow & Approval State​

Perfect for multi-step business processes.

runtime.setSnapshotResolver((workflowCtx) => ({
  approval_stage: workflowCtx.stage,
  already_approved: workflowCtx.isApproved,
}))

Ideal for:

  • finance approvals
  • HR workflows
  • procurement chains
  • release pipelines

Resolver Failure Behavior​

If the snapshot resolver throws, evaluation fails safely.

The runtime throws:

ActraError

with a wrapped message:

Resolver failed: ...

This prevents unsafe execution when state resolution is broken.

Missing Resolver Behavior​

If no snapshot resolver is configured, the runtime uses:

{}

This is safe, but most production policies should provide snapshot state for meaningful governance.

Best Practices​

Keep snapshot state-focused​

Use snapshot for:

  • balances
  • ownership
  • lifecycle stage
  • approval status
  • environment safety

Avoid caller identity here.

Prefer read-only state​

Snapshot should represent the current state of the world, not mutable request intent.

Avoid duplicating actor fields​

Use:

  • actor → who is calling
  • action → what is attempted
  • snapshot → current state

This keeps rules auditable and easy to reason about.

Production Mental Model​

DB / Cache / Workflow / Deploy State
 -> Resolve snapshot
 -> Build state object
 -> Runtime evaluation

This is how Actra reasons about the world before execution.

Next Steps​

  • Explore Explain & Debugging
  • Build Testing Policies
  • Add Observability & Audit
  • Combine with Actor Resolvers