Explanation

The Case Model

This page explains the objects that make up a Vultron coordination case, what each one is for, and how they relate to each other. It describes their structure, not their fields: the field-by-field listing and a class diagram are in Case Model Fields.

The case as distributed shared state

A Vultron case is a distributed coordination object. Multiple independent organizations — a Reporter, a Vendor, a Coordinator — each maintain their own local copy of the case's state. They keep those copies in step by exchanging ActivityStreams 2.0 messages.

One participant, the CASE_MANAGER, keeps the authoritative history of the case: an append-only, hash-chained ledger. Every other participant holds a replica that converges on that ledger as the CASE_MANAGER sends it each new entry in an Announce(CaseLedgerEntry) message. The CASE_MANAGER and the Case Ledger explains how.

`VulnerabilityCase`

VulnerabilityCase is the object that represents a coordination case. It gathers everything the case is about: its participants, the reports it covers, its status history, its embargo, and the hash that anchors its ledger.

VulnerabilityCase does not carry Report Management (RM) state directly — that belongs to each participant, through their ParticipantStatus history. Only Embargo Management (EM) state and the case-wide Publication/eXploit/Active-attacks (PXA) state are recorded at the case level, through the CaseStatus history.

Case Actor

ActivityStreams 2.0 defines five actor types: Person, Organization, Group, Application, and Service. A Case Actor is a Service actor — it represents software infrastructure, not a human or organizational CVD stakeholder. The prototype has no dedicated class for it: it is an ordinary VultronService named CaseActor.

In the prototype, each case has one Case Actor, and it is the participant that holds the CASE_MANAGER role. It is also a CaseParticipant (as a CaseActorParticipant, per ADR-0051): it holds both CVDRole.COORDINATOR and CVDRole.CASE_MANAGER and moves through the RM states like every other participant. Embargo proposals, status updates, notes, and participant invitations all go to it, so that the ledger captures a causally ordered record of the whole coordination.

The CaseActor name and its .../actors/case-actor URL are provisioning conveniences and carry no protocol meaning. Authority follows the role, so no protocol logic may read that name, that URL shape, or where an actor is hosted as evidence of who the authority is (ADR-0088). An ordinary participant that holds CVDRole.CASE_MANAGER is the authority just as fully as a spawned Service actor is.

Do not confuse the CASE_MANAGER role (the role that authorizes ledger writes) with the CASE_OWNER role (the participant who makes decisions about the case).

`CaseParticipant`

A CaseParticipant binds an actor (its attributed_to field) to their roles and protocol state within one case. One CaseParticipant record exists for each actor engaged in a case. Because a single actor may participate in many cases and hold different roles in each, CaseParticipant scopes an actor's obligations and history to a single coordination context.

A participant record holds the actor's roles in the case, the actor's status history, and where the actor stands on the case's embargo.

Status objects

Vultron tracks protocol state through immutable snapshots rather than mutable fields. A change appends a new snapshot to a history list; nothing is changed in place. This makes the full state history auditable and replayable.

There are two kinds of snapshot:

A CaseStatus records the state of the case as a whole: its EM state and its PXA state. The case keeps a history of them.
A ParticipantStatus records one participant's state: its RM state, and, where the participant's roles call for it, its fix-readiness and fix-deployment state. Each participant keeps its own history of them.

A participant's embargo consent is not part of any snapshot. It is one row per embargo in the case's embargo register, kept on the participant's record and changed only through the case ledger (CM-18-006).

The difference between the state of the case as a whole and the state of each participant is explained in Model Interactions.

Dimension objects

Each snapshot is made of Dimension Objects (ADR-0036): small, immutable objects that each own exactly one state machine. EM, PXA, RM, fix readiness and fix deployment each have one. Because each dimension is its own object, it can be compared, serialized, and checked on its own.

Dimension state machines

See Process Models for the EM, RM, and CS state machines and their transition rules.

`CVDRole`

CVDRole names the roles a participant can hold in a case. Each value is a single role, and a participant may hold several at once.

Some roles describe a participant's part in the coordination: REPORTER, VENDOR, DEPLOYER, COORDINATOR, OBSERVER, and CVE_NUMBERING_AUTHORITY. Two describe authority over the case itself: CASE_OWNER decides for the case, and CASE_MANAGER writes its history. There is no Finder role (ADR-0078): an actor that discovers and reports a vulnerability holds REPORTER, and who found it is recorded on the report or in a case note. The full list, with what each role obliges, is in Case Model Fields.

How the objects relate

A VulnerabilityCase aggregates:

One CaseParticipant per engaged actor, each with an append-only ParticipantStatus history
An append-only CaseStatus history recording EM and PXA state over time
An append-only case ledger anchored at the case's genesis hash

The participant holding CASE_MANAGER — in the prototype, the Case Actor — writes the ledger for the case and relays messages between participants.