Loading module
Resolving locale, route permissions, and workspace projection.
Kvary Evidence Standard (KES) — Specification v1
Boundary Disclaimer (Non-Operational / Non-Control)
KES is a read-only evidence and reference standard. It records and publishes structured claims, timestamps, hashes, and optional anchoring references. KES does not process transactions, approve or reject submissions, impose outcomes, assign roles, select winners, automate workflows, or manage logistics.
1. Definition
Kvary Evidence Standard (KES) is a compact, settlement-centric evidence format for publishing verifiable records about stakeholders, agricultural commodity batches, attestations/events, and outcomes.
KES is designed for:
- Deterministic projection: UIs can render consistent list/card/map/detail views from the same dataset.
- Evidence readability: Records are human-auditable and machine-parseable.
READ 2026-03-28T23:42:21.903Z
READ 2026-03-29T04:52:41.869Z
CORE STRICT SAFE DELETE AFTER RERUN REPORT
PUBLIC | DRAFT | v1.0.0
READ 2026-03-29T03:13:33.020Z
Integrity references: Hashes and optional anchoring proofs can be attached as references.2. Principles
- Settlement-safe semantics: the system publishes what was recorded (claims, attestations, outcomes as statements).
- No operational control: KES describes evidence; it is not a workflow engine.
- Minimal canonical types: small set of record types; consistent envelope.
- Deterministic rendering: the same inputs yield the same projections.
- Explicit provenance: who attests, when it was recorded, what it refers to.
3. Non-goals
KES explicitly does not provide:
- Approval or compliance-control logic
- Role assignment or permission systems
- Automated winner selection or bidding operations
- Logistics management, tracking, or scheduling automation
- “Progress tracking” as an operational function (only recorded evidence timeline)
4. Canonical Record Types
KES v1 defines four canonical record types:
- Stakeholder — an identity reference for a party that can publish or be referenced by evidence.
- Batch — an agricultural commodity batch reference record.
- Event/Attestation — a recorded statement tied to a batch (or other subject), optionally with integrity references.
- Outcome — a recorded outcome statement referencing prior evidence.
All records are carried inside a KES Envelope.
5. KES Envelope
An envelope wraps a single canonical record and provides consistent metadata.
5.1 Envelope fields
kesVersion (string, required)
envelopeId (string, required)
- Globally unique identifier for the envelope, e.g.,
"KES-ENV-2026-000123"
recordType (string, required)
- One of:
"stakeholder" | "batch" | "event" | "outcome"
record (object, required)
- The canonical record payload (see sections below).
createdAt (string, required)
- ISO 8601 timestamp of when the envelope was created.
publisher (object, required)
- Reference to the stakeholder who publishes the envelope.
integrity (object, optional)
- Integrity references (hashes, anchoring proof as reference only).
5.2 Envelope JSON example
{
"kesVersion": "1.0",
"envelopeId": "KES-ENV-2026-000123",
"recordType": "event",
"createdAt": "2026-02-15T12:00:00Z",
"publisher": {
"stakeholderId": "STKH-GE-0007",
"displayName": "Kvary Reference Publisher"
},
"integrity": {
"contentHash": "sha256:8b1a9953c4611296a827abf8c47804d7",
"anchoringProof": "ANCHOR-REF-2026-000123"
},
"record": {
"eventId": "EV-AU-2026-0001-04",
"eventType": "Quality test recorded",
"timestamp": "2026-02-12T15:00:00Z",
"subject": { "type": "batch", "batchId": "BATCH-AU-2026-0001" },
"statement": "Lab result reference recorded.",
"evidence": [{ "label": "labReference", "value": "LAB-REF-2026-STR-0001" }]
}
}
6. Stakeholder Record
A stakeholder is a reference identity used to attribute publication or attestations.
6.1 Stakeholder fields
stakeholderId (string, required)
- Stable ID, e.g.,
"STKH-GE-0007"
displayName (string, required)
- Institutional name for UI display.
stakeholderType (string, required)
- Suggested values:
"Farm" | "Cooperative" | "Lab" | "Carrier" | "Authority" | "Registry" | "Other"
jurisdiction (string, optional)
- Reference label only (no legal assertions), e.g.,
"GE"
contacts (object, optional)
- Reference-only contact info placeholders.
email (string, optional)phone (string, optional)
externalRefs (array, optional)
- External reference identifiers (reference only).
- Items:
{ "system": string, "id": string }
6.2 Stakeholder JSON example
{
"stakeholderId": "STKH-GE-0142",
"displayName": "Farm GE-SZS-0142",
"stakeholderType": "Farm",
"jurisdiction": "GE",
"externalRefs": [{ "system": "internal-farm-registry", "id": "FARM-GE-SZS-0142" }]
}
7. Batch Record (Agricultural Commodity Batch)
A batch record is a read-only reference descriptor for an agricultural commodity batch.
7.1 Batch fields
batchId (string, required)
commodity (object, required)
productName (string, required)variety (string, required)quantity (number, required)unit (string, required) — e.g., "kg" | "ton"
origin (object, required)
region (string, required)geoRef (string, optional) — reference-only (e.g., geohash label)
season (object, required)
harvestSeason (string, required)estimatedHarvestWindow (string, optional) — recorded range label.
delivery (object, optional)
- Declared delivery terms as references.
startDate (string, optional)periodDays (number, optional)incoterm (string, optional)notes (string, optional)
settlementState (string, required)
- Settlement-safe label, e.g.,
"Announcement recorded".
createdAt (string, required)
7.2 Batch JSON example
{
"batchId": "BATCH-AU-2026-0001",
"commodity": {
"productName": "Strawberry",
"variety": "Albion",
"quantity": 12,
"unit": "ton"
},
"origin": {
"region": "Samegrelo-Zemo Svaneti",
"geoRef": "u0j0d9v"
},
"season": {
"harvestSeason": "2025 Autumn",
"estimatedHarvestWindow": "2025-09-10 to 2025-10-05 (recorded)"
},
"delivery": {
"startDate": "2026-05-01",
"periodDays": 100,
"incoterm": "EXW",
"notes": "Staged pickup schedule (recorded)."
},
"settlementState": "Announcement recorded",
"createdAt": "2026-02-05T10:00:00Z"
}
8. Event / Attestation Record
An event/attestation is a recorded statement about a subject (usually a batch), optionally containing evidence references.
8.1 Event fields
eventId (string, required)
eventType (string, required)
- Example:
"Farm inspection recorded", "Quality test recorded".
timestamp (string, required)
subject (object, required)
type (string, required) — e.g., "batch"batchId (string, required when type is batch)
attester (object, optional)
- Stakeholder reference.
stakeholderId (string, required)displayName (string, optional)
statement (string, required)
evidence (array, optional)
- List of evidence references.
- Items:
{ "label": string, "value": string }
8.2 Event JSON example
{
"eventId": "EV-AU-2026-0001-04",
"eventType": "Quality test recorded",
"timestamp": "2026-02-12T15:00:00Z",
"subject": { "type": "batch", "batchId": "BATCH-AU-2026-0001" },
"attester": { "stakeholderId": "STKH-GE-LAB-0003", "displayName": "Reference Lab" },
"statement": "A lab reference was recorded for this batch.",
"evidence": [
{ "label": "labReference", "value": "LAB-REF-2026-STR-0001" },
{ "label": "evidenceHash", "value": "sha256:STR-0001-QT" }
]
}
9. Outcome Record
An outcome is a recorded outcome statement that references prior events/attestations. It is a publication of what was recorded.
9.1 Outcome fields
outcomeId (string, required)timestamp (string, required)subject (object, required)
- Typically
{ "type": "batch", "batchId": "..." }
summary (string, required)
- Human-readable statement.
references (array, optional)
- References to evidence envelopes, events, or external records.
- Items:
{ "type": "envelope" | "event" | "external", "id": string }
settlementState (string, required)
- Example:
"Outcome recorded".
9.2 Outcome JSON example
{
"outcomeId": "OUT-AU-2026-0001",
"timestamp": "2026-04-21T12:00:00Z",
"subject": { "type": "batch", "batchId": "BATCH-AU-2026-0001" },
"summary": "An outcome statement was recorded for the batch.",
"references": [
{ "type": "event", "id": "EV-AU-2026-0001-04" },
{ "type": "external", "id": "ANCHOR-REF-2026-000123" }
],
"settlementState": "Outcome recorded"
}
10. Security and Integrity (Reference-Only)
KES supports integrity references to help readers verify content consistency.
Integrity fields do not imply adjudication. They support reference-level verification and audit.
11. Versioning Rules
kesVersion uses semantic versioning: MAJOR.MINOR.- MAJOR increments when:
- Canonical record types change incompatibly, or
- Required fields are removed/renamed.
- MINOR increments when:
- Optional fields are added, or
- New enumerated values are added in a backward-compatible way.
- Producers should:
- Always include
kesVersion in every envelope.
- Avoid changing the meaning of existing fields across minor versions.
- Consumers should:
- Treat unknown optional fields as ignorable.
- Render deterministic projections using only recognized fields.