dispute_claimChargebacks, insurance claims, invoice disputes, commercial disagreements, demurrage, force majeure. Something is contested.
Case file format — PDF bundle
Portable Decision-Ready Case File
The .pdf file is the portable, JSON-first, human-readable case container. It carries the case — pain path, claims, evidence, missing items, and requested action. ERF is the separate trust / receipt / verification layer.
JSON-first
Human-readable
Machine-parseable
Not a ZIP
Portable · no lock-in
Critical distinction
.pdf is the case file. ERF is the receipt / trust layer. They are not the same.
.VRM — CASE FILE
- Carries the case: pain path, claims, evidence, missing items
- Human-readable, portable JSON
- Exists before and during case building
- Has review_state (intake → decision_ready)
- Contains requested_action for reviewer
- Can be a starter (draft) or decision-ready (complete)
ERF — RECEIPT / TRUST LAYER
- Carries the trust: canonical hash, ed25519 signature, timestamp
- Created at sealing — not before
- Has integrity_state (unsealed → sealed → verified → anchored)
- Powers the verify URL and QR code
- Separate from the case content
- PASS / Declared / Unverified labels live here
Do NOT mix these. .pdf = what happened and what the reviewer must decide. ERF = proof that the record has not changed since sealing.
.pdf v1.1 — full format
Complete case file structure.
{
// ── Core identity ──────────────────────────────────────────
"vrm_version": "1.1",
"id": "vry_01HQZX…", // stable case ID
// ── Pain-path classification ────────────────────────────────
"case_path": "dispute_claim", // dispute_claim | handover_acceptance | review_qualification
"family": "woo", // woo | insurance | vendor_review | maritime_supplychain | broker | generic
"profile": "decision_ready", // starter | decision_ready
// ── Case content ────────────────────────────────────────────
"subject": "Chargeback on order #4521 — item not received",
"parties": {
"sender": "Acme Shop",
"reviewer": "Bank disputes team"
},
"amount": { "value": 149.00, "currency": "USD" },
// ── Review state (separate from integrity) ──────────────────
"review_state": "decision_ready", // intake | organized | missing_evidence | decision_ready
"integrity_state": "sealed", // unsealed | sealed | verified | anchored
// ── Claims ──────────────────────────────────────────────────
"claims": [
{
"id": "c1",
"statement": "Item was shipped and delivered on 14 Jan 2025",
"support_state": "supported", // supported | sender_stated | missing | contradicted
"evidence_refs": ["e1", "e2"]
},
{
"id": "c2",
"statement": "Customer was notified by email on order date",
"support_state": "sender_stated",
"evidence_refs": []
}
],
// ── Evidence items ──────────────────────────────────────────
"evidence_items": [
{
"id": "e1",
"label": "Carrier tracking screenshot",
"status": "PASS", // PASS | Declared | Unverified
"file_hash": "sha256:3a4b5c…",
"filename": "4521_tracking_UPS_2025-01-14.jpg"
},
{
"id": "e2",
"label": "Delivery confirmation",
"status": "Declared",
"note": "Confirmed via UPS portal — screenshot not attached"
}
],
// ── Missing items (gap analysis) ───────────────────────────
"missing_items": [
{
"label": "Order confirmation email",
"tier": "MUST",
"note": "Required for DNR — proves customer email and shipping address"
}
],
// ── Requested action for reviewer ──────────────────────────
"requested_action": {
"type": "review", // review | acknowledge | accept_handover | request_missing_item | assess_claim
"question": "Review the attached evidence and determine whether the chargeback is warranted."
},
// ── Timeline ────────────────────────────────────────────────
"timeline": [
{ "date": "2025-01-10", "event": "Order placed", "key": true },
{ "date": "2025-01-11", "event": "Order shipped via UPS", "key": true },
{ "date": "2025-01-14", "event": "Delivery confirmed by carrier", "key": true },
{ "date": "2025-01-21", "event": "Chargeback filed", "key": true }
],
// ── Render / view wrapper (Vraimony imprint layer) ─────────
"render_manifest": {
"available_views": ["reviewer_page", "summary_sheet", "pdf", "json"],
"branding_mode": "imprint", // imprint | white_label | none
"imprint_text": "Packaged with Vraimony", // appears in footer of generated wrapper layers only
"imprint_url": "https://www.vraimony.com"
},
// ── Lineage / revision ──────────────────────────────────────
"supersedes": null, // previous case ID if this replaces an earlier record
"revision_reason": null,
// ── Extensions (family-specific, does not pollute core) ────
"extensions": {
"woo": {
"order_id": "#4521",
"reason_code": "dnr",
"payment_gateway": "Stripe",
"tracking_number": "1Z999AA…"
}
},
// ── Metadata ────────────────────────────────────────────────
"packaged_by": "vraimony-sdk/2.0",
"created_at": "2025-01-21T14:32:00Z",
"erf_ref": "erf://vry_01HQZX…" // reference to ERF trust layer (separate file)
}
Format rules
What .pdf must always be. What it must never become.
✓ Always
- JSON — plain text, no binary wrapper
- Portable — readable in any text editor
- Human-readable — no encoded opaque blobs
- Versioned — vrm_version field always present
- Separate from ERF — case file is not the receipt
- Free vs paid differ in depth (profile field), not format
✕ Never
- Not a ZIP — binary bundling belongs elsewhere
- Not a receipt — ERF handles trust/signing
- No pricing / checkout logic inside .pdf
- No separate file formats for free vs paid
- No imprint over original evidence files
- No opaque encoded claim structures
case_path — pain-path classification
Three values. Consistent across all families.
handover_acceptanceDelivery acceptance, project handover, milestone completion, supplier handoff, cargo handover. Something is being transferred.
review_qualificationVendor review, procurement qualification, broker evidence request, SIG/CAIQ, due diligence. Outside party must review before decision.
State fields — review vs integrity
Two separate state dimensions. Do not conflate them.
review_state — case readinessintake — facts collected, not yet organisedorganized — timeline and claims structuredmissing_evidence — gaps identified, not yet filleddecision_ready — complete, ready for outside reviewintegrity_state — trust layer (ERF)unsealed — local draft, not yet submittedsealed — signed, timestamped, tamper-evidentverified — integrity confirmed by verify surfaceanchored — additional external timestamp anchorA case can be decision_ready (review state) before it is sealed (integrity state). Sealing is the act of locking — it does not make the case decision-ready.
Vraimony imprint — where it goes and where it does not
Imprint only on wrapper layers. Never on original evidence.
✓ Appropriate imprint locations
- Footer of generated summary sheets
- Footer of reviewer-facing case page
- Footer of exported PDF wrapper layer
- render_manifest.imprint_text field in .pdf
- Cover note templates ("Packaged with Vraimony")
✕ Never imprint on
- Original screenshots or evidence files
- Invoices, contracts, or third-party documents
- Customer-visible communications
- Anything that could appear manipulated
- Original evidence metadata or EXIF data
The imprint must remain clearly secondary. It signals who packaged the record — not who created the underlying evidence. The distinction is non-negotiable.
Build your first .pdf