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-onlyCaseReader, 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
|
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 |
|
status |
The HTTP status VINCE answered with, or |
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
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
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).