Skip to content

Vultron Modules

The pages below document individual packages. The rest of this page documents every top-level module.

Page Group
Hexagonal Architecture —
Vultron Case States Module —
Behavior Trees Behavior Trees
Behavior Tree Base Behavior Trees
Behavior Tree Basic Node Types Behavior Trees
Pacman Bot Behavior Tree Demo Behavior Trees
Robot Behavior Tree Demo Behavior Trees
Vultrabot Behavior Tree Demo Behavior Trees
Vultron Case State Behaviors Behavior Trees
Vultron Activity Streams Vocabulary Activity Streams Vocabulary
Base Package Activity Streams Vocabulary
Base Objects Activity Streams Vocabulary
Base Links Activity Streams Vocabulary
Base Activities Activity Streams Vocabulary
Vultron Extensions Activity Streams Vocabulary
Vultron Objects Activity Streams Vocabulary
Vultron Activities Activity Streams Vocabulary
Demo Package Demo
Demo CLI Demo
Demo Utilities Demo
Demo Scripts Demo

vultron

The vultron package is a collection of modules that provide the functionality for the Vultron project.

vultron.adapters

Adapters layer for the Vultron hexagonal architecture.

This package contains thin translation layers that connect the core domain to external systems. No domain logic, no AS2 parsing, no semantic extraction should live here — only translation and dispatch.

Sub-packages:

  • driving/ — Driving (left-side) adapters that trigger the core. Examples: HTTP inbox, CLI, MCP server.

  • driven/ — Driven (right-side) adapters that the core calls out to. Examples: activity store, delivery queue, HTTP delivery.

  • connectors/ — Connector plugins for outside systems (trackers, coordination platforms). Each plugin implements the core ports it serves, such as the read-only CaseReader, and translates only.

See notes/architecture-adapters.md for adapter-layer design details.

vultron.core

Core domain layer for the Vultron Protocol.

vultron.demo

Provides demo functionality for Vultron behaviors.

vultron.wire

Wire layer for the Vultron Protocol.

Handles parsing and semantic extraction of inbound ActivityStreams activities. This layer sits between the driving adapters (HTTP, CLI, MCP) and the core domain layer.

vultron.errors

The vultron.errors module provides exceptions for Vultron

BtNodePreconditionError

Bases: VultronError

Raised by a BT node helper when a required precondition is unmet.

BT node helper methods (private methods called from update()) MUST raise this exception instead of returning None when a precondition fails. update() is the single try/except handler that converts the exception to Status.FAILURE and sets self.feedback_message. See ADR-0032 and notes/bt-integration.md BT-HELPER-01.

CarriesViolations

Mixin: structured multi-violation carriage for a VultronError.

EH-07-003 and EH-07-004 require an exception raised for more than one violation to keep them as structured data and to render the whole set in str(), so no caller parses a joined message. Subclasses set self.violations in __init__; this mixin owns the rendering. It must precede :class:VultronError in the bases so its __str__ wraps Exception.__str__.

CaseHistoryInputError

Bases: VultronError

Raised when the case event history command is handed input it cannot dump.

Raised by :func:vultron.measure.history.case_history_report when the files hold no case ledger entry, or do not hold the case the caller named (CEH-01-008). The command exits non-zero on it, so a bad input never reads as a case with no events.

CaseLedgerFileError

Bases: CarriesViolations, VultronError

Raised when a case reader cannot read a case from a case-ledger file.

Raised by the case shadow tool's Vultron case reader (:mod:vultron.shadow.readers.vultron_ledger) for a file that is missing, unreadable, empty, or holds a row that is not a valid ledger entry. Unlike the measure layer, which degrades a malformed row (CEH-02-008), the reader refuses the whole file, so it never returns a partial ledger.

Attributes:

Name Type Description
path

The ledger file the reader was asked for, as it was named.

violations

Every reason the file was refused, each naming its row where it has one (EH-07-001, EH-07-003).

CvdStateModelError

Bases: VultronError

Base class for errors in the CVD state model.

DemoActorRoleError

Bases: VultronError

Raised when a scenario's ActorRole declaration is invalid.

Raised at import time by :class:~vultron.demo.helpers.actor_roles.ActorRole and :func:~vultron.demo.helpers.actor_roles.role_map — a malformed role name, a missing help string, id metadata on a role that declares no --*-id option, or two roles in one scenario sharing a name or a container env var.

Fails fast for the same reason :class:DemoScenarioRegistryError does: the role list is what generates a scenario's CLI options and what its main() signature is ratcheted against (DEMOCI-11-011), so a role list that is quietly wrong yields a sub-command whose options look complete and point at the wrong container.

DemoCaseActorUnconfiguredError

Bases: VultronError

Raised when a demo helper needs the CaseActor identity and none is set.

Raised by :func:~vultron.demo.utils.configured_case_actor_id when ActorConfig.case_actor_service_url is unset. The CaseActor identity comes from configuration only (CP-08-001, CP-08-009): a demo that guessed it from its own server.base_url would name a CaseActor that no container hosts in a multi-container topology, and the CaseProposal round-trip would never start. The message names VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL, the variable that fixes it.

DemoFailureError

Bases: VultronError

Raised when a demo scenario completes with one or more step failures.

Accumulates all failures from demo_step and demo_check context managers in vultron.demo.utils. Raised by assert_demo_success() at the end of a scenario run, and by vultron.demo.helpers.runner.run_exchange_demos once every selected exchange demo has run, so that docker compose --exit-code-from and the vultron-demo CLI can detect failure. See specs/demo-ci.yaml DEMOCI-01-001, DEMOCI-01-005.

DemoRecordingError

Bases: VultronError

Raised when a demo scenario cannot be recorded for the demo UI.

Raised by :mod:vultron.demo.recordings when:

  • the Docker compose file lacks the container layout a scenario's roles name, or sets a malformed case-roles value;
  • a scenario addresses a host that no role's container slot serves;
  • a run ends without capturing every ledger its dump names, or the dump holds no CaseActor (canonical) ledger;
  • a dumped ledger line is not an entry with a logIndex;
  • a replica holds an entry that differs from, or is absent from, the canonical ledger at the same logIndex;
  • a run ends without reporting every step of its declared path, or its step marks are missing or malformed.

A scenario that itself fails raises :class:DemoFailureError instead.

DemoScenarioRegistryError

Bases: VultronError

Raised when a demo scenario's self-registration is invalid.

Raised at import time by the @scenario decorator in vultron.demo.scenario.registry — a malformed spec, a story that names no path (DEMOCI-11-019), a name already registered with a different spec, or a declared name that contradicts the module it was declared in — and by discover_scenarios() when a discovered *_demo module registered nothing at all, or when the declared paths do not merge into one tree in which every registered scenario is exactly one ending (DEMOCI-11-023).

Fails fast for the same reason :class:RegistryOrderError does: every committed scenario artifact is generated from this registry, so a registry that is quietly wrong yields tables and a CI matrix that look complete and are not. See specs/demo-ci.yaml DEMOCI-11 and ADR-0098.

DemoScenarioStepError

Bases: VultronError

Raised when a scenario reports a step its declared path does not hold.

Raised by :meth:~vultron.demo.helpers.harness.ScenarioHarness.reach_step when the reported (branch point, choice) is not the next step of the scenario's declared path — the choices of its assembled story (DEMOCI-11-019) — or when a step after the first is reached before the harness follows a case ledger. Either way the code and the declaration disagree about where the scenario is on the tree, so the step mark the shared-prefix check reads would be wrong (DEMOCI-11-014, DEMOCI-11-019, DEMOCI-11-017).

DemoStoryError

Bases: VultronError

Raised when a demo scenario's assembled story is malformed.

Raised by :mod:vultron.demo.helpers.story when a story is empty or holds an item that is neither a fragment nor a choose(...), when a choice names an actor the scenario's cast does not seat, or when a fragment reads an artifact the story has not produced yet — the case before it is opened, say.

Fails fast for the same reason :class:DemoScenarioRegistryError does: the story is what the registry reads the scenario's path off (DEMOCI-11-019), so a story that is quietly wrong puts the scenario at the wrong place on the tree and the generated index follows it there.

LedgerReadError

Bases: VultronError

Raised when a case-ledger file handed to the measure layer cannot be read.

Raised by :func:vultron.measure.ledger.read_ledger_file for a file that is missing, unreadable or not UTF-8 text. A malformed row is never this error: the reader degrades it to one unusable row and reads the rest (CEH-02-008).

RegistryOrderError

Bases: VultronError

Raised when SEMANTIC_REGISTRY contains a less-specific pattern that precedes a more-specific one in the same activity_ group.

Raised at import time by _validate_registry_order() in vultron.semantic_registry so that ordering violations fail fast and are impossible to miss. See specs/semantic-extraction.yaml SE-03-002 and vultron/wire/as2/AGENTS.md.

ShadowConnectorError

Bases: VultronConfigError

Raised when the case shadow tool's outside-system connector cannot serve it.

The connector the outside-system source reads through, the one the shadow.connector setting names or vince when it is unset, is not installed, or its plugin implements no :class:~vultron.core.ports.case_reader.CaseReader. The page shows the reason when the analyst chooses that source, rather than read cases through some other reader than the one chosen.

Attributes:

Name Type Description
connector

The connector's entry-point name.

TriggerRegistryError

Bases: VultronError

Raised when the trigger registry cannot be assembled consistently.

Raised at import time by vultron.trigger_registry when two rows share a verb, when a row's request_model binds a result type other than the row's result_type, or when a request model is shared by rows that disagree on the use case or result type — a table that cannot resolve a request to one use case (ADR-0110, TRIG-12-004). Fails fast so a bad row is impossible to miss, as RegistryOrderError does for the received side.

VinceAuthError

Bases: VinceReadError

Raised when VINCE refuses the API credential (HTTP 401 or 403).

The operator replaces VULTRON_VINCE__API_TOKEN or asks for the account's access; repeating the read changes nothing.

VinceCaseNotFoundError

Bases: VinceReadError

Raised when VINCE holds no case by the id the reader was given, or does not show it to the credential's account (HTTP 404 on the case).

VinceCaseRecordsError

Bases: CarriesViolations, VultronError

Raised when the VINCE translation cannot read a case at all.

Raised by :mod:vultron.adapters.connectors.vince when the records of a VINCE case hold no case record, or one without the vuid, pk or created time every crosswalk row needs. Any other record the translation cannot read is returned as an untranslated fact instead (CRD-01-005). No violation quotes a VINCE value, so the error is safe to log (VSD-01-003).

Attributes:

Name Type Description
vuid

The case's VINCE id, when the records name one.

violations

Every reason the case could not be read (EH-07-001).

VinceRateLimitedError

Bases: VinceReadError

Raised when VINCE answers a read with HTTP 429 (too many requests).

The reader does not wait and retry: the analyst asks again later.

Attributes:

Name Type Description
retry_after

The seconds VINCE asked the client to wait, from its Retry-After header, or None when it named no number of seconds (no header, an HTTP-date, or a value that is not a whole number in ASCII digits).

VinceReadError

Bases: VultronError

Raised when the VINCE case reader cannot fetch a case from VINCE.

Raised by :class:~vultron.adapters.connectors.vince.reader.VinceCaseReader when a read of the VINCE API fails. The reader makes one attempt per read and never retries, so a failure reaches the analyst at once rather than after an unbounded wait. A subclass names the cause an operator acts on. The message names the case, the read and the HTTP status, never a response body or the credential (VSD-01-003, VSD-01-005).

Attributes:

Name Type Description
vuid

The VINCE id of the case being read.

read

The read that failed, as its path below case/<vuid>/ (case for the case itself).

status

The HTTP status VINCE answered with, or None when no answer came.

VinceUnavailableError

Bases: VinceReadError

Raised when VINCE cannot be reached, times out, or answers a read with a server error (HTTP 5xx).

Violation

Bases: NamedTuple

One violated rule in a rejection that reports every violation.

A validation boundary that refuses its input as a unit still owes its caller every violation it can recognise (EH-07-001). This is the unit of that report: the rule's human-readable message, the dimensions the rule reads, and whether it is a root cause or a consequence of another reported violation (EH-07-002).

derived is a property of the set, not of the rule on its own, so it is assigned by whichever evaluator produced the complete list — see :func:~vultron.core.states.participant_transitions .participant_transition_violations.

classification property

"derived" or "root" — the EH-07-002 label for this rule.

VultronActClockInstalledError

Bases: VultronWiringError

Raised when an act clock is installed while another install is active.

The scoped install of the act clock does not nest: two recorded runs in one block would read one clock and move each other's times (ADR-0176). A composition fault, never a protocol outcome.

VultronActivityConstructionError

Bases: VultronError

Raised when a factory function cannot construct the requested activity.

Wraps a Pydantic ValidationError as __cause__ so that callers can inspect the original validation details if needed. Factory functions MUST catch pydantic.ValidationError and re-raise as this exception to keep internal activity class names out of public error messages. See specs/activity-factories.yaml AF-04-001, AF-04-002.

VultronActorProfileFetchError

Bases: VultronError

Raised when an actor's profile cannot be fetched or read.

The fetch failed, or the answer is not that actor's profile: a body that does not parse as one of the concrete actor types, or one for another actor. The message says which.

VultronAlreadyExistsError

Bases: VultronError, ValueError

Raised when creating a record whose id_ is already present.

The counterpart of :exc:VultronNotFoundError, and the only cause a caller of DataLayer.create() may legitimately swallow: the record it wanted stored is already stored.

This type exists so that "already there" stays separable from "could not be projected". crud.create previously raised a bare ValueError for the duplicate, and every caller that swallows a duplicate catches it — so any other ValueError escaping the same call was silently logged as a benign duplicate and never stored. That is not hypothetical: it is why :exc:VultronValidationError was kept out of the ValueError hierarchy, and it also swallowed Record.from_obj's two genuine faults (an object with no type_, and a type_ still carrying the as_ prefix).

ValueError remains in the base classes so that callers written against the older contract keep working; callers that mean only "already exists" MUST catch this class rather than ValueError. ARCH-23-006's note records why :exc:VultronValidationError must be absorbable by Pydantic, which is what made the shared base untenable.

VultronApiHandlerNotFoundError

Bases: VultronError, KeyError

Raised when no handler is found for a given activity type.

VultronBTInternalError

Bases: VultronError

Raised when a received-side or trigger-side BT failed on an internal error.

BTBridge catches a non-VultronError exception escaping a node and reports it as FAILURE with internal_error=True. That is a programming error, not a protocol outcome, so a handler MUST NOT report it as HandlerDisposition.REFUSED (ADR-0095): it re-raises it as this exception so the inbox pipeline records it as a raised dispatch, traceback and all, and it stays distinguishable from a refusal. A trigger raises it for the same reason, so a server-side fault is never translated into the client's 422.

VultronCanonicalEntryError

Bases: VultronError

Raised when a case-ledger entry violates canonical entry criteria.

VultronConfigError

Bases: VultronError

Raised when the node's configuration cannot be used as given.

A configuration fault is the operator's to fix before the node starts or before the feature that needs the setting runs; it is never a protocol outcome. A subclass's message names the setting and its source, never a secret setting's value (VSD-01-005).

VultronConfigScopeLostError

Bases: VultronWiringError

Raised when get_config() runs outside the app scope it needs.

An app holding its own config runs in the process, and the caller is in no app's scope, so the process-wide config is not its node's (ADR-0206). A background boundary that logs one actor's failure and goes on re-raises this one: a lost scope is every actor's failure. Any other VultronWiringError stays one actor's failure there, as before.

VultronConflictingActInstantError

Bases: VultronWiringError

Raised when a nested tree run is handed an instant of its own.

Only an act's outermost run takes the act's instant; a nested run inherits it, so one act decides and records against one instant (ADR-0176). A second instant inside a run means something below the act's edge read a clock.

VultronEntryRefusedError

Bases: VultronInvalidStateTransitionError

Raised when a ledger entry does not apply to the case it is applied to.

The one apply function checks the starting state an entry implies before it writes what the entry carries (ADR-0124, CM-23-016). On a replica a refusal means an earlier entry is missing or the replica's case has diverged, so the Add that carried the entry is held for gap handling (SYNC-14-001) and the entry is never patched over. On the CASE_MANAGER a refused trial apply stops the act before anything is committed.

VultronError

Bases: Exception

Base class for all Vultron exceptions

VultronIdSourceInstalledError

Bases: VultronWiringError

Raised when an id source is installed while another install is active.

The scoped install (install_id_source) does not nest: two reproducible runs in one block would draw from one stream of ids and take each other's ids without anyone seeing it (ADR-0185). A composition fault, never a protocol outcome.

VultronInvalidStateTransitionError

Bases: VultronError

Raised when an operation requests an invalid state machine transition.

VultronMissingActInstantError

Bases: VultronWiringError

Raised when time is wanted below an act's edge and no act supplied it.

An act reads the clock once, at its entry point, and its tree runs carry that instant as /at; a node that needs the time reads it there, never the clock (ADR-0176). A run with no instant was started outside an act, so it is a composition fault, not a protocol outcome, and it is never answered by reading the clock instead (ARCH-10-001).

VultronMissingCredentialError

Bases: VultronConfigError

Raised when a feature needs a credential the environment does not hold.

The VINCE connector raises it before it reads a case, so a node with no credential refuses the read rather than sending an unauthenticated request (VSD-01-004, SHD-02-003). The message names the environment variable to set.

VultronNodeCaseReadError

Bases: CarriesViolations, VultronError

Raised when the live Vultron case reader cannot read a case.

Raised by the case shadow tool's live Vultron case reader (:mod:vultron.shadow.readers.vultron_node) when the node cannot be reached, does not serve the demo case-ledger endpoint (it serves it only in prototype run mode), holds no such case, or sends a row that is not a valid ledger entry. The reading is refused whole, so the reader never returns a partial ledger (SHD-04-002, SHD-04-004).

Attributes:

Name Type Description
node_url

The node's API root the reader was configured with.

case_id

The case the reader was asked for, as it was named.

violations

Every reason the case could not be read, each naming its row where it has one (EH-07-001, EH-07-003).

VultronNotACaseParticipantError

Bases: VultronError

Raised when an actor asks to read a case it is no active participant of.

The case host serves a case's objects only to the case's active participants (AKM-05-006, CM-10-004). The requester is the actor the request claims to be: a fetch request carries no proof, so the prototype does not authenticate it (HTTP-level request authentication is #509).

VultronNotAnEmbargoError

Bases: VultronValidationError

Raised when an embargo id resolves to a record that is not an EmbargoEvent.

The type-mismatch half of the fail-closed embargo read (EMB-18-003); the missing half is :exc:VultronNotFoundError. It carries embargo_id so a caller can tell which embargo was unreadable — for example the one a revision replaces, as opposed to the one it activates — without parsing the message.

VultronNotFoundError

Bases: VultronError

Raised when a requested resource cannot be found.

VultronOutboxObjectIntegrityError

Bases: VultronError

Raised when an outbound activity's object_ is a bare string URI or Link reference instead of the required inline domain object.

This codebase carries the object of every outbound activity as a fully inline typed object so that recipients can determine the semantic type without dereferencing it, which this codebase does only in a few cases (AKM-05-007). The protocol allows the object inline or by reference (AKM-03-001, MV-09-001); inlining is this codebase's rule (AKM-03-003), enforced at delivery (AKM-03-002, MV-09-002).

VultronOutboxToFieldMissingError

Bases: VultronError

Raised when an outbound activity lacks a non-empty to: field.

All Vultron protocol exchanges are direct messages. Every outbound activity MUST address at least one recipient via to:. See specs/outbox.yaml OX-08-001, OX-08-002, OX-08-003.

VultronProofVerificationError

Bases: VultronError

Raised when a document's proof is missing or does not verify.

The error category for a sender-authentication failure (EH-03-005). The receiver cannot tell who wrote the document, so it refuses it (SIG-03-002). translate_domain_errors maps it to 422 with ProofVerificationError as the error name, the answer the inbox gives to a delivery whose proof fails (SIG-03-002). The proof is part of the content, not an HTTP credential, so 401 (which asks for a WWW-Authenticate challenge) does not fit. 403 does not arise at the inbox either: a verified sender's entitlement is decided in core and answered with a Reject (HP-01-006, HP-01-007). The distinct name keeps a failed proof apart from a field error (:exc:VultronValidationError) for senders and in logs. The authorization half of EH-03-005 is :exc:VultronNotACaseParticipantError.

This class deliberately does not inherit ValueError. A forged body is not malformed input that a validator may absorb as one failed union branch. It also carries no activity_id: an unverified document's id is the forger's claim.

The signing module raises the wire subclass :exc:~vultron.wire.as2.errors.VultronProofInvalidError. Its other two errors are outside this category, and translate_domain_errors maps neither. The inbox's verification stage answers a malformed published key (VultronMultikeyError) as a key that cannot be read, raising :exc:VultronVerificationKeyError, and a body it cannot read as one JSON object (VultronUnsignableJsonError) 400 for a syntax fault and 422 for refused but well-formed JSON.

VultronProtocolViolationError

Bases: CarriesViolations, VultronError, ValueError

Raised when an inbound protocol message violates a mandatory requirement.

The inbound mirror of :exc:VultronOutboxObjectIntegrityError. While that class catches outbound integrity failures (sending a bare URI when an inline object is required), this class catches inbound structural violations — messages received that break a MUST-level spec requirement.

First use: CBT-05-008 — bootstrap Create(VulnerabilityCase) carrying a participant as a bare URI string rather than a fully inline typed object. Receivers MUST raise this error and reject the bootstrap rather than silently synthesising participant state from domain knowledge.

ValueError is included in the base classes so that Pydantic absorbs this error when it is raised from a model_validator or field_validator and wraps it in a ValidationError rather than letting it escape the model_validate() call. Callers that need to distinguish a protocol violation from an ordinary validation failure can inspect ValidationError.errors()[0]['ctx']['error'].

A boundary that recognised more than one violation passes them as violations (EH-07-003) — first use: CoreObject's computed-field contradiction check (ARCH-23-005), which names every contradicted field.

VultronReadOnlyViewError

Bases: VultronError, AttributeError

Raised on an attempt to change a read-only view of a received activity.

A received activity's view is parsed fresh from the archived body on every load (ADR-0149), so a change to it could only ever reach that one copy, and would read as a change to what arrived. Core changes its own records instead. An AttributeError, as assignment to any frozen object raises.

VultronReferenceResolutionError

Bases: VultronError, ValueError

Raised when an IRI reference in an object-only slot cannot be materialised.

VM-06-007 makes rehydrate() the sole owner of ID-to-object materialisation and requires it to refuse rather than fabricate a placeholder. This is that refusal. It fires for two distinct causes, both of which mean the slot cannot legally be filled:

  • the reference resolved to nothing in the data layer, or
  • it resolved to something that is not an AS2 object, so it cannot go into a wire slot.

ValueError is included in the base classes for the same reason as :exc:VultronProtocolViolationError: so Pydantic absorbs the error and wraps it in a ValidationError if it is ever raised inside a validator, rather than escaping the whole model_validate() call. ARCH-23-006's note records what goes wrong when a core-side guard is not absorbable that way.

VultronReusedActivityIdError

Bases: VultronProtocolViolationError

Raised when a delivery reuses a held activity id with a different body.

An activity id names one activity (ID-01-001), so a second body under an id the receiver already holds is not a redelivery: it is refused at ingress and neither body is routed (IE-10-002, IE-10-003). The comparison is an exact match of the sealed received texts (VM-08-002).

The message names the reused id, which becomes the inbox outcome's failure_reason; the sending actor is kept on :attr:actor_id for the WARNING the ingress adapter logs.

Parameters:

Name Type Description Default
activity_id str

The id the delivery reuses.

required
actor_id str | None

The sending actor the delivery names, if any.

required

VultronSecretInConfigFileError

Bases: VultronConfigError, ValueError

Raised when a configuration file names a secret setting.

A secret, such as the VINCE API credential, is read only from the environment the node runs in, because configuration files live in the repository and a secret written there has a path into a commit (VSD-01-004, SHD-02-003). The file is refused at load whatever value the key holds, and the message names the file and the key, never the value.

VultronStaleStoreError

Bases: VultronError

Raised when a persisted store predates a change to its stored shape.

Stored data carries no backwards compatibility and no migration: a store written before a shape change is refused when it is opened, with a message saying it must be reset, rather than run without the guarantee the new shape provides (notes/datalayer-design.md § "Changing a Table's Shape").

VultronUnhostedActorError

Bases: VultronWiringError

Raised when execution is scoped to an actor this container does not host.

A store can be opened only for an actor under the authority of the store in hand: clone_for_actor on another authority's actor would mint an empty local store in its name. No sanctioned path executes a tree, or enqueues an activity, as an actor the running container does not host (BT-05-005, CM-24-011, CLP-10-014, ADR-0109), so reaching one is a composition fault, not a protocol outcome.

VultronUnverifiedLedgerEntryError

Bases: VultronError

Raised when the CASE_MANAGER is about to send an entry it cannot verify.

The entry states no entry_hash, or its content does not reproduce the one it states. It is held back, and no later entry of the same send goes out (SYNC-03-009). The message names the case, the entry, its log_index and the recipients, so the one ERROR line that reports it carries everything SYNC-03-009 asks for.

VultronValidationError

Bases: CarriesViolations, VultronError, ValueError

Raised when domain validation of a resource or request fails.

When the boundary recognised more than one violation, pass them as violations: they are kept as structured data on the exception and str() renders the whole set (via :class:CarriesViolations), so no caller has to parse the joined message to recover the individual rules (EH-07-003, EH-07-004). This follows :exc:DemoFailureError's shape, the house pattern for accumulate-all-then-fail (DEMOCI-01-003).

ValueError is in the base classes for the same reason as :exc:VultronProtocolViolationError and :exc:VultronReferenceResolutionError: Pydantic absorbs a ValueError raised inside a validator and reports it as a failed branch, where any other exception escapes the whole model_validate() call. ARCH-23-006 requires this: under ADR-0099 core classes sit inside wire unions, so a core-side guard firing while Pydantic resolves a union must fail that branch rather than abort the operation. The rule's note names this as the defect to fix before the rule is inverted, and inverting it is what ADR-0099 does.

This class deliberately did not inherit ValueError until :exc:VultronAlreadyExistsError existed, because crud.create signalled a duplicate row with a bare ValueError that callers swallow — so sharing the base made a projection failure indistinguishable from "already stored". Separability now comes from the two distinct types, not from this class avoiding ValueError; see test_normalization_failure_is_distinguishable_from_duplicate_row.

VultronVerificationKeyError

Bases: VultronProofVerificationError

Raised when the key a proof names cannot be read from its author.

A receiver takes the key that verifies a proof only from the author's actor profile, as fetched from the author (SIG-02-001, SIG-02-003). When the fetch fails or the fetched profile does not list the key the proof's verificationMethod names, the receiver cannot tell who wrote the document and refuses it (SIG-03-002), so this is a proof-verification failure, answered as one.

VultronWiringError

Bases: VultronError

Raised when a node is missing a DataLayer or port it requires.

That is a deployment or composition fault, never the sender's doing, so BTBridge flags it as internal_error even though it is a VultronError — and a received handler therefore raises rather than reporting the message as REFUSED (#2255, ADR-0095).