# Idempotency Audit Contract

> Design and review idempotency and audit contracts for agent runtimes. Use when preventing duplicate side effects, propagating idempotency keys, persisting operation history, redacting sensitive payloads, auditing tool decisions, or reconstructing task execution after retries and resumes.

- **Type:** Skill
- **Install:** `agentstack add skill-hsienw-ai-agent-engineering-playbook-idempotency-audit-contract`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HsienW](https://agentstack.voostack.com/s/hsienw)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HsienW](https://github.com/HsienW)
- **Source:** https://github.com/HsienW/ai-agent-engineering-playbook/tree/master/skills-runtime-governance/idempotency-audit-contract

## Install

```sh
agentstack add skill-hsienw-ai-agent-engineering-playbook-idempotency-audit-contract
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Idempotency and Audit Contract

## Skill Interface

- Name: idempotency-audit-contract.
- Description: Design and review idempotency and audit contracts for agent runtimes that prevent duplicate side effects, propagate idempotency keys, persist operation history, redact sensitive payloads, audit tool decisions, and reconstruct task execution after retries and resumes.
- Parameters: Side-effecting operation, idempotency key scope and version, record lifecycle, expiry policy, audit event fields, actor and resource identifiers, redaction policy, replay rules, and verification cases.
- Instructions: Use this skill when a workflow writes to external systems or needs durable audit history. Lock before side effects, return recorded results for repeated keys, persist enough metadata for replay decisions, redact sensitive payloads, and test duplicate, expired, failed, concurrent, and resumed operations.

Side effects must be safe across retries, duplicate requests, worker crashes,
and resume flows. Audit must explain what happened without storing sensitive
payloads.

## Idempotency Key

Use a scoped, versioned key:

```ts
type IdempotencyKey = {
  namespace: string;
  resourceKey: string;
  version: string;
};

type IdempotencyRecord = {
  key: string;
  status: 'locked' | 'completed' | 'failed';
  result?: unknown;
  createdAt: string;
  expiresAt: string;
};
```

## Idempotency Rules

- Require idempotency for side-effecting operations.
- Lock before executing the side effect.
- Return the recorded result for repeated completed keys.
- Allow re-execution only after expiry or explicit invalidation.
- Include policy version in the key to avoid unsafe cross-version replay.
- Persist enough result metadata for deterministic replay decisions.
- Pair idempotency with a state transition guard for concurrent step updates.

## Audit Event

```ts
type AuditEvent = {
  eventId: string;
  taskId?: string;
  stepId?: string;
  operationId?: string;
  actorType: 'system' | 'user' | 'agent';
  actorId: string;
  action: string;
  resourceType: string;
  resourceId: string;
  decision: 'allow' | 'deny' | 'pending_confirmation';
  reasonCode?: string;
  beforeStateRef?: string;
  afterStateRef?: string;
  createdAt: string;
};
```

## Redaction Rules

Do not persist credentials, raw secrets, full prompts, full conversations,
private uploaded content, or unmasked personal data. Persist structured
summaries, hashes, opaque references, policy decisions, reason codes, and
redacted payload fragments when needed.

## Verification

Test repeated requests with the same key, expired keys, failed keys, concurrent
key acquisition, audit reconstruction, redaction, missing idempotency keys for
side effects, and resume after process restart.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HsienW](https://github.com/HsienW)
- **Source:** [HsienW/ai-agent-engineering-playbook](https://github.com/HsienW/ai-agent-engineering-playbook)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hsienw-ai-agent-engineering-playbook-idempotency-audit-contract
- Seller: https://agentstack.voostack.com/s/hsienw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.