Skip to main content

Policy Artifact API

The Policy class is the compiled policy artifact used by the JavaScript SDK.

It wraps the validated native engine instance and provides a safe, ergonomic API for:

  • deterministic evaluation
  • schema-aware runtime integration
  • testing and assertions
  • policy hashing
  • debugging and explain flows

This page documents the Policy APIs exposed by JavaScript SDK.

Creating a Policy​

Most applications do not construct Policy directly.

Instead, create it through the compiler layer:

import { Actra } from "@getactra/actra"

const policy = await Actra.fromDirectory("./policy")

This returns a compiled Policy artifact ready for runtime use.

Artifact Mental Model​

YAML -> Compiler -> Native Policy -> Policy Artifact

The Policy instance is:

  • immutable after compilation
  • reusable across requests
  • safe for repeated evaluation
  • compatible with ActraRuntime

Schema APIs​

getSchema()​

Returns the parsed schema object if available.

const schema = policy.getSchema()

Used internally by ActraRuntime for schema-driven action normalization.

Useful for:

  • framework integrations
  • action builders
  • custom middleware
  • test helpers

hasSchema()​

Check whether schema metadata is attached.

if (policy.hasSchema()) {
  console.log("schema available")
}

This is useful when working with mixed compiled artifacts.

Evaluation APIs​

evaluate()​

Primary decision API.

const decision = policy.evaluate({
  action: { type: "refund", amount: 1000 },
  actor: { role: "support" },
  snapshot: { is_locked: false },
})

This validates the evaluation input before delegating to the native engine.

Returns a Decision object.

evaluateAction()​

Ergonomic helper for direct domain inputs.

const decision = policy.evaluateAction(
  { type: "refund", amount: 1000 },
  { role: "support" },
  { is_locked: false },
)

This is equivalent to evaluate() with explicit action, actor, and snapshot sections.

Best for:

  • tests
  • scripts
  • CI validation
  • framework adapters

Testing & Assertions​

assertEffect()​

The strongest testing API in the Policy class.

policy.assertEffect(
  {
    action: { type: "deploy", environment: "production" },
    actor: { role: "developer" },
    snapshot: {},
  },
  "require_approval",
)

If the actual effect does not match, it throws ActraPolicyError with:

  • expected effect
  • actual effect
  • full evaluation context

This is ideal for:

  • unit tests
  • CI regression suites
  • governance contract checks
  • rollout verification

Policy Hashing​

policyHash()​

Returns a stable hash of the compiled policy artifact.

const hash = policy.policyHash()

Excellent for:

  • cache keys
  • artifact integrity
  • CI drift checks
  • deployment verification
  • rollout safety

Explain & Debugging​

explain()​

Evaluates the policy and prints a structured explanation.

policy.explain({
  action: { type: "refund", amount: 5000 },
  actor: { role: "finance" },
  snapshot: { is_locked: false },
})

Printed sections include:

  • action
  • actor
  • snapshot
  • final result

This is excellent for:

  • local debugging
  • CI logs
  • policy support workflows
  • rollout validation

The method also returns the Decision object.

Error Semantics​

Invalid Native Artifact​

Constructing Policy without a valid native policy throws:

ActraPolicyError

Evaluation Failure​

Native evaluation failures are wrapped as:

ActraPolicyError

Assertion Failure​

assertEffect() mismatches throw:

ActraPolicyError

with expected vs actual decision details.

Production Use Cases​

The Policy artifact is ideal for:

  • direct service-side checks
  • CI policy verification
  • snapshot tests
  • contract tests
  • approval gate validation
  • deployment drift detection

Production Mental Model​

Compiled Policy
 -> evaluate()
 -> Decision
 -> assert / explain / hash

This is the safest low-level policy interface in the JavaScript SDK.

Next Steps​

  • Explore Compiler API
  • Build Testing Policies
  • Use Explain & Debugging
  • Integrate with Runtime API