Idempotency Keys

Stable construction

Build a stable logical key from the business action and resource identity, not from a random timestamp. Logical or destination examples include refund:ledger-entry-id, customer-export:request-id, and payment:invoice-id:attempt-1. After replay activation, wrap that logical key as hsr1:<operator-epoch>:<logical-key> for HaltState while keeping the destination key separate. Random keys generated after every retry create a new decision for the same business action.

Duplicate prevention

The key binds one exact operation and lets HaltState replay its stored decision without issuing a second permit. It does not make an external side effect exactly-once. The destination or business ledger must enforce the same idempotency key or a uniqueness constraint, and a permit-issued operation with no confirmed report requires reconciliation rather than re-execution.

Approval resumes

When an action requires approval, a later retry should use the same key. That retry can discover that the approval was granted, rejected, expired, or still pending without creating a second approval request.

Activation epoch and destination identity

At activation, newly admitted work uses an epoch-qualified authority key such as hsr1:<activation-epoch>:<logical-key>. The activation epoch fences stale delayed calls, but it does not replace the destination's stable business key. Destination idempotency remains separate; a permit with uncertain external completion requires reconciliation, not a new HaltState key or replacement permit.

Construction examples

from datetime import date

operator_epoch = '11111111-2222-4333-8444-555555555555'
destination_key = f'nightly-cleanup-{date.today().isoformat()}'
op_key = f'hsr1:{operator_epoch}:{destination_key}'

# Other logical keys follow the same construction:
refund_destination_key = f'refund:{ledger_entry_id}'
refund_op_key = f'hsr1:{operator_epoch}:{refund_destination_key}'

Exit-and-retry pattern

from haltstate import HaltStateClient, ApprovalPending, ActionDenied
from datetime import date
import sys

client = HaltStateClient(tenant_id='acme', api_key='hs_xxx')
operator_epoch = '11111111-2222-4333-8444-555555555555'
destination_key = f'maintenance-{date.today().isoformat()}'
op_key = f'hsr1:{operator_epoch}:{destination_key}'
report_id = '40000000-0000-4000-8000-000000000501'

try:
    with client.guard(
        'system.maintenance',
        params={},
        idempotency_key=op_key,
        report_id=report_id,
    ) as permit:
        permit.validate_for_execution()
        run_maintenance(idempotency_key=destination_key)
except ApprovalPending:
    print('Pending approval - will retry next cron run')
    sys.exit(0)
except ActionDenied as exc:
    print(f'Denied: {exc}')
    sys.exit(1)

Ledger idempotency

Policy idempotency and ledger idempotency are related but separate. HaltState should return the same decision for the same action key. The business ledger should still enforce a uniqueness constraint so a process crash or retry cannot write a second execution row for the same refund, payment, export, or message.

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.