Platform Compiler — Receipt & Provenance Model¶

Document: 4 of 4 Status: Canonical Depends on: Core Object Model (arch_01), Contract Model (arch_02), Projection Model (arch_03) Required by: Nothing — this is the terminal document

Purpose¶

This document defines receipts as first-class business objects. Receipts are not logs. They are not side effects. They are the authoritative record of what happened, bounded by the execution authority that produced them.

This document covers: receipt types, the immutability invariant, bounded authority, lineage and composability, the receipt schema authority, storage in Beads → Dolt, and the query model.

Receipts Are Business Objects¶

A receipt is an immutable claim about what occurred, bounded by the authority of the entity that issued it.

The Platform Compiler emits receipts. Deployment systems emit receipts. Verification workflows emit receipts. Beads consumes receipts. Dolt stores receipts. No receipt is ever modified after creation.

Events that produce Receipts:

    Import         → a provider contract was imported
    Compilation    → the compiler ran and produced a ProjectionPlan
    Projection     → a specific artifact was generated
    MR             → a generated MR was opened to a generated repository
    Deployment     → a generated artifact was applied to a runtime
    Verification   → a deployed runtime was verified against its projection
    Retirement     → a legacy deployment was removed from a runtime
    Migration      → a consumer was moved from one contract to another

Receipt Schema¶

The receipt schema lives in the registry at contracts/schemas/receipt.schema.yaml. This is the schema authority for all receipt types. It is authored by Bluefly and governs what constitutes a valid receipt.

# contracts/schemas/receipt.schema.yaml
Receipt:
  required:
    - id
    - type
    - authority
    - timestamp
    - status
    - claims
  properties:
    id:
      type: string
      pattern: "^receipt\\.[a-z0-9-]+\\.[0-9]{13}$"
      description: Globally unique, immutable. Never reused.
    type:
      enum:
        - import
        - compilation
        - projection
        - mr
        - deployment
        - verification
        - retirement
        - migration
        - error
    authority:
      $ref: "#/ExecutionAuthority"
    timestamp:
      type: string
      format: date-time
    status:
      enum: [success, failure, partial, skipped]
    inputs:
      type: array
      items:
        $ref: "#/ObjectReference"
    outputs:
      type: array
      items:
        $ref: "#/ArtifactReference"
    claims:
      type: array
      items:
        $ref: "#/Claim"
    lineage:
      type: array
      items:
        type: string
        description: IDs of parent receipts this receipt composes
    duration_ms:
      type: integer
    notes:
      type: string

ExecutionAuthority:
  description: >
    Bounds what the issuer may claim.
    Authority = Declared Role ∩ Published Scope ∩ Highest Successfully Exercised Layer
  required:
    - role
    - scope
    - layer
  properties:
    role:
      type: string
      description: Who the issuer is allowed to be (e.g., platform-compiler, deployment-agent)
    scope:
      type: string
      description: What the issuer was attempting to exercise
    layer:
      enum: [transport, published-contract, implementation]
      description: The highest layer successfully reached

Claim:
  required:
    - claim
    - status
    - evidence
    - confidence
  properties:
    claim:
      type: string
    status:
      enum: [TRUE, FALSE, POSSIBLE, UNKNOWN, NOT_FOUND]
    evidence:
      type: string
    confidence:
      enum: [HIGH, MEDIUM, LOW, NONE]

Receipt Types (Detailed)¶

import¶

Issued when a provider contract is imported into the registry.

id: receipt.import.1720958400000
type: import
authority:
  role: platform-compiler
  scope: provider-import
  layer: transport
timestamp: 2026-07-14T10:00:00Z
status: success
inputs:
  - type: provider
    id: provider.acquia
    import: source
    source_url: https://...
outputs:
  - type: file
    path: providers/acquia/imports/source/openapi.yaml
    hash: sha256:...
  - type: file
    path: providers/acquia/imports/source/manifest.yaml
    hash: sha256:...
claims:
  - claim: "Imported artifact hash matches source"
    status: TRUE
    evidence: "sha256 of downloaded file matches manifest record"
    confidence: HIGH
  - claim: "No content was modified during import"
    status: TRUE
    evidence: "Import is a straight copy; no normalization applied"
    confidence: HIGH

compilation¶

Issued when the compiler runs and produces a ProjectionPlan.

id: receipt.compilation.1720958400000
type: compilation
authority:
  role: platform-compiler
  scope: projection-planning
  layer: published-contract
timestamp: 2026-07-14T10:00:00Z
status: success
inputs:
  - type: objects
    count: 47
    path: objects/
  - type: contracts
    count: 23
    path: contracts/bluefly/
outputs:
  - type: projection-plan
    path: generated/projections/plan.yaml
    hash: sha256:...
claims:
  - claim: "All objects conform to their schemas"
    status: TRUE
    evidence: "Schema validation passed: 47/47 objects valid"
    confidence: HIGH
  - claim: "No two canonical deployments share a hostname"
    status: TRUE
    evidence: "Duplicate detection scan: 0 conflicts"
    confidence: HIGH
  - claim: "All provider manifests hash-verified"
    status: TRUE
    evidence: "12/12 provider manifests verified"
    confidence: HIGH
duration_ms: 1823

projection¶

Issued per generated artifact.

id: receipt.projection.1720958400001
type: projection
authority:
  role: platform-compiler
  scope: artifact-generation
  layer: published-contract
timestamp: 2026-07-14T10:00:00Z
status: success
lineage:
  - receipt.compilation.1720958400000
inputs:
  - type: deployments
    tunnel: tunnel.cloudflare.oracle-platform
    count: 76
outputs:
  - type: file
    path: generated/projections/cloudflare/tunnel-config.yml
    hash: sha256:...
    renderer: renderer.yaml.cloudflare-tunnel
    projection_type: exposure:tunnel-ingress
claims:
  - claim: "All 76 canonical deployments included in tunnel ingress"
    status: TRUE
    evidence: "76 ingress rules emitted; 3 legacy deployments excluded"
    confidence: HIGH
  - claim: "No legacy deployments included in projection"
    status: TRUE
    evidence: "Legacy filter applied before generation"
    confidence: HIGH

deployment¶

Issued when a generated artifact is applied to a runtime.

id: receipt.deployment.1720962000000
type: deployment
authority:
  role: deployment-agent
  scope: runtime-apply
  layer: transport
timestamp: 2026-07-14T11:00:00Z
status: success
lineage:
  - receipt.projection.1720958400001
inputs:
  - type: file
    path: generated/projections/cloudflare/tunnel-config.yml
    hash: sha256:...
outputs:
  - type: runtime-state
    runtime: runtime.cloudflare.global
    tunnel: tunnel.cloudflare.oracle-platform
claims:
  - claim: "Tunnel ingress config applied to Cloudflare"
    status: TRUE
    evidence: "Cloudflare API returned 200 on tunnel config PUT"
    confidence: HIGH
  - claim: "All 76 hostnames are routing correctly"
    status: UNKNOWN
    evidence: "Config was applied; probe verification not yet run"
    confidence: NONE

verification¶

Issued by a verification workflow after deployment.

id: receipt.verification.1720962300000
type: verification
authority:
  role: verification-agent
  scope: deployment-verification
  layer: published-contract
timestamp: 2026-07-14T11:05:00Z
status: partial
lineage:
  - receipt.deployment.1720962000000
inputs:
  - type: deployment-receipt
    id: receipt.deployment.1720962000000
claims:
  - claim: "compliance.blueflyagents.com responds on HTTPS"
    status: TRUE
    evidence: "HTTP 200 at https://compliance.blueflyagents.com/health"
    confidence: HIGH
  - claim: "mesh.blueflyagents.com responds on HTTPS"
    status: TRUE
    evidence: "HTTP 200 at https://mesh.blueflyagents.com/health"
    confidence: HIGH
  - claim: "studio.blueflyagents.com responds on HTTPS"
    status: FALSE
    evidence: "HTTP 502 — origin not accepting connections on :3012"
    confidence: HIGH
  - claim: "All 76 endpoints verified"
    status: FALSE
    evidence: "73/76 pass; 3 failures noted above"
    confidence: HIGH

Immutability Invariant¶

A receipt is never modified after creation.

If a receipt is found to be incorrect, a corrective receipt is issued:

id: receipt.correction.1720963000000
type: verification
lineage:
  - receipt.verification.1720962300000    ← the receipt being corrected
claims:
  - claim: "studio.blueflyagents.com responds on HTTPS"
    status: TRUE
    evidence: "HTTP 200 after origin service restart at 11:12:00Z"
    confidence: HIGH
notes: "Corrects claim in receipt.verification.1720962300000 — origin was restarting"

The original receipt is never deleted. The correction extends the provenance chain.

Bounded Authority¶

Every receipt declares the execution authority of its issuer. Claims are bounded by that authority.

Execution Authority = Declared Role ∩ Published Scope ∩ Highest Successfully Exercised Layer

A compiler receipt may claim it generated a file. It may not claim the file was deployed.
A deployment receipt may claim the API returned 200. It may not claim the service is functioning end-to-end.
A verification receipt may claim an endpoint responds. It may not claim the system is fully operational.

Language rules: - Observation: "The Cloudflare API returned 200 on tunnel config PUT." - NOT Observation: "The tunnel is fully operational."

Lineage and Composability¶

Receipts compose. Every receipt may reference parent receipts in its lineage field.

receipt.import.acquia-source
        │
        └─► receipt.compilation.2026-07-14
                │
                ├─► receipt.projection.tunnel-config
                │           │
                │           └─► receipt.deployment.cloudflare-tunnel
                │                       │
                │                       └─► receipt.verification.tunnel-endpoints
                │
                └─► receipt.projection.dns-records
                            │
                            └─► receipt.deployment.terraform-apply

A composite incident can aggregate multiple receipts without modifying any of them. The lineage chain is the audit trail.

Storage: Beads → Dolt¶

Receipts are not stored in Git. Git is for authored contracts and generated artifacts.

Receipts are stored in:

Beads (work state authority)
    │ captures receipt as work evidence
    ▼
Dolt (append-only relational store)
    │ receipts table — one row per receipt
    │ claims table — one row per claim
    │ lineage table — one row per parent-child edge
    ▼
Query API (bd CLI / Dolt SQL / REST)

The Dolt schema is the private implementation of receipt storage. The published contract is the receipt schema (contracts/schemas/receipt.schema.yaml) and the bd CLI query interface.

Receipt Schema Authority¶

The receipt schema lives in api-schema-registry/contracts/schemas/receipt.schema.yaml.

This is the only authoritative definition of what a valid receipt looks like. The compiler validates every receipt it emits against this schema before storing it. Any system that produces receipts (compiler, deployment agents, verification agents) must conform to this schema.

The receipt schema is versioned. Breaking changes require a migration: all existing receipts remain valid under their original schema version; new receipts conform to the new schema; both coexist in Dolt.

Query Model¶

Receipts are queryable by:

Query	Example
All receipts for a deployment	`bd receipts deployment.compliance.oracle.production`
All failed verifications in the last 24h	`bd receipts --type verification --status failure --since 24h`
Full lineage of a deployment	`bd receipts --lineage receipt.deployment.1720962000000`
All receipts for a compilation run	`bd receipts --lineage receipt.compilation.1720958400000`
All unverified deployments	`bd receipts --type deployment --not-followed-by verification`
Receipts for a given runtime	`bd receipts --runtime runtime.oracle.primary --type deployment`

The bd CLI is the published contract for querying receipts. Dolt SQL is the private implementation.

Five Invariants (Restated)¶

Immutability — receipts never change. Corrections are new receipts.
Bounded Authority — claims are bounded by role ∩ scope ∩ layer. No inference elevation.
Composability — composite incidents aggregate receipts; they do not rewrite them.
Monotonic Extension — later receipts add evidence; they never invalidate earlier receipts without a corrective receipt.
No Inference Elevation — a receipt may not claim to have reached a layer that was not successfully exercised.

Receipts as Business Objects¶

The receipt is not a technical artifact. It is a business record.

It answers: What happened? Who authorized it? What was consumed? What was produced? What was verified?

A deployment without a verification receipt is not complete. A compilation without a ProjectionPlan receipt is not auditable. A provider import without an import receipt is not provenance.

The receipt chain from import → compilation → projection → deployment → verification is the complete audit trail for any piece of infrastructure in the platform.