Decorators

Python decorator shape

from haltstate.decorators import guard

@guard(action="refund.create", idempotency_key=lambda order: f"refund:{order.id}")
def issue_refund(order):
    return ledger.write_refund_once(order)

When to use decorators

Use decorators for small service methods where the action name and idempotency key can be derived cleanly from function arguments. Prefer explicit guard blocks for complex workers that need to claim rows, update state transitions, create proof evidence, or report multiple outcomes.

Sync decorator

from haltstate import haltstate_guard, HaltStateClient

client = HaltStateClient(tenant_id='acme', api_key='hs_xxx')

@haltstate_guard(client=client, action='data.export', agent_id='exporter')
def export_records(count: int):
    return do_export(count)

Async decorator

from haltstate import AsyncHaltStateClient
from haltstate.decorators import ahaltstate_guard

client = AsyncHaltStateClient(tenant_id='acme', api_key='hs_xxx')

@ahaltstate_guard(client=client, action='chat.complete', agent_id='llm')
async def call_llm(prompt: str):
    return await llm_call(prompt)

OpenAI wrapper

from haltstate import openai_guard, HaltStateClient

client = HaltStateClient(tenant_id='acme', api_key='hs_xxx')

@openai_guard(client=client, agent_id='gpt')
def ask(prompt: str):
    return openai.ChatCompletion.create(model='gpt-4', messages=[{'role': 'user', 'content': prompt}])

Implementation notes

Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.

Operational evidence

For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.