The VPEC specification.

Field definitions, proof levels, gap model, and verification rules. This page is technical reference, not the marketing path.

§ 01 — Wire format

A single signed credential. Content-blind by construction.

A VPEC describes who ran what, against which declared controls, on which committed artifacts, with what proof level and what gaps. It is meant to leave the originating system and remain useful to another party later.

Field
Type
Example
Meaning

vpec

string

"primust/v1"

Wire format version. Frozen for verifier compatibility.

kind

enum

"pipeline.run" | "agent.run" | "agent.commit"

What this credential describes.

workflow_id

string

"refund_agent.review"

Operator-defined workflow or process identifier.

bundle_id

string

"eu_ai_act_art12_v1"

Named and versioned policy, regulation, or control bundle.

input_commit

hash

"poseidon2:b7f2..."

Commitment to the governed input. Never the input itself.

output_commit

hash

"poseidon2:9d08..."

Commitment to the output, if the workflow has one.

controls

array

[{ id, result, proof_level }]

Declared checks, policy gates, scanner runs, or review steps.

proof_level_floor

enum

"execution"

The weakest defensible proof level across the run.

provable_surface

float 0-1

0.91

How much of the declared surface is covered by verifiable evidence.

gaps

array

[{ code, scope, reason }]

Named missing, weaker, or unverifiable surface.

signed_at

rfc3339

"2026-04-12T14:33:01Z"

Issuer signing time. External timestamps can be attached.

issuer_kid

string

"kid_live_2026_01"

Public key identifier used by the verifier.

signature

bytes

"ed25519:..."

Issuer signature over canonical credential bytes.

§ 02 — Data boundary

The signer gets commitments. The governed content stays with you.

Content-blindness is the load-bearing property. It is what lets a VPEC travel to an auditor, regulator, reinsurer, or downstream team without turning the credential into a data spill.

Commitments, not content

Fields that would expose governed content are represented as Poseidon2 or SHA-256 commitments. The reviewer can test the credential against disclosed material later, but the signing path does not need the raw content.

Canonical bytes before hashing

Commitment inputs and the credential itself should be serialized deterministically before hashing or signing. Stable bytes are what make cross-language verification possible.

Commit before release

The artifact is committed inside the governed process before the result crosses the boundary being reviewed. A downstream log cannot silently rewrite the execution claim later.

Sensitive fields stay out

Signing requests should carry commitment hashes and execution metadata, not raw prompts, documents, customer records, claim files, patient records, or model reasoning traces.

When a stronger proof path is available, Poseidon2 commitments are ZK-friendly. When ordinary SHA-256 is the right engineering choice, the credential should still be explicit about the resulting proof level.

§ 03 — Proof levels

Every credential declares its weakest defensible level and its surface.

The floor is the weakest link. The surface is the distribution. A run can be mostly Mathematical and still have an Attestation floor because one important step was opaque. A good credential carries both instead of hiding the weak segment.

floor.05

Mathematical

Deterministic, independently replayable

The declared rule evaluated as declared on the committed input. A third party with the same policy pack and disclosed input gets the same result.

floor.04

Verified Model

Bound model hash or equivalent stronger model evidence

A named model-bound process produced the committed output with stronger evidence than an opaque invocation alone.

floor.03

Execution

Named control or algorithm ran

A declared algorithm, scanner, policy gate, or model call executed and the credential records the path and result.

floor.02

Witnessed

Designated human review

A human reviewer saw the declared artifact, recorded rationale, and signed or otherwise witnessed the step.

floor.01

Attestation

Opaque process, explicit claim

The workflow records that a declared step occurred, but cannot defend a stronger proof level. Weakest floor, still useful when labeled honestly.

§ 04 — Gaps

Silence is not a gap model. The credential records missing surface explicitly.

If part of the declared workflow was not instrumented, not reviewable, or not provable end to end, the credential should say so by code, scope, and reason.

Code
Name
Meaning

G-001

check_not_declared

A control referenced by the policy pack has no implementation in the runtime.

G-007

policy_pack_drift

The policy pack used at run time differs from the one declared for the workflow.

G-012

input_commit_mismatch

The committed input differs from the input hashed at evaluation.

G-017

visibility_opaque

A step ran, but the reviewer cannot independently validate the implementation path.

G-024

proof_level_missing

A check did not declare its proof level, so the run falls back to a weaker floor.

G-031

adapter_version_uncertain

The adapter wrapping an external system did not declare an exact version.

G-038

witness_not_recorded

Witnessed proof was claimed but no reviewer evidence was attached.

G-045

content_leaked_to_issuer

A signing request carried recoverable governed content and should be rejected.

§ 05 — Signing and timestamps

The artifact should verify later without relying on the origin dashboard.

A VPEC should not depend on a live SaaS screen to be meaningful. Signature material, timestamps, and public verification records are what let another party review the artifact after it has left the issuing system.

Issuer key

Ed25519 signature

The credential is signed over canonical bytes. The verifier checks the signature with the issuer public key identified by issuer_kid.

Time evidence

External timestamp

An RFC 3161 timestamp or equivalent external time witness can prove the credential hash existed before a specific time.

Append-only witness

Transparency log

A public transparency log entry can give relying parties another way to confirm the credential hash was not invented later.

Enterprise option

Customer-held keys

For sensitive environments, the customer key can become the verification root while Primust acts as issuance orchestration.

§ 06 — Verification

$ pip install primust-verify
$ primust verify ./run.vpec
✓ signature valid
✓ timestamp witnessed
✓ floor: execution
! 2 gaps declared

from primust_verify import verify
 
result = verify("./run.vpec")
assert result.floor == "execution"
assert result.surface >= 0.85
assert len(result.gaps) == 2

Verification is the reason the format matters. If the artifact cannot be checked later, the spec is only a serialization detail. If it can, the artifact becomes evidence another party can test.