1Purpose
An Install Receipt is the durable record of what an APAI install actually did. Files added, files modified, permissions requested, permissions granted, risk score at time of install, approval state, and the exact rollback command needed to undo the install.
Every successful install MUST produce a receipt. Every failed install MUST produce a receipt describing the failure state. The receipt is the artifact a security or operations team would inspect weeks later to answer "what got installed on this machine and when?"
2Example
schema: apai.receipt.v0.1 install_id: rcpt_01HXYZABC123 package: prompt-preflight-starter package_version: 0.1.0 package_source: https://github.com/example/prompt-preflight-starter package_sha256: 8a3f... target_platform: codex install_mode: local-tool user: griffin9899 workspace: ~/projects/myapp files_added: - .apai/skills/prompt-preflight-starter/PROTOCOL.md - .apai/skills/prompt-preflight-starter/SKILL.md files_modified: [] permissions_requested: - file_write - memory_write: false permissions_granted: - file_write approval_state: granted_by_operator_at_install risk_level: low scanner_findings: [] status: success timestamp: "2026-05-14T01:30:00Z" rollback_command: "apai rollback prompt-preflight-starter --install-id rcpt_01HXYZABC123"
3Required fields
| Field | Type | Req | Description |
|---|---|---|---|
| schema | string | yes | Must be "apai.receipt.v0.1" exactly. |
| install_id | string | yes | Globally unique install ID. Format: rcpt_ + ULID or KSUID. |
| package | string | yes | Package slug. |
| package_version | string | yes | Exact version installed. |
| package_source | string | yes | Source URL the package came from (registry, git URL, etc). |
| package_sha256 | string | no | SHA256 of the package archive when applicable. |
| target_platform | string | yes | Where the package was installed: codex, claude_code, gemini_cli, etc. |
| install_mode | enum | yes | local-tool | cloud-sandbox | remote-connector. Where the install lands: user's machine / LLM provider's session-scoped sandbox / no software fetched anywhere. |
| user | string | yes | Local user or workspace member who triggered install. |
| workspace | string | yes | Workspace path or identifier. |
| files_added | string[] | yes | List of files created by the install. Empty array if none. |
| files_modified | string[] | yes | List of files modified. Empty array if none. |
| permissions_requested | string[] | yes | Permissions the package's manifest declared. |
| permissions_granted | string[] | yes | Permissions the operator approved at install. |
| approval_state | string | yes | How approval was obtained. Examples: granted_by_operator_at_install, granted_by_policy, denied_with_reason. |
| risk_level | enum | yes | Risk level from passport at time of install. |
| scanner_findings | object[] | yes | Scanner findings at time of install. Empty array if clean. |
| status | enum | yes | success | failed | partial |
| timestamp | ISO 8601 datetime | yes | When the install completed (or failed). |
| rollback_command | string | yes | Exact command to reverse the install. |
4Where receipts live
- Local:
~/.apai/receipts/{install_id}.json - Workspace audit log:
.apai/install.log.jsonl(one JSON object per install, append-only) - Cloud copy:
/api/install/receipt(Phase 4+, opt-in) - CLI:
apai receipts list/apai receipts show {install_id}
5Integrity
v0.1 receipts are plain JSON. Phase 6 adds:
- Hash chain across receipts in the same workspace audit log.
- Optional signature using the publisher's verified key.
- Cloud-side receipt index for cross-machine audit.
What this spec is NOT
- ·A transaction log. Receipts describe install events, not every action a package took after install. Runtime activity logs are a separate concern (Policy Pack telemetry).
- ·A guarantee of rollback success. The rollback_command field is the operator's tool; whether rollback fully restores prior state depends on the package's rollback strategy and what happened after install.
- ·A privacy boundary. Receipts may contain workspace paths, usernames, file paths, and timestamps. Treat receipts as sensitive; do not publish them externally without redaction.