Skip to content

Vultron ActivityStreams Vocabulary Objects

vultron.wire.as2.vocab.objects.base

Provides a base class for all Vultron ActivityStreams Objects.

as_VultronObject

Bases: as_Object

Base class for all Vultron ActivityStreams Objects.

Subclasses represent specific Vultron wire-format object types and MUST implement :meth:from_core (and SHOULD implement :meth:to_core) with a narrowed type signature, e.g.::

@classmethod
def from_core(cls, core_obj: VulnerabilityReport) -> "VulnerabilityReport":
    ...

_field_map contract: If a subclass wire type uses different field names than the corresponding core domain type, declare the mapping as::

_field_map: ClassVar[dict[str, str]] = {"domain_field": "wire_field"}

The default :meth:from_core implementation applies _field_map renames before calling :func:~pydantic.BaseModel.model_validate, so subclasses with no name differences can inherit the default without override.

inline_required_refs contract: Some AS2 ref fields are required by the protocol to carry a whole object rather than a URI — as_CaseProposal must inline its as_VulnerabilityReport (CP-01-004, AKM-03-003). The type annotation cannot express that: ActivityStreamRequiredRef[T] is T | as_Link | NonEmptyString, so a URI type-checks. Name such fields here::

inline_required_refs: ClassVar[frozenset[str]] = frozenset({"object_"})

Persistence reads this declaration and skips dehydration for those fields, so the invariant survives a store round-trip. Without it the id is stored alone and nothing can rebuild the object, because only the first level of an inbound activity's nesting is given a record of its own — the defect behind #2482.

to_core always raises :exc:NotImplementedError at this level; subclasses that have a meaningful reverse mapping SHOULD override it.

from_core(core_obj) classmethod

Create a wire object from a core domain object.

The default implementation performs a JSON round-trip::

data = core_obj.model_dump(mode="json")
# apply _field_map renames (domain key → wire key)
cls.model_validate(data)

Subclasses MUST narrow the core_obj parameter type. Override this method when simple field-rename mapping via _field_map is insufficient.

Parameters:

Name Type Description Default
core_obj Any

A core domain model instance (Pydantic BaseModel subclass).

required

Returns:

Type Description
as_VultronObject

A new instance of this wire type populated from core_obj.

to_core()

Convert this wire object to a core domain object.

Subclasses that have a well-defined reverse mapping SHOULD override this method and return the appropriate core domain type.

The _field_map contract is the inverse of :meth:from_core: wire field names map to domain field names. Subclass overrides should apply the reverse mapping before calling CoreType.model_validate(data).

Raises:

Type Description
NotImplementedError

Always — no generic reverse mapping exists at the wire base level.

vultron.wire.as2.vocab.objects.case_participant

Wire-layer alias for CaseParticipant.

Per ARCH-25-003 (ADR-0099): the core class is the canonical form. The as_-prefixed names are retained for backward compatibility.

as_CaseParticipant was held back with the two status classes by #3487, which scoped it out because the status pair "drags the as_CaseParticipant cascade with them". The cascade turned out to be the cheap part: the two classes carried identical field sets apart from an invite RSVP deadline (core-only then; it now rides on each consent row, ADR-0122), and core already implemented every method the wire class had — role serialization, name derivation, status seeding, has_role, roles — plus several the wire class did not. Nothing needed relocating from this class.

The role subclasses continue to be re-exported here so that existing from vultron.wire... import VendorParticipant imports keep working.

CaseActorParticipant

Bases: CaseParticipant

A participant that acts as the CaseActor service for a VulnerabilityCase.

Holds both COORDINATOR and CASE_MANAGER roles (CBT-01-014, CBT-01-015). The attributed_to field identifies the ActivityStreams Service URI that will send Announce(VulnerabilityCase) updates on behalf of the case owner. Receivers use this participant to establish trusted CaseActor identity during bootstrap.

CoordinatorParticipant

Bases: CaseParticipant

A CaseParticipant that holds the COORDINATOR role.

DeployerParticipant

Bases: CaseParticipant

A CaseParticipant that holds the DEPLOYER role.

ObserverParticipant

Bases: CaseParticipant

A CaseParticipant that holds the OBSERVER role (ADR-0057).

ReporterParticipant

Bases: CaseParticipant

A CaseParticipant that holds the REPORTER role.

Also initialises participant_statuses to [ACCEPTED] because a reporter has by definition accepted the report.

VendorParticipant

Bases: CaseParticipant

A CaseParticipant that holds the VENDOR role.

vultron.wire.as2.vocab.objects.case_status

Wire-layer aliases for CaseStatus and ParticipantStatus.

Per ARCH-25-003 (ADR-0099): the core class is the canonical form. The as_-prefixed names are retained for backward compatibility.

These were the last two of the 27 paired classes, held back by #3487 because they "differ by field name" — flat em_state/rm_state against nested em/rm dimensions — rather than merely by spelling. That difference had already dissolved before the pair was collapsed: ARCH-25-005 (ADR-0099) makes a dimension serialize as a bare state value, and the core fields carry the emState/rmState aliases, so both classes already emitted byte-identical AS2. What remained was two projections translating between forms that had become the same form.

One piece of the deleted classes had no core equivalent: as_ParticipantStatus._reject_retired_vfd_keys, which refused the retired vfd_state key. It was relocated onto ParticipantStatus and later deleted (#3921): extra="forbid" refuses the key on in-process and stored data (SDO-03-008), and the parse edge sets it aside on inbound data as an unknown key (MV-11-003, ADR-0175).

vultron.wire.as2.vocab.objects.embargo_event

Wire-layer alias for EmbargoEvent.

Per ARCH-25-003 (ADR-0099): the core class is the canonical form. The as_-prefixed names are retained for backward compatibility.

vultron.wire.as2.vocab.objects.vulnerability_case

Wire-layer vocabulary for VulnerabilityCase.

Per ARCH-25-003 (ADR-0099): :class:VulnerabilityCase is the canonical form. as_VulnerabilityCase is a backward-compatibility alias.

:class:~vultron.core.models.case_preview.CasePreview (wire alias in :mod:~vultron.wire.as2.vocab.objects.case_preview) is the case's preview, which a stub Invite carries as the preview of the case's typed reference (ADR-0205).

vultron.wire.as2.vocab.objects.vulnerability_report

Wire-layer alias for VulnerabilityReport.

Per ARCH-25-003 (ADR-0099): the core class is the canonical form. The as_-prefixed names are retained for backward compatibility.