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.
• 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:

1. Stakeholder — an identity reference for a party that can publish or be referenced by evidence.
2. Batch — an agricultural commodity batch reference record.
3. Event/Attestation — a recorded statement tied to a batch (or other subject), optionally with integrity references.
4. 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)
  • Example: "1.0"
• 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)
  • Stable reference ID.
• 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)
  • Recorded timestamp only.

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)
  • Stable ID.
• eventType (string, required)
  • Example: "Farm inspection recorded", "Quality test recorded".
• timestamp (string, required)
  • ISO 8601 timestamp.
• 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)
  • Human-readable claim.
• 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.

• contentHash

  • A hash of the canonicalized envelope content (e.g., SHA-256).
  • Used for reference verification and reproducible projections.

• evidenceHash (optional, inside event evidence)

  • A hash reference for an external artifact (e.g., lab PDF), without embedding the artifact.

• anchoringProof

  • A reference string that points to an anchoring statement elsewhere (e.g., a settlement registry record).
  • Not a guarantee of finality or compliance control; it is an informational pointer.

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.