Receipt Specification

This is the technical reference page for WitnessOps Receipt v2. It explains what a receipt is expected to carry, which proof references matter, how continuity is expressed, and how the current verifier reads the surrounding proof package.

If you need the concept first, start with Receipts. If you need the operator workflow, go to Verification.

1. Problem this page solves

Reviewers often receive a receipt artifact but still need a field-level contract for what is signed, what is referenced, and what verification can actually assert.

This page solves that diligence problem by defining the Receipt v2 shape and its proof references in technical terms.

2. What you should understand after reading

After this page, you should be able to answer:

• What exactly is a WitnessOps Receipt v2?
• What is signed, what is timestamped, and what is only referenced?
• Which fields establish continuity between receipts?
• How does the current verification path classify success, failure, or incomplete trust?

This page describes the public receipt contract. It does not replace the verifier implementation or bundle contract. It explains how they fit together.

Receipt v2 at a glance

Receipt v2 is the canonical statement WitnessOps issues for a governed event. It is designed to be:

• portable enough to move outside the runtime
• structured enough for offline verification
• narrow enough to stay atomic

Receipt v2 is not the full evidence bundle. It is the atomic proof statement inside the wider trust package.

At minimum, a Receipt v2 needs to express five things:

1. identity of the receipt itself
2. continuity position within a receipt stream
3. claimed event details
4. proof references to signed and timestamped material
5. enough linkage to connect the receipt to the bundle and chain around it

Canonical shape

The public shape below is intentionally simplified, but it reflects the current model: a governed statement plus structured references to the cryptographic artifacts that bind it.

{
  "schema": "witnessops.receipt.v2",
  "receipt_id": "rct_01H...",
  "ledger": {
    "stream": "engagement/execution",
    "seq": 1842,
    "prev_hash": "sha256:...",
    "entry_hash": "sha256:..."
  },
  "time": {
    "claimed_utc": "2026-03-28T12:34:56Z"
  },
  "actor": {
    "principal": "operator://...",
    "origin": "bridge://cli"
  },
  "intent": {
    "type": "scan.recon",
    "request_id": "req_01H..."
  },
  "result": {
    "status": "ok",
    "summary": "Governed recon completed"
  },
  "proof": {
    "dsse": {
      "payload_type": "application/vnd.witnessops.execution-receipt.v2+json",
      "envelope_digest": "sha256:...",
      "keyid": "sha256:..."
    },
    "rfc3161": {
      "present": true,
      "hashed_message": "sha256:...",
      "tsa": "tsa://...",
      "token_ref": "bundle/TIMESTAMP.tsr"
    },
    "log": {
      "included": true,
      "checkpoint_ref": "bundle/checkpoint.json",
      "inclusion_ref": "bundle/inclusion-proof.json"
    }
  }
}

The exact packaging may vary by bundle or delivery format. The trust model does not: the receipt is the claim, and the bundle carries the surrounding material required to verify that claim.

Field groups

Receipt identity

These fields identify the artifact being inspected.

These fields tell the verifier what kind of statement they are looking at. They do not establish continuity or proof strength on their own.

Continuity fields

These fields place the receipt into an append-only stream.

Continuity is broken if entry_hash recomputes differently, prev_hash does not match the prior receipt, or expected sequence order is missing.

Claimed event fields

These fields describe the governed event itself.

These fields matter for audit reconstruction, but they remain issuer claims until the surrounding proof material verifies.

Proof reference fields

Receipt v2 carries references to cryptographic artifacts rather than pretending the receipt alone is the whole proof story.

These references matter because the receipt does not become portable proof until a verifier can locate and validate the signed, timestamped, and committed material around it.

DSSE reference model

The signing layer is a DSSE envelope over the receipt statement. For diligence purposes, the important points are:

• the payload type is explicit
• the envelope bytes are the object being signed
• the envelope digest is the object later bound to trusted time

That order matters. The timestamp should bind to the signed envelope, not to an unsigned precursor and not to a human-readable rendering.

RFC 3161 reference model

WitnessOps uses RFC 3161 as the trusted-time reference for the signed object. In the public model:

• the timestamp token covers the DSSE envelope digest
• the timestamp token is an adjacent proof artifact, not a replacement for the receipt
• the receipt records where that timestamp proof lives and what digest it is expected to cover

When the timestamp token is absent, the receipt may still be valid as a signed statement, but it proves less about time.

Canonicalization and derived hashes

Receipt verification depends on deterministic hashing. Two rules matter:

1. the canonical representation must be stable
2. derived fields must not participate in computing themselves

Current typed proof paths in the implementation follow this rule explicitly. Artifact-hash computation and execution-hash computation are treated as separate canonicalization paths so the same receipt body is not allowed to self-justify derived digests.

For a technical buyer, the important consequence is simple: if canonicalization rules are ambiguous, trust drops immediately. WitnessOps treats canonicalization as part of the proof contract, not as a UI detail.

Current verification model

Keep two verification surfaces separate.

• The public /verify surface is receipt-first v1. It accepts supported receipt JSON and returns a receipt-scoped result.
• Bundle-complete verification evaluates the receipt in the context of the canonical proof bundle around it.

At a high level, a bundle-complete verifier does this:

1. normalize and parse the manifest
2. validate required fields and protocol compatibility
3. check artifact presence and hash integrity
4. validate signature and digest relationships
5. evaluate witness or trust-registry requirements when declared
6. return valid, invalid, or indeterminate

The public receipt-first surface does not prove bundle completeness or artifact-byte revalidation. A public valid result means supported receipt-level checks passed for the submitted receipt.

Those statuses mean:

That last case matters. WitnessOps treats incomplete trust state differently from a hard cryptographic failure.

Public failure vocabulary and proof breach codes

The public API first distinguishes input rejection from receipt verification results.

Public API failure classes:

• FAILURE_INPUT_MALFORMED
• FAILURE_INPUT_UNSUPPORTED

Proof-bearing receipt checks then expose breach codes such as:

• SCHEMA_MISSING_FIELD
• SCHEMA_UNKNOWN_STAGE
• DIGEST_RECORD_NOT_IN_SET
• DIGEST_ARTIFACT_TAMPERED
• ATTESTATION_SIGNATURE_INVALID
• ANCHOR_RFC3161_IMPRINT_MISMATCH
• WITNESS_SUBJECT_MISMATCH
• WITNESS_UNTRUSTED

For diligence review, that separation matters. A malformed request is different from a receipt that parses but fails a proof-bearing check.

What Receipt v2 proves

When verified against a trusted WitnessOps verification key, Receipt v2 proves that the signed statement is intact and claims issuance under that key identity, and that the statement is bound into a continuity structure with explicit proof references. It does not by itself prove key custody was uncompromised or that only WitnessOps could ever produce a matching shape.

When the surrounding bundle also verifies, the verifier can additionally conclude that:

• the signed statement is intact
• the required artifacts match declared digests
• the receipt sits inside the declared trust package
• any declared witness policy or trust-registry requirement was satisfied, unless the verifier returns indeterminate

What Receipt v2 does not prove

Receipt v2 does not, by itself, prove:

• that the underlying tool output was correct
• that the target choice was appropriate
• that the host running the operation was uncompromised
• that key custody outside the proof system was perfect
• that an isolated receipt tells the whole operational story without its chain and bundle context

Those boundaries belong in the threat model, not hidden in marketing copy.

8. Next-page handoff

Next, read Threat Model and Trust Boundaries to evaluate what this receipt contract can and cannot guarantee under adversarial conditions.

Then continue with:

• Execution Chains for continuity and Merkle packaging
• Proof Model for signature and timestamp layers
• Verification for operator workflow