Basic Refund Example

This example demonstrates the Actra refund policy workflow in both Python and JavaScript.

It is the ideal first example because it teaches the complete mental model:

• define schema
• write a blocking rule
• compile the policy
• attach runtime resolvers
• protect a function
• validate allow vs block behavior

The business rule is simple:

Refunds greater than 1000 are blocked.

---

What This Example Teaches

• schema-driven action validation
• actor resolver usage
• snapshot resolver usage
• runtime admission control
• policy exceptions
• testing expected blocks
• SDK parity across languages

---

Example

Python

"""
Basic Actra Example

This example shows how Actra can enforce admission
control policies on normal Python functions.
"""

from actra import Actra, ActraPolicyError
from actra.runtime import ActraRuntime


schema_yaml = """
version: 1

actions:
  refund:
    fields:
      amount: number

actor:
  fields:
    role: string

snapshot:
  fields:
    fraud_flag: boolean
"""

policy_yaml = """
version: 1

rules:
  - id: block_large_refund
    scope:
      action: refund
    when:
      subject:
        domain: action
        field: amount
      operator: greater_than
      value:
        literal: 1000
    effect: block
"""

policy = Actra.from_strings(schema_yaml, policy_yaml)
runtime = ActraRuntime(policy)

runtime.set_actor_resolver(lambda ctx: {"role": "support"})
runtime.set_snapshot_resolver(lambda ctx: {"fraud_flag": False})


@runtime.admit()
def refund(amount: int):
    print("Refund executed:", amount)


print("\n--- Allowed call ---")
refund(amount=200)

print("\n--- Blocked call ---")
try:
    refund(amount=1500)
except ActraPolicyError as e:
    print("Refund blocked by policy")
    print("Rule:", e.matched_rule)

JavaScript

import { Actra, ActraRuntime, ActraPolicyError } from "@getactra/actra";

const schemaYaml = `
version: 1

actions:
  refund:
    fields:
      amount: number

actor:
  fields:
    role: string

snapshot:
  fields:
    fraud_flag: boolean
`;

const policyYaml = `
version: 1

rules:
  - id: block_large_refund
    scope:
      action: refund
    when:
      subject:
        domain: action
        field: amount
      operator: greater_than
      value:
        literal: 1000
    effect: block
`;

const policy = await Actra.fromStrings(schemaYaml, policyYaml);
const runtime = new ActraRuntime(policy);

runtime.setActorResolver(() => ({ role: "support" }));
runtime.setSnapshotResolver(() => ({ fraud_flag: false }));

function refund(amount: number) {
  console.log("Refund executed:", amount);
  return amount;
}

const protectedRefund = runtime.admit("refund", refund);

console.log("\n--- Allowed call ---");
await protectedRefund(200);

console.log("\n--- Blocked call ---");
try {
  await protectedRefund(1500);
} catch (e) {
  if (e instanceof ActraPolicyError) {
    console.log("Refund blocked by policy");
    console.log("Rule:", e.matchedRule);
  }
}

---

Expected Output

Allowed

Refund executed: 200

Blocked

Refund blocked by policy
Rule: block_large_refund

---

Why This Example Matters

This example introduces the most important Actra runtime guarantee:

Policy is evaluated BEFORE business execution

That means blocked calls never reach your application logic.

This is the foundation for:

• refund controls
• deploy gates
• destructive tool safety
• finance approvals
• agent tool governance

---