Skip to content
Explanation

Propose Case

The specification governs

This page explains the design of the Vultron Protocol. It is informative: the normative text is the Vultron Protocol Specification. Where this page and the specification differ, the specification governs.

Proposing a case is how an actor asks a service to open and manage a coordination case on its behalf. The proposing actor does not create the case itself. It sends a proposal and waits. The service that accepts becomes the single-writer authority for everything that follows.

This page explains three things:

  • Why the protocol delegates case creation instead of doing it locally.
  • What the accepting service does for the proposer.
  • Where the decision to accept or decline lives.

What starts it

An actor that holds a report and wants it coordinated as a case sends Create(CaseProposal) to a case actor service. That service is the provisioning endpoint configured as case_actor_service_url (CP-04-001, CP-08-002). In the reference implementation, this happens in the create_case trigger path. The actor records a local case, publishes the case actor identity it will address, and emits the proposal.

The proposal carries the report inline. The reference implementation does not permit a URI reference here, because the receiving service fetches only a few objects by reference, and a report is not one of them (CP-01-004, AKM-03-003). The proposal also carries the provenance of the report: which Offer(VulnerabilityReport) delivered it, and from whom. The accepting service cannot reconstruct that provenance, and it needs it for the first ledger entry (CP-01-007, CP-01-019).

The proposal is addressed to the service's own actor identity, never to an identity derived per case or per report (CP-04-003). That identity exists before the report does. The service does not exist yet as a per-case actor. The proposal asks for that.

In this implementation, that identity is {case_actor_service_url}/actors/case-actor, one per case-actor container (CP-04-005). That one identity per container holds many cases (BT-10-002). An activity's context names the case that the activity concerns. The address does not name the case.

An address derived from the report could not be provisioned before the report arrived. The proposal would then meet a permanent 404, and the round-trip would never start.

The service URL comes from the actor's configuration, not from the server's own base URL. In a container deployment, that configuration is VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL, one of the settings in the Node Configuration Reference. The server's own base URL happens to work when both actors share a container. When they do not share a container, a proposal sent to that URL goes back to the proposer.

Why creation is delegated rather than done locally

An actor can hold a local case object. What it cannot do alone is be the single-writer authority for a case that other organizations will replicate from. The CVDRole.CASE_MANAGER role carries that authority, and the canonical ledger every Participant converges on is written by whoever holds it (ADR-0041). Delegating creation is how the authority gets established as a fact other actors can recognize, rather than a claim the proposer makes about itself.


The mechanical path

Accepting a proposal is the largest single cascade in the protocol. The accepting service does the steps below, and the order is not interchangeable.

Step What it establishes
Resolve or create the case A redelivered proposal (same proposal identifier) reuses its case rather than creating a second (CP-05-006, CP-05-013); a new proposal identifier is a new request, and the case is reused only for the proposer that owns it (CP-05-008, CP-05-017, CP-05-020). A new case starts with its report's name and summary (CSAF-03-006). Where the report is silent, a Common Security Advisory Framework (CSAF) Vulnerability Report on the carried Offer fills them, can mark the vulnerability public, its exploit public or attacks observed, and can propose an embargo end (CSAF-02-001, CSAF-03). The case also takes a vulnerability item for each vulnerability the CSAF document names, and a case reference for each of its document-level references (CSAF-03-008, CSAF-03-009).
Store the inline report Everything downstream derives from it — the reporter Participant, its ledger entry, the consent seed
Add itself as Participant COORDINATOR and CASE_MANAGER, so the authority is in the roster
Add the proposing actor CASE_OWNER at RM.RECEIVED, plus the roles its proposal states in proposerCaseRoles (CP-09-007) — never the accepting service's own configuration
Add the reporter At RM.ACCEPTED — the reporter has already accepted, by reporting
Initialize the default embargo A case begins embargoed rather than open (EP-04-001), unless it starts already public, exploited or attacked, when it begins with no embargo (EP-04-020)
Seed the owner's consent An AGREED consent row for the default embargo, without an invitation round-trip
Seed the reporter's consent An AGREED consent row — submitting a report is implicit consent (ADR-0048)
Emit Accept(CaseProposal) The proposer learns its request succeeded
Emit Create(VulnerabilityCase) The proposer receives the case replica, with Participants, vulnerability items and case references inline
Commit the canonical ledger entries The case's history starts here, and each entry fans out to every Participant
Relay a contested creation's revision When the reporter and the owner both proposed terms, the longer ones are sent as an Invite(EmbargoEvent) to the party whose terms won (EP-04-011, EP-04-027)

The ledger commits come after both emissions for a reason that is easy to miss. Each commit sends its entry to every Participant through the same first-in-first-out outbox that carries the Create(VulnerabilityCase). A commit placed ahead of the Create therefore gives every Participant ledger entries for a case it does not hold yet. Each such entry takes the pre-genesis recovery path — buffer, then one Reject per case asking for a replay from genesis — while the replica waits behind the whole fan-out (CP-09-009). When the service emits the case first, that recovery path is what it was designed to be: a backstop for transport reordering, not the normal route.

The revision relay comes after the ledger commits, because no modification of the case may start before its initialization is complete (CM-14-014).

Case creation is one act. Every step from the case to the revision relay is written in one storage transaction. If a step fails, the transaction keeps none of them, including the queued Accept, Create and Invite (CLP-07-015, CLP-07-016).

Delivery learns of the queued messages only after that transaction commits. So a failed creation sends nothing, and a redelivered proposal starts again from the beginning. The service stores no marker for a later run to finish the creation.

The two emissions are queued together or not at all. The Accept is irrevocable once sent: the service has committed to managing the case. An Accept with no Create behind it would tell the proposer of a case that nothing announces. So the service queues neither one without the other (CP-05-005).

After both are queued, the outbox retries the delivery of each one until it succeeds or its attempts run out (CP-05-011). The Create takes an id derived from the proposal. A redelivery that finds the case already announced announces nothing again. A redelivery that finds a Create for a different case under that id fails, instead of leaving the new case unannounced. Sending a second Accept would tell the proposer it had been accepted twice, and there is no such thing.


Where judgment enters

One call-out point governs this use case: EvaluateCaseProposal (Evaluator), the admission decision (CP-05-002). Evaluator is one of the four capability shapes (ADR-0097, BT-18-013). The backend that answers it is injected as a swappable factory (ADR-0025). So a deployment supplies its own admission policy without editing the tree. Its service contract is in the Capability Model.

It is the only place a deployment can express admission policy. Admission policy answers three things:

  • Whether the proposing actor is one this service will work for.
  • Whether that actor already holds more open cases than the service will carry.
  • Whether the inline report is substantive enough to be worth coordinating.

All of that lives here or nowhere.

The decision comes before every step above, and that placement is the interesting part. A refusal has to happen before the case exists. Suppose a service created the case, committed ledger entries, and then declined. It would tell the proposer "no" while it holds a case that no Participant will ever converge on. That is the canonical-versus-replica divergence that CLP-10-009 exists to prevent.

When the service declines, it sends Reject(CaseProposal) with the proposal inline, and creates nothing (CP-05-004). The proposing actor records the refusal (CP-06-003, CP-06-004). It records a reply only from the actor that it addressed the proposal to. It refuses a reply from any other actor, and its records stay unchanged (CP-06-005, CP-06-008). Once a case exists for the report, no reply replaces the case's trusted CASE_MANAGER (CP-06-007).

The service records and queues the refusal in one storage transaction. A refusal that fails stops the whole delivery. A decline that cannot be queued does not silently become an acceptance. The service keeps neither the decision nor the Reject, and it does not try the accept path. So the irrevocability that CP-05-004 and CP-05-012 rely on holds in both directions.

A reader should expect this consequence. Suppose a service decided "no" and then failed to say so. It reports a processing failure, and it decides again on the next delivery. It never creates the case.

Two properties of the guarding are worth stating, because each is a way a refusal gate can be defeated rather than merely fail.

The guards key on the proposal, never on the report. A report identifier arrives inside the proposal, which means the sender chooses it, and two proposals may name one report.

Consider a guard that asks "does a case already exist for this report?" That guard answers "already handled" for a proposal that was never judged at all. It admits that proposal as a duplicate of the earlier one, and policy is never consulted. So the service writes its own per-proposal record when it begins to admit, and it asks that record instead.

"We already told them" comes from that record too, not from the outbound queue. A refusal leaves the queue after it is delivered. So a queue-based check cannot distinguish a refusal that was delivered from one that was never sent. That check then re-sends the refusal on every later delivery of the same proposal. Recording the identifier of the refusal that was actually queued gives the service three answers instead of two: undecided, decided but not yet told, and told.

Under the deterministic default, the service admits. That default is deliberate. A service that an actor was configured to trust should not silently refuse. Also, if the service refused by default, no unconfigured deployment could ever open a case.

The default is also not the conservative-default case that BT-23-012 governs. Accepting creates a new case in which the proposer becomes the owner, and no other party's agreed state changes.

The reason for a refusal is a separate matter. CP-06-004 requires the proposer to surface one where present. Nothing yet carries a reason from the admission decision onto the wire.

An admission backend answers yes, no or error (ADR-0183). A no carries a reason, but the decline record does not read it yet, so the Reject carries no summary and a proposer records the refusal without an explanation (#6077).

A backend whose policy service is unreachable answers error. The proposal is then not judged: it stays in holding, and the next delivery decides it. A backend that answers no for an outage instead produces a permanent refusal.

An already-answered proposal is never re-adjudicated. A duplicate delivery of the same proposal reuses the existing case and does not decide again. The reason is that a later "decline" would contradict an Accept already sent. CP-05-006 goes further: the stored Accept must be re-sent unchanged, with its original identifier. So a proposer whose copy was lost converges instead of waiting forever.

The reference implementation does this. The Accept takes an id derived from the proposal. A duplicate proposal queues the stored Accept again under that id, unless it is still waiting in the outbox.

The CASE_MANAGER finds the case through the Accept it stored for the proposal, not only through the case's current owner. So a former owner's redelivery after an ownership transfer creates no second case. It also does not make the former owner CASE_OWNER again (CM-21-001).

The exception is a case that is fully closed, that is, its ledger holds the CASE_MANAGER's own status entry reaching RM CLOSED. The stored Accept would lead into the accept path, which writes to the case. A closed case accepts no further writes (CM-23-013). So the CASE_MANAGER answers the duplicate with Reject(CaseProposal) instead. It commits no ledger entry and changes no case or participant state.

The Reject declines only the redelivery. The stored Accept stands, and the proposer learns only that nothing more will be done for the proposal. The same lookup gives a former owner this answer after an ownership transfer.

Only the proposal's author can redeliver it. The sender chooses the proposal identifier. So the CASE_MANAGER refuses a delivery whose identifier it recorded for another proposer, and it writes and sends nothing for it (CP-05-010, CP-05-022). The proposer-side deadline that lets a proposer give up on a lost reply (CP-05-007) is not yet implemented (#2890).

A proposal under a new identifier is a new request, even when it names a report that already has a case (CP-05-008). It goes through the admission decision. It gets its own Accept or Reject, not the earlier proposal's stored answer (CP-05-016).

What happens to the case depends on who asks. The proposer that owns the case gets that case back. The Accept's result names it, and no second case is created. The case is not announced or recorded in the ledger a second time.

Any other proposer gets a separate case of its own and is not added to the first one (CP-05-020). The reason is that the sender chooses the report identifier, and that identifier does not say whose case it is.

When the owner's case is fully closed, the owner's new proposal is declined with Reject(CaseProposal), and nothing is written for the case (CP-05-018, CP-05-019, CM-23-013). The admission policy is not consulted, because the closure decides first. Reopening a closed case, or creating a fresh case for its report, is not yet designed (#3066).

Both closed-case declines write a decline record keyed on the proposal, before the Reject is queued. That record is not a ledger entry or a case change, so CM-23-013 does not bar it. It stops a failed Reject from falling through into the accept path, and it answers a later delivery of the same proposal without deciding again. The Reject carries a summary that says the case is fully closed.


What the case learns

The proposer receives two messages, in order: Accept(CaseProposal), then Create(VulnerabilityCase) carrying the case with its Participants inline. The Create sets context to the new case's URI and in_reply_to to the Accept that authorized it. So the causal link is explicit in the ActivityStreams 2.0 (AS2) correct field (CP-05-003, ADR-0045).

On a declined proposal the proposer receives Reject(CaseProposal) and nothing else.

The authority sends nothing to the reporter (CBT-01-010). The proposer, which received the report, sends the reporter its own Create(VulnerabilityCase) with the same case inline, naming the authority as CASE_MANAGER (CBT-01-001, ADR-0132). The reporter trusts that message because it comes from the actor the reporter sent its report to.

No other actor learns anything yet. At this point the case has three Participants — the authority, the owner, and the reporter — and no one has been invited. Bringing in a vendor or a coordinator is a separate flow.

A proposal with no answer is not a proposal still pending

A proposer that has received neither an Accept nor a Reject by the proposal's deadline MUST treat it as expired and stop waiting (CP-05-007). Nothing in the protocol will eventually resolve it, because nothing is holding it open — see Protocol Event Flow for why a deadline passing is not an event.


What conformance requires

Requirement Obligation
CP-04-001 A proposer MUST send Create(CaseProposal) to the case actor service's inbox
CP-04-003 The proposal MUST be addressed to the service's own actor identity, not a per-case one
CP-04-005 This implementation's service identity is {case_actor_service_url}/actors/case-actor
CP-05-002 The service MUST evaluate the proposal and either accept or reject it
CP-05-003 On acceptance it MUST send Accept and then Create(VulnerabilityCase), in that order
CP-05-004 On refusal it MUST send Reject(CaseProposal) with the proposal, inline or by reference
CP-05-005 Accept and Create(VulnerabilityCase) MUST be queued together or not at all
CP-05-011 Each queued Accept and Create(VulnerabilityCase) MUST be retried until delivered or its attempts are exhausted
CP-05-012 A retry or re-send MUST carry the same Accept under its original identifier, never a second one
CP-05-006 A duplicate proposal (the same proposal identifier) MUST re-send the stored Accept unchanged, with its original identifier
CP-05-013 A duplicate MUST NOT create a second case
CP-05-014 When the case is fully closed, a duplicate MUST be answered with Reject(CaseProposal) instead
CP-05-015 That decline MUST NOT commit a ledger entry or change case or participant state
CP-05-008 A proposal under a new identifier MUST go through the admission decision, which begins with the closed-case decline
CP-05-016 It MUST be answered with its own Accept or Reject
CP-05-017 The case MUST be reused for its owner, with no second case
CP-05-018 When the owner's case is fully closed, the proposal MUST be answered with Reject(CaseProposal), before any other step of the decision
CP-05-019 That decline MUST NOT commit a ledger entry or change case or participant state
CP-05-020 Any other proposer MUST get a separate case and is not added to the existing one
CP-05-007 A proposer MUST treat an unanswered proposal as expired at its deadline
CP-06-003 The proposer MUST record the acceptance and await the replica
CP-06-004 The proposer MUST record a refusal and surface its reason where one is given

The requirement most often read too loosely is CP-05-002. "Evaluate and either accept or reject" is not satisfied by a service that always accepts. An implementation with no refusal path has no admission policy. A case actor service that cannot decline is an open relay. Any actor that can reach the inbox obtains a managed case, a canonical ledger, and a default embargo.


Further reading