Receipts

A Receipt is the signed, line-numbered recipe of how a Surface should compose. PhiCo proposes Receipts; you accept them. Nothing publishes without a human-accepted Receipt. Every accepted Receipt becomes an immutable snapshot you can diff against, roll back to, or audit.

Think of the Receipt as a typed PR description: it tells you exactly what will change, you sign off, and only then does the change land.

Why Receipts exist

PhiCo is an AI. AI proposals must be reproducible, reviewable, and auditable. The Receipt is the contract:

Reproducible — Same Receipt → same Surface render, every time.
Reviewable — The diff is human-readable line-by-line.
Auditable — Receipt history is preserved and signed.

If PhiCo’s proposal were applied without a Receipt, the same prompt could produce two different Surfaces, debugging would be guesswork, and there’d be no audit trail for compliance.

Anatomy of a Receipt

Receipt sf_abc123 · rev 7 → 8
Hash sha256:8f3a…d2c1
Author phico/composer · agent_id=…
Tokens 1,420 · Φ cost (on accept) 0.84 Φ
─────────────────────────────────────────
+ container                       L01    maxWidth="lg" padding="lg"
+   heading                       L02    level=1 content="…" align="center"
+   text                          L03    content="…" color="muted"
~ container.padding               L05    lg → xl
- image (id="img_old")            L21    removed

Every Receipt carries:

Field	What it is
`receiptId`	ULID; stable across the Receipt’s lifetime.
`surfaceId`	The Surface the Receipt targets.
`parentRevision` / `nextRevision`	Revision boundary the Receipt would create.
`hash`	SHA-256 of the canonical Receipt body.
`signature`	Server-side signature. Used by clients to verify provenance.
`lines`	Ordered list of diff operations: `add`, `mutate`, `remove`. Each line is independently addressable.
`aiMeta`	Model, agent, mode (`compose`/`mutate`/`spawn`/`style`/`bind`), token usage, Φ cost on accept.
`proposedAt` / `acceptedAt`	Timestamps; `acceptedAt` is null until human acceptance.

Lifecycle

[draft]
  │ PhiCo proposes
  ▼
[proposed]   ◄────────────┐
  │ human review          │
  ├── accept ──► [accepted] (revision committed)
  ├── modify ──► [proposed] (refined Receipt)
  └── reject ──► [rejected] (no charge)

Accepted Receipts are immutable. Rejected Receipts are kept for audit but never apply to the Surface.

Diff line semantics

Op	Meaning
`+` (add)	A new block — props, children, position.
`-` (remove)	Block deleted by ID.
`~` (mutate)	Targeted edit — only the changed prop is in the diff line.
`move`	Block re-parented or re-ordered.
`cap+` / `cap-` / `cap~`	Capability config added / removed / mutated.

The same line operations show up in GET /api/surfaces/:id/revisions/:from/diff/:to when you compare two arbitrary revisions.

Φ accounting

Receipts cost nothing to propose or reject. The Φ cost lands at acceptance time — that’s the trigger that commits the revision and charges your World’s grant.

API

Receipts are composed at the Receipt level, but accepted or rejected per instruction — each diff line is independently addressable (ADR-111).

Method	Endpoint	Purpose
`POST`	`/api/phico/receipt/generate`	Compose a Receipt for a Surface. Returns the Receipt with all instructions in `preview` state.
`GET`	`/api/phico/receipt/:receiptId`	Fetch a Receipt with its ordered instructions.
`POST`	`/api/phico/receipt/:receiptId/instruction/:instructionId/execute`	Produce the diff preview + mutations for a single instruction.
`POST`	`/api/phico/receipt/:receiptId/instruction/:instructionId/accept`	Accept and apply a single instruction.
`POST`	`/api/phico/receipt/:receiptId/instruction/:instructionId/reject`	Reject a single instruction with an optional reason.
`GET`	`/api/surfaces/:id/revisions`	List all accepted revisions.
`GET`	`/api/surfaces/:id/revisions/:from/diff/:to`	Receipt-style diff between two revisions.