Complete specification — invariants, schemas, APIs, stage types, and gap taxonomy.
System Invariants
No content transit. Raw inputs/outputs, model weights, PII never leave the customer environment. Only commitment hashes transit to api.primust.com. For Bounded Inference: only merkle_root transits — per-operator outputs stay in customer environment.
Fail open, fail honest. Primust failures do not block customer pipelines. All failures become gaps.
Weakest-link proof level.proof_level_floor = minimum across all records. DERIVED — never set manually.
Gaps recorded honestly.detectable_from_surface: false means "unknown" not "ungoverned."
Domain-neutral core. No agent_id, tool_name, trace, pipeline_id in core schema.
Promotion gates in code. P1 → SHAREABLE impossible without override + watermark.
Manifest hash per record. Every CheckExecutionRecord stores manifest_hash at time of execution.
Customer private key never leaves customer environment. BYOK signing: Primust calls customer signing endpoint with payload.
upstream_vpec_verify proof ceiling is Mathematical. Ed25519 verification is deterministic. Never downgrade.
Bounded Inference profiles are Primust-signed. Profile signature verifiable offline against Primust public key. Tampered profile is detectable.
XGBoost, RandomForest, logistic regression, linear SVM. Decision path committed as arithmetic constraints. Auto-inferred by SDK from sklearn/xgboost object types.
Never transits Primust: raw inputs/outputs, model weights, individual AgentActivityRecords, reviewer display content or rationale text, matched PII/secret values, per-operator ML outputs (only merkle_root for Bounded Inference), explanation text (only poseidon2 commitment hash), actual bias audit disparity values (only commitment hash).
API Endpoints
Base URL: https://api.primust.com. SDK endpoints use Authorization: Bearer pk_sb_xxx (sandbox) or pk_live_xxx (production). Dashboard endpoints use JWT.
Run Lifecycle
Method
Endpoint
Description
POST
/api/v1/runs
Start a run. Body: workflow_id, policy_pack_id. Returns run_id, policy_snapshot_hash.
GET
/api/v1/runs/:id
Get run status and summary.
POST
/api/v1/runs/:id/records
Commit a check execution record. Returns record_id, chain_hash.
POST
/api/v1/runs/:id/close
Seal the run — triggers VPEC issuance. Returns the VPEC.
VPECs & Evidence Packs
Method
Endpoint
Description
GET
/api/v1/vpecs/:id
Retrieve a VPEC by ID.
POST
/api/v1/packs
Assemble Evidence Pack from VPEC IDs.
POST
/api/v1/evidence-packs/:id/report
Generate signed PDF audit report. P1 packs watermarked.
Model Profile Registry
Method
Endpoint
Description
GET
/api/v1/registry/profiles
List all available profiles. Optional ?model_hash= filter — includes operator thresholds when filtered.
GET
/api/v1/registry/lookup?hash={onnx_model_hash}
Lookup profile by model hash. Returns profile_id or 404.
POST
/api/v1/registry/calibration-requests
Submit a model for calibration. Returns request_id. SLA: 7d standard, 48h Enterprise.
Analytics
Method
Endpoint
Description
GET
/api/v1/analytics/check-summary
Per check_id aggregates. Includes upgrade_available signal, inferred_ceiling, six-level proof distribution.
GET
/api/v1/analytics/enforcement-summary
Governance decision aggregates from VPEC governance_decision_summary fields — not activity stores.
GET
/api/v1/analytics/proof-trend
Per-day provable_surface_breakdown. Period: 30|90|365 days. Includes drift_events count.
Incident Packages
Method
Endpoint
Description
POST
/api/v1/incident-packages
Assemble signed incident package for a run_id. Returns package_id, download_url. Package signed by Ed25519 + RFC 3161.
GET
/api/v1/incident-packages
List incident packages for org. Optional ?workflow_id= filter.
Policy & Manifests
Method
Endpoint
Description
GET
/api/v1/policy/bundles
List all policy bundles (7 built-in + org custom).
{
"vpec_id": "vpec_a1b2c3...",
"schema_version": "6.0.0",
"org_id": "org_x9y8z7",
"run_id": "run_8f3a2b...",
"workflow_id": "loan-underwriting-v3",
"policy_snapshot_hash": "sha256:...",
"environment": "production", // "sandbox" | "production" — NOT test_mode
"partial": false,
"state": "signed",
"proof_level_floor": "operator_bound", // weakest-link, DERIVED — never set manually
"provable_surface": 0.87, // hero metric — NOT coverage_verified_pct
"provable_surface_breakdown": {
"mathematical": 0.52,
"verifiable_inference": 0.00,
"bounded_inference": 0.18, // NEW in v6 — Bounded Inference share
"execution": 0.12,
"witnessed": 0.05,
"attestation": 0.00
},
"provable_surface_pending": 0.00, // verifiable_inference proofs in-flight
"provable_surface_ungoverned": 0.05, // manifest checks with no record this run
"provable_surface_basis": "executed_records", // | "manifest_checks"
"provable_surface_suppressed": false,
"gaps": [], // NOT governance_gaps — that name is banned
"merkle_root": "sha256:...", // present on bound_committed_inference VPECs only
"profile_id": "primust/distilbert-class/v1.2.0", // same
"issuer": { "issuer_id": "primust.com", "issuer_type": "platform" },
"signature": {
"algorithm": "Ed25519",
"public_key_id": "key_m3n4o5",
"trust_anchor_url": "https://primust.com/.well-known/primust-pubkey.pem",
"value": "base64..."
},
"timestamp_anchor": { "method": "rfc3161", "value": "base64..." },
"issued_at": "2026-03-17T14:23:01Z"
}
Banned field names
proof_level (single field) → use proof_level_floor governance_gaps → use gaps coverage_verified_pct → use provable_surface proof_distribution / proof_level_breakdown → use provable_surface_breakdown test_mode → use environment: "sandbox" pk_test_xxx → use pk_sb_xxx
Data crossed an external boundary without governance instrumentation
lineage_token_missing
High
Delegation handoff missing lineage token
admission_gate_override
Critical
Admission gate bypassed or overridden
check_timing_suspect
Medium
Review duration below minimum threshold — possible rubber-stamping
reviewer_credential_invalid
Critical
Reviewer credential failed validation (expired, revoked, or malformed)
witnessed_display_missing
High
Witnessed record lacks display_hash proving what reviewer saw
witnessed_rationale_missing
High
Witnessed record lacks rationale_hash
witnessed_timestamp_invalid
High
Witnessed record has invalid or tampered timestamp
deterministic_consistency_violation
Critical
Same input produced different check results across runs
skip_rationale_missing
High
Check skipped without skip_rationale_hash
policy_config_drift
Medium
Policy configuration changed between manifest snapshot and execution
proof_level_floor_breach
Critical
Record proof level below policy bundle's declared minimum floor
zkml_proof_pending_timeout
Medium
EZKL proof generation timed out
zkml_proof_failed
High
EZKL proof generation failed
system_error
High
Unrecoverable system error during governance processing
sla_breach
Medium
Governance SLA target not met
explanation_missing
Medium
AI decision lacks explanation commitment (required when compliance_requirements set)
bias_audit_missing
High
Decision on protected categories lacks bias audit record
System Availability (1)
gap_type
Severity
Description
system_unavailable
High
Primust API unreachable — SDK queued locally, queue lost or TTL expired. Distinct from system_error.
Unstructured Check (1)
gap_type
Severity
Notes
archetype_unmapped
Medium
custom_check VPEC exists but compliance officer has not mapped it. Auto-resolves on officer mapping.
Cross-Org Verification (7)
gap_type
Severity
upstream_vpec_invalid_signature
Critical
upstream_vpec_sandbox
High
upstream_vpec_key_revoked
High
upstream_vpec_insufficient_proof_level
High
upstream_vpec_missing_claim
Medium
upstream_vpec_issuer_mismatch
Critical
upstream_vpec_missing
High
Profile Registry (1 — new in v15)
gap_type
Severity
Description
model_profile_missing
Medium
bound_committed_inference stage type declared or inferred but no Primust-signed profile exists for onnx_model_hash. Check falls back to Execution. Auto-resolves when Primust publishes a profile or customer submits for calibration. SDK advisory: "upgrade to Bounded Inference at app.primust.com/policy/registry."
Connector-Specific (16)
Pattern: {platform}_api_error (High) = vendor API unreachable or 5xx. {platform}_auth_failure (Critical) = vendor API 401/403.
Platforms: complyadvantage, actimize, blaze, odm, falcon, pega, wolters_kluwer, guidewire — each with _api_error and _auth_failure variants.
Not gaps
check_candidate findings from primust scan are scan advisories — NOT gap types. They do not appear in the VPEC gaps array and do not affect provable_surface.
Package Inventory
SDKs
Package
Language
Registry
Status
primust
Python
PyPI
Live 1.0.0
primust-ai
Python
PyPI
Live 1.0.0 — autoinstrument(), autoinstrument-level model detection
@primust/sdk
TypeScript
npm
Live 1.0.0
com.primust:primust-sdk
Java
Maven Central
Published 1.0.0
Open Source
Package
Language
License
Description
primust-verify
Python
Apache-2.0
Offline VPEC verifier CLI. Free forever. No account required.
primust-checks
Python
Apache-2.0
Open-source check harness. Run checks locally, prove they ran with Primust. 8 built-in checks, 7 bundles.
AI Framework Adapters
Package
Target
Tests
Status
primust-langgraph
LangGraph
14
Live 1.0.0
primust-openai-agents
OpenAI Agents SDK
14
Live 1.0.0
primust-google-adk
Google ADK
14
Live 1.0.0
primust-otel
OpenTelemetry
14
Live 1.0.0
@primust/otel
OpenTelemetry (TS)
—
Live 1.0.0
Rule Engine Adapters (Mathematical ceiling)
Package
Target
Proof ceiling
Status
primust-cedar
AWS Cedar
Mathematical (eval())
Maven Central 1.0.1. GREEN.
primust-drools
Red Hat Drools
Mathematical (eval() + Map facts)
Maven Central 1.0.1. GREEN.
primust-odm
IBM ODM
Mathematical (eval() via IlrSessionFactory)
Maven Central 1.1.0. GREEN. Real ODM runtime verified.