Install Receipt

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?"

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
wrapped_install:
  source: apai
  package: prompt-preflight-starter
  package_reference: prompt-preflight-starter
  command:
    executable: apai
    args: ["install", "prompt-preflight-starter"]
  executed: false
  writes_files: false
  blocked_reason: External wrapped installer was not executed. Current live APAI packages write receipt evidence only.
package_sha256: 8a3f...
target_platform: codex
install_mode: native-install
integrity:
  registry_source_verified: true
  package_manifest_verified: true
  package_manifest_source_type: apai
  package_manifest_execution_enabled_in_v01: false
  package_manifest_writes_files: false
  install_card_verified: true
  payload_manifest_verified: true
  payload_artifact_fetch_status: no-artifacts
  payload_artifact_fetch_verified: true
  payload_artifact_fetch_writes_files: false
  payload_execution_mode: no-op
  payload_execution_writes_files: false
  payload_execution_requires_operator_approval_before_write: true
user: griffin9899
workspace: ~/projects/myapp
files_added: []
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"

• 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} / apai receipts verify {install_id} / apai rollback <package> --install-id {install_id}
• Agent handoff: apai state inspect

The optional wrapped_install block records the package source APAI is wrapping. For APAI-native packages this source is apai. For future external installs it can be npm, pip, gh, or gemini. The command is stored as { executable, args }, never as a shell string.

In v0.1 external source installs are preview-only, so receipts that include this block should use executed: false and writes_files: false unless a later phase explicitly enables and verifies the underlying package-manager execution path.

v0.1 receipts are plain JSON. The optional integrity block records what the installer verified before it wrote the receipt: live registry source state, package-manifest source/wraps boundaries, install-card checksum evidence, payload-manifest checksum evidence, payload artifact gate status/findings, payload artifact fetch status/hash evidence, wrapped-install evidence, and the payload execution decision (no-op, blocked, or package-store-install). 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.