Skip to content
Reference

Architecture Specifications

Recommended structure that carries over to other languages but is not required for Vultron compliance. Behavior trees, and keeping protocol behavior inside the behavior tree, are architecture, as are hexagonal boundaries, event-driven dispatch, port and adapter patterns, and fail-fast principles.

Behavioral Specifications

The following specifications define Event-Condition-Action (ECA) behavioral requirements with typed preconditions, ordered steps, and postconditions.

Actor Knowledge Model

Defines the Actor Knowledge Model: a Vultron Actor's knowledge of the world is strictly bounded by the ActivityStreams 2.0 activities it has received. Actors must not assume recipients hold objects that were not explicitly included in prior activities; DataLayer access is private and non-shareable, and all inter-Actor communication occurs exclusively through the AS2 wire protocol.

File ID: AKM

Actor Addressing and Resolution

ID Priority Requirement Related
AKM-05-002 SHOULD When a URI first names an actor with no local record, the implementation SHOULD query the ActorResolutionCallOutBundle before it mints a minimal record.

A resolution backend can supply a peer's inbox and profile, so a minimal record minted without asking it holds less than is available.
AKM-05-016 SHOULD When the ActorResolutionCallOutBundle backend returns a FAILURE result, the implementation SHOULD log an explicit WARNING rather than fall back silently.

A failed lookup that falls back silently looks like success, so operators would not learn that actor resolution is broken. The WARNING makes the degraded path visible.
Extends: AKM-05-002

Agentic Readiness

Requirements for API and CLI design that enable reliable interaction by automated agents and AI systems. Covers machine-parseable interfaces, structured response formats, and observable behavior that supports agentic workflows.

File ID: AR

Long-Running Operations

ID Priority Requirement Related
AR-04-001 SHOULD Long-running operations SHOULD return a job or task object immediately with a stable id and status field

A request that waits for a long operation can time out in the client, in a proxy or in the server. The client then does not know whether the operation ran. A job object with a stable id and status, returned at once, lets the client follow the operation and not start it a second time.
AR-04-002 SHOULD A separate polling endpoint or webhook mechanism SHOULD be available to report operation completion

A job object (AR-04-001) is useful only if the client can find out when the job ends. A polling endpoint or a webhook gives the client that answer without an open connection for the whole operation.

Pagination

ID Priority Requirement Related
AR-05-001 SHOULD Collection endpoints SHOULD expose limit and offset (or cursor) query parameters with documented defaults and maximums

A collection can grow without limit, so one request for all of it can return more data than the client or the server can handle. Paging parameters with documented defaults and maximums let an agent read a collection in parts of a known size.

Bulk Operations

ID Priority Requirement Related
AR-06-001 MAY Resources that agents may need to create, update, or delete in quantity MAY expose batch endpoints (e.g., POST /v1/items/batch)

An agent that changes many resources with one request each pays the cost of each request. A batch endpoint does the same work in one request. The requirement is optional because most resources are not changed in large numbers.

Architecture

Defines the architectural constraints for the Vultron codebase. The system follows hexagonal architecture (Ports and Adapters): the core domain is isolated from all external systems, which interact through defined ports via thin adapters. Covers layer separation rules, the core object hierarchy, domain model richness, and the fail-fast validation boundary.

File ID: ARCH

Layer Separation

ID Priority Requirement Related
ARCH-01-002 MUST Core functions MUST accept and return domain types only

Core logic reads the meaning of a message, not its encoding. If a core function takes or returns a wire type, core depends on the AS2 format, and a change to that format then changes core code. Domain types also arrive already validated (ARCH-08-002), so core does not need to check them again.
ARCH-01-003 MUST NOT The wire/ layer (AS2 parser, semantic extractor) MUST NOT contain handler logic, case management, or case ledger management.

The wire layer encodes and decodes messages. Handler logic, case management and the case ledger are domain behavior, and they belong in core. If the wire layer holds domain logic, a change of wire format must also change that logic, and core then does not own its own rules. The wire layer may name core types in its annotations (ARCH-22-001), because AS2 is a serialization of the core model (ADR-0211). The rule thus limits what wire code does, not what it imports.

Driven Adapter Injection

ID Priority Requirement Related
ARCH-04-001 MUST Driven adapters (persistence, delivery queue, DNS resolver, HTTP delivery) MUST be injected into core services via port interfaces

Enables testing core logic with in-memory ports and swapping production backends without touching domain code

Wire Layer Replaceability

ID Priority Requirement Related
ARCH-06-001 SHOULD The wire layer (wire/as2/) SHOULD be replaceable as a unit without touching the core or adapter layers

AS2 is one encoding of the protocol. If core or the adapters depend on the internals of the wire layer, a change of encoding must also change them. When the wire layer can be replaced as one unit, a change of encoding stays in that layer.

Handler Isolation

ID Priority Requirement Related
ARCH-07-001 MUST NOT Handler functions MUST NOT re-invoke semantic extraction

Semantic extraction runs once, in the wire pipeline, before dispatch (ARCH-03-001), and the handler receives its result. If a handler runs extraction again, the two results can differ. The handler can then act on a meaning different from the one that selected it in the dispatcher.

Driving Adapter Boundary

ID Priority Requirement Related
ARCH-08-001 MUST Driving adapters (HTTP inbox, CLI, MCP server) MUST invoke the wire pipeline before calling into the core

Any driving adapter that needs to ingest AS2 can reuse the wire pipeline; there is no duplication
ARCH-08-002 MUST A driving adapter MUST promote an incoming wire object to its most-specific domain type before it passes the object into the core.

Promoting at the boundary ("validate at edge") ensures that core handlers receive fully typed objects and never need to downcast or call isinstance() to recover type information that was present on the wire. Deferring promotion into the core violates the hexagonal principle that adapters adapt, cores compute.
Extends: ARCH-08-001
Refines: CS-10-001
ARCH-08-003 MUST NOT Code that calls into the core MUST NOT pass it a bare BaseObject or generic BaseModel when the wire payload determines a more specific type.

A core handler that gets a generic object must downcast it, or call isinstance(), to recover a type that the wire payload already gave. Those checks then spread through core code, although that work belongs to the adapters.
Extends: ARCH-08-002

Domain Model Richness Constraint

ID Priority Requirement Related
ARCH-09-001 MUST Core domain models MUST be as rich as or richer than their wire-layer counterparts

A thinner core model forces piecemeal additions as handlers are implemented, causing boundary leakage and implementation drift

Fail-Fast Domain Objects

ID Priority Requirement Related
ARCH-10-001 MUST Domain events and domain models MUST validate required fields at construction time and fail immediately if required invariants are not satisfied

Late validation masks missing data and makes debugging harder; fail-fast ensures errors surface at the point of construction

Fail-Fast at Domain Operation Boundaries

Governs relational invariants enforced at runtime entry points — use-case execute(), BT node update(), and helper functions that require non-None resolved values. Extends the construction-time fail-fast rule to cover checks that can only be performed at the point of invocation, not at object construction.

ID Priority Requirement Related
ARCH-15-004 MUST Each domain helper function MUST have exactly one canonical copy, with no second implementation of the same logic.

When one helper has two copies, a fix to one copy does not reach the other, and the copies drift apart in their behavior. Callers then get different answers to the same question, for example different handling of a missing value. One copy in a known place lets every caller share each fix. See notes/domain-validation.md and ADR-0032.
ARCH-15-005 MUST A layer-neutral domain helper, one with no dependency above models/, MUST live in vultron/core/models/_helpers/.

A fixed place for each kind of helper lets a developer find the existing copy before writing a new one. A layer-neutral helper in models/ can serve every layer above it. A use-case-specific helper belongs in vultron/core/use_cases/_helpers.py.
Implements: ARCH-15-004

Port Inbound/Outbound Discrimination

ID Priority Requirement Related
ARCH-11-001 SHOULD Core ports SHOULD be organized into inbound (driving) and outbound (driven) categories

Adapters call driving ports, and core calls driven ports. The two kinds have different rules for who implements them and who calls them. When the ports are grouped by direction, a reader can see which rules apply to a port, and can find a port that is in the wrong place.

Outbound Delivery Pipeline

ID Priority Requirement Related
ARCH-19-001 MUST Outbound delivery MUST be modelled as a three-stage pipeline consisting of Emission, Transport delivery, and Recipient acceptance.

Conflating stages (e.g., treating a transport timeout as a recipient rejection) leads to incorrect retry logic and protocol-state divergence. The three-stage model is the foundation for correct at-least-once delivery. Source: notes/architecture-adapters.md.
ARCH-19-006 MUST NOT Each stage of the outbound delivery pipeline has distinct error semantics and MUST NOT be conflated with another stage.

Treating a transport timeout (stage 2) as a recipient rejection (stage 3) leads to incorrect retry logic and protocol-state divergence.
Extends: ARCH-19-001
ARCH-19-002 MUST Emission (stage 1) MUST be idempotent: a second write of the same activity ID creates no duplicate outbox entry.

Emission can run again for the same activity, for example after a retry or a crash. If each run adds an outbox entry, the recipient gets the same activity more than one time, and each copy costs a delivery attempt. One entry for each activity ID makes a repeated emission safe.
Extends: ARCH-19-001
ARCH-19-003 MUST This codebase MUST retry transport delivery (stage 2) after a transient network failure.

Most network failures are temporary, so a retry usually delivers the activity.
Extends: ARCH-19-001
ARCH-19-007 MUST The outbox worker, not a use case or a handler, MUST hold the retry mechanism for transport delivery.

The outbox worker holds each queued activity, so it can retry with no need to run the use case again. A retry in a use case or a handler would block that work and repeat its protocol logic, although the work is complete when the activity is in the outbox.
Implements: ARCH-19-003
ARCH-19-004 MUST NOT A transport delivery failure (stage 2 error) MUST NOT be interpreted as recipient rejection (stage 3 semantics). Delivery failure means the activity did not reach the recipient; it carries no information about whether the recipient would accept or reject the activity.

A failed delivery tells the sender only that the activity did not arrive. If the sender reads it as a rejection, it can change protocol state for a decision that the recipient never made. The sender and the recipient then disagree about the state of the case.
Derives from: ARCH-19-001
ARCH-19-005 MUST The outbox worker MUST record each delivery outcome in the per-actor process log (Python logging), at the level specs/structured-logging.yaml prescribes. An outcome is a success, a transient failure or a permanent failure.

A delivery outcome is an operational diagnostic. Per-actor transport observability goes to the process log (ADR-0019), where an operator can see why an activity did not arrive.
Extends: ARCH-19-001
ARCH-19-008 MUST NOT The outbox worker MUST NOT write a delivery outcome to the canonical case ledger.

The canonical case ledger holds only protocol-significant assertions that the CASE_MANAGER authors (ADR-0019). Whether a network call succeeded is an operational diagnostic, not such an assertion.
Extends: ARCH-19-005

Core-to-Wire Rendering Port

Governs how core domain objects are rendered into wire-shaped (AS2 camelCase) JSON. Core legitimately needs a wire representation in one place — the CaseLedgerEntry.payloadSnapshot, which CLP-07-011 requires to be receiver-reconstitutable AS2 — and this group makes a driven port the single seam that produces it. Under one object model (ADR-0211) the spelling lives on the core class (ARCH-25-002) and a dimension serializes to a bare state value (ARCH-25-005), so the port's adapter is a plain by_alias dump of the core object; what the group still guards is that core code reaches that dump only through the port.

ID Priority Requirement Related
ARCH-20-001 MUST Core code that needs a wire-shaped form of a core-branch object MUST get it through a driven port in vultron/core/ports/, and never produce it itself. Producing it itself includes a model_dump(by_alias=True) call on a core-branch instance and a rewrite of dumped keys into wire spellings. The alias_generator a core object inherits (ARCH-12-013) is the mechanism behind the port, not a licence for core to dump directly. A dump of an as_Base wire vocabulary object with no core counterpart, such as as_Link, is outside this requirement. A domain type's as_* name is its core class, so it is not such an object. Nor is the activity a received handler holds, which the extractor rebuilds as a core-branch VultronActivity.

A single rendering seam keeps the decision of what goes on the wire (which object, with which @context, failing closed on anything without an AS2 shape) in one adapter instead of at every call site that happens to need camelCase. The requirement is scoped to core-branch objects because core legitimately handles wire objects on the verbatim-capture path; conflating the two would make this requirement unverifiable.
Extends: ARCH-01-004
See also: ARCH-12-013 — explanation: the inherited alias generator is the mechanism behind the port, not a licence to dump

Post-Construction Mutation Safety

Requirements governing validation of core domain objects after construction. Pydantic v2 validates at construction only, so attribute assignment and in-place collection mutation bypassed every type guarantee, allowing a wire-shaped object to occupy a core-typed field and be silently misread as absent (#2232, #2264). Codified by ADR-0064. Source: CONCERN-2261.

ID Priority Requirement Related
ARCH-21-001 MUST Every core domain model (a pydantic.BaseModel subclass defined under vultron/core/models/) MUST have validate_assignment=True in effect, whether set directly or inherited, so that attribute assignment is validated to the same standard as construction.

Construction-time-only validation means the same value the constructor rejects is accepted by assignment. A wire-shaped object in a core-typed field does not raise when read — it reads as absent, and readers substitute an initial state, silently resetting a participant's ladder (#2232, #2264).
ARCH-21-002 MUST NOT The wire branch MUST NOT inherit validate_assignment from core. The flag is set on the core record root CoreRecord, through ValidatedAssignmentMixin. The wire base as_Base thus stays off both core roots (ARCH-12-001), and inbound wire data stays lenient.

Inbound wire data is loose by contract, and the wire classes must parse it. If the wire branch inherits validate_assignment, an assignment on a wire object fails on data that is valid on the wire, and many inbound paths fail. The flag is set on the core root, so the wire base must stay on its own root (ARCH-25-004) to keep the flag off the wire branch.
Refines: ARCH-12-001
Refines: ARCH-21-003
ARCH-21-003 MUST NOT No wire-layer class (under vultron/wire/) MUST have validate_assignment enabled. Strictness belongs at the wire-to-core projection, not on the wire types themselves.

Inbound wire data is loose by contract. Enforcing strictness on the wire types would reject legitimate inbound payloads instead of projecting them (ADR-0062, ARCH-12-001).

Case-Authority Determination

ID Priority Requirement Related
ARCH-24-001 MUST Determining which actor holds single-writer authority for a case MUST have exactly one implementation — a single role-authority resolver that reads CaseParticipant.case_roles — composed by both behaviors/ and use_cases/. No duplicate or twin resolver may exist.

Authority for a case decides who may commit to the case ledger. If more than one resolver answers that question, the resolvers can disagree, and two actors can each act as the authority. Tests that find a site that forgets the check do not stop two resolvers from drifting apart. One shared resolver gives the same answer at every site by construction.
ARCH-24-002 MUST The role-authority resolver MUST reside in a neutral layer below behaviors/ and use_cases/ that depends only on models, ports and enums. Resolving case authority thus needs no behaviors → use_cases import.

Both behaviors/ and use_cases/ must resolve case authority. If the resolver is in one of them, the other must import it or keep its own copy. A behaviors → use_cases import breaks the layer rule (BTND-04-003), and a copy breaks ARCH-24-001. A neutral layer below both lets them share one resolver with no cross-layer import.
Extends: ARCH-24-001
Refines: BTND-04-003
ARCH-24-003 MUST The authority condition node that answers "is the executing actor the case authority" MUST be defined in exactly one module.

A second definition of the node is a second implementation, and two can give different answers for the same actor and case. How many places ask the question is bounded instead by ARCH-24-008: one source for the answer makes the number of askers harmless, which one node definition on its own does not.
Depends on: ARCH-24-001
ARCH-24-007 MUST The shared role predicate MUST answer CVDRole.CASE_MANAGER by delegating to the single role-authority resolver of ARCH-24-001, not by scanning the roster itself.

The predicate is the one source of the authority boolean (ARCH-24-008), so this stops that source disagreeing with the resolver. A roster recording CVDRole.CASE_MANAGER on two participants — the window a role delegation opens (CM-33) — is where a second implementation diverges: a roster scan named the second holder while the resolver named the first, so a path stage admitted a delivery its own gate then skipped, and the handler reported APPLIED having notified nobody (HP-01-005).
Extends: ARCH-24-001
ARCH-24-008 MUST Code that answers whether an actor is a case's authority MUST take that boolean from the shared role predicate asked about CVDRole.CASE_MANAGER, which is its only source.

Who the authority is and whether a given actor is it are two questions. The first returns an actor id that addressing needs. The second returns a boolean, and while several implementations produced it no check could insist on a call: the only enforceable rule was a list of class names, which flagged sites that correctly delegated and missed one that computed the answer from a role list. One callable makes the rule a property of the code, not of a maintained list.
Extends: ARCH-24-001
ARCH-24-009 MUST NOT Code outside the shared role predicate and the single role-authority resolver MUST NOT derive the "is this actor the case authority" boolean from either of its ingredients: the resolver's returned actor id compared with another actor id, or a participant's role list tested for CVDRole.CASE_MANAGER.

Each ingredient answers differently from the predicate in a case that happens. The comparison is exact, so an id differing only by a trailing slash fails its own authority test (OID-01-006). The role-list test answers true for any holder while the resolver names the first in roster order, so a roster recording the role twice makes a tree admit on one answer and skip the effect gated on the other (HP-01-005). Naming both shapes makes the rule checkable with no list of sanctioned classes.
Extends: ARCH-24-008
ARCH-24-006 MUST The authority condition node MUST take its answer from the shared role predicate (ARCH-24-008).

A condition node that resolves authority by its own logic can disagree with every other asker. Asking the one source gives one answer, and the predicate delegates the authority role to the single resolver (ARCH-24-007).
Extends: ARCH-24-008
Uses definition from: ARCH-24-001
ARCH-24-004 MUST NOT No protocol-logic module MUST branch on the case-actor name/URL shape (an is_case_actor_identity predicate or the /actors/case-actor substring) or on Service-hosting location to determine authority, recognition, or routing. Authority derives from the CVDRole.CASE_MANAGER role alone.

A URL shape or a hosting location is incidental: it does not show who holds the CVDRole.CASE_MANAGER role. A hosting test can also fail during the bootstrap window, so the real authority can fail its own test and act as an ordinary participant on its own ledger (CM-02-012). The case replica holds the CASE_MANAGER participant from the moment it is seeded (CP-09-004), so the role gives a stable answer.
Extends: ARCH-24-001
ARCH-24-005 MUST NOT The store-consistency / anti-fork guard that gates which store may append canonical ledger entries (DeclineForeignLedgerCommitNode / store_for_actor) MUST NOT be conflated with authority determination; the two are distinct concerns.

Once role-authority says "you may commit," the store guard refuses, by raising, to mint a canonical index in a store that is not the log's home (which would fork the hash chain, #2626; CLP-10-014). Authority (role) and "where the write may land" (store) are different jobs.

Behavior Tree Integration

Requirements for integrating py_trees behavior trees into Vultron handler functions. Covers the BT execution model, state management via the DataLayer, handler integration patterns, actor isolation, concurrency constraints, and failure diagnosis. Complex protocol workflows such as report validation, case creation, and embargo management must be implemented as BT nodes or subtrees.

File ID: BT

Workflow-Specific Trees

ID Priority Requirement Related
BT-06-005 MUST Cascades from a parent subtree to a child subtree MUST be expressed as subtrees within the use case's behavior tree, not as procedural calls made after the tree has run.

A cascade that runs after the tree returns is outside the guards, logs and failure reports of the tree. It can also run when the outcome of the tree must stop it. As a subtree, the cascade shows in the tree structure, and it does not run when its parent fails.
BT-06-006 MUST NOT Protocol-observable actions and state transitions MUST NOT be performed as procedural code outside the BT.

Code outside the tree is not subject to the guards, the ledger commit or the failure reports of the tree. Thus a protocol action in that code has no audit, and the tree cannot refuse it. When every such action is in the tree, the tree is the full record of what the actor did.

Call-Out Point Abstraction Layer

ID Priority Requirement Related
BT-18-029 MAY A capability implementation MAY cache the external data it fetches. Where the cache lives, how long an entry stays fresh and what clears it are the implementation's choice. The call-out seam provides no cache.

Only the implementation knows how fast its external source changes, so only it can judge when a cached answer is stale. A shared cache in the seam would need a staleness policy that the protocol cannot judge. A stale answer is a wrong answer of the implementation, like any other. A cache is also one way a slow external lookup meets the call-out time budget.
Refines: BT-18-015 — Caching is one way an implementation meets the time budget.
BT-18-030 SHOULD NOT A tree that carries content its caller supplied SHOULD NOT consult a Composer for that content. A Composer call-out point sits at a step where the tree itself produces the artifact.

A tree that carries content sends what its caller wrote, and a tree that produces content makes the artifact it sends. When the two stay apart, a reader can tell from the tree who wrote each artifact. A caller that wants drafted content drafts it before it calls the trigger. Reusing earlier text is the Composer implementation's own choice and adds no call-out point.
Refines: BT-18-028 — Places the Composer that BT-18-028 defines by its output.
BT-18-039 MUST Where the case file or the actor's own store can hold the fact a Retriever call-out point fetches, a read-first guard MUST precede the call-out point and skip it when the fact is present.

Asking for a fact the actor already holds spends call-out budget (BT-18-015) on a known answer, and the answer can contradict the case. The guard reads the case file or the actor's own records, never case bookkeeping (CLP-07-022). Each Retriever call-out point says in its docstring whether its fact can be held there. A cache of external data belongs to the capability implementation instead (BT-18-029).
Refines: BT-18-028 — Places the Retriever that BT-18-028 defines by its output.

BT Layer Dependency Model

Rules governing the dependency direction between BT nodes and use-case classes. Violations of these rules create circular dependency risk, un-auditable call chains, and excessively large update() methods.

ID Priority Requirement Related
BT-22-001 MUST NOT A BT leaf node's update() method MUST NOT directly instantiate or call a use-case class.

Use-case classes are the handlers that create BTs. They are not work items to be called from within a BT node. A use case called from inside a BT node creates a BT→UseCase→BT→UseCase call chain that cannot be audited or preempted. The BT tree structure is the source of truth for protocol behavior, so any logic that executes outside it is invisible to analysis and audit.
BT-22-006 MUST A multi-step workflow that a BT leaf needs MUST be a child subtree of the current tree, not a use-case call embedded in update().

An in-tree child subtree keeps the full behavior visible in the tree, and a parent Selector can preempt it.
Extends: BT-22-001
BT-22-002 MUST NOT BT nodes in vultron/core/behaviors/ MUST NOT import private helpers or functions from vultron/core/use_cases/.

Importing a use-case helper into a BT node inverts the hexagonal layer boundary and creates circular dependency risk. The import direction is the enforcement mechanism for the layer rule. Identified as BT-IDM-02 in notes/bt-canonical-reference.md.
BT-22-004 MUST The dependency direction between BT nodes and use cases MUST be use_cases/ → behaviors/ (use cases create BTs), never behaviors/ → use_cases/ (BT nodes importing from use cases).

The one-way dependency from use cases into behaviors is the structural enforcement of the hexagonal layer boundary; reversing it creates circular dependency risk.
BT-22-005 MUST If a helper is needed by both a use case and a BT node, it MUST be extracted to a shared utility module (e.g., vultron/core/behaviors/shared/ or a domain-model method) that neither layer owns.

A shared utility module is the canonical resolution when a helper is needed at both layers; placing it in either layer would invert or entangle the layer boundary.
BT-22-003 SHOULD A BT leaf node's update() method SHOULD NOT exceed approximately 30 lines of logic. Nodes whose update() grows to 60–100+ lines typically encode multiple responsibilities (read, validate, create, persist, broadcast) that are better expressed as distinct leaf nodes in a named subtree. Smell signals include more than 3–4 distinct responsibilities, multiple dl.save() calls, Boolean constructor parameters that silently activate optional branches, and internal if/else chains that should be separate Sequence/Selector children.

Long update() methods defeat the core purpose of behavior trees — simple, auditable, composable leaves whose complexity is visible in tree structure rather than in individual nodes. Decomposing a god node into a named subtree factory makes the workflow readable by inspection. Identified as BT-IDM-03 in notes/bt-canonical-reference.md; see also specs/behavior-tree-node-design.yaml BTND-02-001.

Behavior Tree Node Design

Formal requirements for BT node parameterization, composability, and reuse in the core behaviors package. Covers node context injection, blackboard hygiene, module ownership, and the fractal composability pattern that applies at every depth of the tree hierarchy.

File ID: BTND

BT Status-Write Node Transition Validation

ID Priority Requirement Related
BTND-10-002 MUST The per-dimension transition rules, role gates and cross-machine entailments of a ParticipantStatus write MUST be composed into one evaluator that returns every violated rule.

Two paths that each have their own copy of the transition checks and role gates drift apart. Each path enforces some rules that the other path does not, and their messages diverge (ARCH-15-004). When the rule set is composed one time, as composite_state_violations() does, all paths use the same rules. Shared individual predicates do not give that result.
Extends: BTND-10-001
Refines: ARCH-15-004 — One canonical copy of each transition and role predicate
Implements: EH-07-001 — Reporting every violation at a ParticipantStatus write boundary
BTND-10-003 MUST A ParticipantStatus write node MUST keep its own call to the shared evaluator, even when an upstream guard node validates the same write.

BTND-10-001's fail-closed-regardless-of-guard-coverage rule is not hypothetical here: CreateParticipantStatusNode is reached from develop_fix.py, deploy_fix.py, close_case_effect.py and two sites in leave.py without passing through ValidateTriggerTransitionsNode, so for those paths its checks are the only validation. Both nodes validating cannot double-report on the trigger path: the guard fails first and the Sequence aborts before the write node ticks.
Refines: BTND-10-001
Uses definition from: BTND-10-002
BTND-10-004 MUST The ParticipantStatus write node MUST run only as a child of a behavior tree, never built and ticked inside another node's update().

Five sites did exactly that (develop_fix.py, deploy_fix.py, close_case_effect.py and twice in leave.py), producing six nested update() calls because develop_fix.py ticks one shared helper-built node from two places. A nested update() call skips setup() and the tick cycle, so declared ports are never resolved and the enclosing composite cannot observe the child's status; deploy_fix.py and develop_fix.py additionally wrapped the call in try/except, which is the failure-swallowing shape notes/bt-pitfalls.md documents under "Always Check BTBridge.execute_with_setup Return Value". Six further nodes bypassed the write node entirely, giving three distinct ways to perform one write. One way is the point: two mechanisms for one purpose must both be maintained and tested, and they drift (CS-22-001).
BTND-10-005 MUST The ParticipantStatus write node MUST obtain case_id from its declared blackboard port, never from a constructor argument.

A port is the only way to supply case_id that works in all trees. In received trees, the tree finds the case at tick time from the report, so the case is not known at build time. In every other tree the runner seeds /case_id from the event or trigger request before the first tick (BT-25-007). Thus one mechanism serves both.
Depends on: BTND-10-004
Refines: BTND-01-006
Refines: BTND-01-007
BTND-10-009 MUST Every writer of a ParticipantStatus, not only every node that validates one, MUST call that evaluator instead of the individual is_valid_*_transition() or violation_* predicates.

Two paths that each have their own copy of the transition checks and role gates drift apart (ARCH-15-004). The rule applies to every writer, not to every validator (ADR-0089). Otherwise a writer that validates nothing, or a writer that is not a node, is not covered. This check does not find the wire projection (as_CaseParticipant.append_rm_state), which builds as_ParticipantStatus from flat fields. That code needs its own check.
Extends: BTND-10-002
BTND-10-010 MUST Every writer of a ParticipantStatus MUST report every violation that the evaluator returns.

A writer that reports only the first violation hides the rest. The sender then fixes one problem, retries, and meets the next one (EH-07-001).
Extends: BTND-10-002
Refines: EH-07-001
BTND-10-011 MUST The ParticipantStatus write node MUST take the subject actor only as an explicit argument, never from the executing actor on the blackboard.

The blackboard actor_id is the executing actor, and the subject of the write is often a different actor, such as the deferring actor, the sender or the leaver. A fallback writes the status onto the wrong participant, and no error shows. It also gives the node two paths, and each path needs its own tests.

Case Management

Requirements for VulnerabilityCase lifecycle management, CASE_MANAGER responsibilities, and the RM/EM/CS/VFD state model. Covers actor isolation at the protocol level, the distinction between participant-specific and participant-agnostic state, case initialization sequencing, embargo acceptance ownership, and the invitation acceptance lifecycle.

File ID: CM

CASE_MANAGER Lifecycle

ID Priority Requirement Related
CM-02-011 MUST An actor is the single-writer authority for a case if and only if it enacts CVDRole.CASE_MANAGER in that case's participant roster (CaseParticipant.case_roles). Authority MUST be determined from the role, never from hosting location or from the actor's name or URL shape.

The role is the only signal of authority in the protocol. The case roster records it, only a ledgered act changes it, and every replica reads the same value. The hosting location, the name of an actor and the shape of its URL are deployment facts that are different between topologies. A check that uses them gives different answers for the same case. The case-actor name is only a demo convenience.
Refines: CM-02-002
CM-02-012 MUST The actor enacting CVDRole.CASE_MANAGER MUST recognize its own canonical ledger entries as authoritative from replica-seed onward, including during the bootstrap window before any co-located Service object carries the case context.

The replica holds the role membership from the moment it is seeded. A check that needs a co-located Service object with the case context fails before that object exists. Until that object exists, such a check makes the CASE_MANAGER treat its own ledger entry as the entry of a participant.
Uses definition from: CM-02-011
CM-02-013 MUST NOT The case-actor name and any .../actors/case-actor URL MUST NOT be treated by any protocol logic as evidence of authority, recognition, or routing; they are provisioning conveniences with no protocol meaning.

A stable inbox URL for the enacting actor is a convenience for provisioning (ADR-0041). The authority is the role in the case roster (CM-02-011, ADR-0088). Logic that reads authority from the case-actor name or the shape of the URL gives an incorrect answer in a deployment that names or hosts its CASE_MANAGER differently.
Refines: CM-02-011

Domain Model Architecture

ID Priority Requirement Related
CM-08-001 SHOULD The system SHOULD maintain a clear separation between the wire representation, domain model, and persistence model for CVD objects

Wire shape, domain rules and storage change for different reasons. There is one object model, and AS2 is its serialization (ADR-0211). Thus, the separation is at the edges: the parse edge, the rendering port and the store. A new storage backend or an AS2 rendering detail then changes one edge and does not change the domain rules.

Per-Participant Embargo Acceptance

ID Priority Requirement Related
CM-10-007 MUST This codebase MUST run the active-participant check (CM-10-004) in the shared recipient selection that every case-content send uses, never at individual send sites. An embargo-ending notice owed to a bound participant that is not active (CM-31-009, CM-31-030) is not case content.

Almost every send of case content selects its recipients from the roster. If each send site has its own check, the next send site that someone writes can omit it. One shared selection (vultron/core/participants/recipients/) prevents this. The embargo-ending notices are an exception. They must reach participants that are not active, including the due notices of a removed participant (ADR-0116).
Implements: CM-10-004
See also: CM-31-009 — scope boundary: the notice is not case content
See also: CM-31-030 — context for the reader
CM-10-009 MUST The shared recipient selection MUST deliver a stub Invite, or an embargo Invite (EP-09), to an inert participant that has not been removed (CM-31-013). Such an Invite is not case content.

An Invite asks a participant to join the case or to consent to an embargo. An inert participant is the one that has to answer it. If the content gate held the Invite back, the participant could never become active.
Extends: CM-10-007
See also: CM-31-013 — context for the reader

CASE_MANAGER-Delegated Activity Authorship Contract

Requirements for how trigger use cases and received trees assign actor, attributed_to and in_reply_to when the CASE_MANAGER emits an Activity on behalf of a requesting participant (delegated message). The reference implementation is delegated_authorship() (vultron/core/behaviors/delegated_authorship.py). Codified from CONCERN-2170.

ID Priority Requirement Related
CM-24-004 MUST Trigger use cases that emit delegated Activities MUST queue the constructed Activity in the CASE_MANAGER's outbox, not in the requesting participant's outbox.

The outbox of the CASE_MANAGER is the delivery path to other participants. If the requesting actor's outbox holds a delegated Activity, the activity bypasses the CASE_MANAGER as the authoritative intermediary. This breaks the CaseLedgerEntry audit trail.
Extends: CM-24-001
CM-24-009 MUST Each delegated emit MUST sit in a composite gated on the executing actor holding CVDRole.CASE_MANAGER for the case, not on an actor_id comparison.

The authority is a role in the case, and any Actor type can hold it. Thus a comparison of actor_id with a computed case_actor_id checks the wrong thing. When a role gate controls the emit, the executing actor is the CASE_MANAGER. Thus the activity and its outbox entry are always in one store (BT-05-006, ADR-0073). Without the gate, the helper allows identity spoofing. Any actor that reaches it can emit an Announce with the CASE_MANAGER as author to every participant.
Extends: CM-24-004
CM-24-010 MUST The delegated emit MUST execute on the container that hosts the CASE_MANAGER. A requesting participant whose container does not host it sends the CASE_MANAGER its own activity, and the CASE_MANAGER's received tree performs the delegated emit.

An emit in the name of the CASE_MANAGER from a container that does not host it bypasses the CASE_MANAGER. The activity leaves a store that does not hold the ledger. The canonical entry can then come only from a copy of the emit that is delivered to the CASE_MANAGER. Also, such a container cannot sign the activity (OX-10).
Extends: CM-24-004
Derives from: CM-24-011
CM-24-011 MUST NOT A container MUST NOT execute a tree, or enqueue an activity, as an actor it does not host (ADR-0109).

A container holds the stores, keys and outboxes of its own actors only. A tree run as another actor would write to a store that is not that actor's, and an activity enqueued for it would leave from an outbox that cannot sign for it (OX-10).

Participant Removal and Reinstatement

Removing a participant withdraws its entitlement to case content and keeps its record. The Case Owner requests removal and reinstatement; the CASE_MANAGER applies them, records each as one ledger entry, and tells the affected participant directly (ADR-0116).

ID Priority Requirement Related
CM-31-002 MUST This codebase MUST compute whether a participant is active by one case-level check over the CM-10-004 stored facts, never over RM CLOSED (#4100). Those facts are that the participant joined, by case initialization or by accepting the stub Invite, and is not removed. While an embargo is active, they include that its consent row for that embargo is AGREED.

Whether an embargo is active is case state a participant record cannot see, so the full answer lives on the case. One check means every send site gets the same answer.
Uses definition from: CM-10-004
CM-31-018 MUST NOT This codebase MUST NOT store whether a participant is active.

An inferred status that is stored goes stale whenever one of its inputs changes without rewriting it; the precedent is signatory and lapsed consent (CM-18-001).
Extends: CM-31-002
CM-31-019 MUST NOT A participant-level property in this codebase MUST NOT compute a partial answer under a name that reads as "active".

A partial participant-level property would read as "active" at a send site and leak embargoed content to a non-signatory.
Extends: CM-31-002

Outside-System Case Reader

The read-only port through which a case held by an outside system, such as VINCE, reaches the core, and what its translation contains. A read-write port for a later two-way gateway is a separate interface, not specified here.

File ID: CRD

Case Reader Port

ID Priority Requirement Related
CRD-01-001 MUST The core MUST declare a CaseReader port that returns an outside system's case, given that system's case identifier.

A port the core declares states what the core needs from any outside system, so each new system adds an adapter rather than a new interface.
CRD-01-002 MUST NOT The CaseReader port MUST NOT declare a method that writes to the outside system.

A reader that cannot write is safe whatever its adapter does. A write method that refuses every call is still a write path in the interface.
CRD-01-003 MUST A CaseReader adapter MUST return the case as a core case ledger, together with the facts it could not translate.

A case is its ledger and the projection of that ledger. A snapshot alone loses the order and timing the CVD desiderata are about.
CRD-01-004 MUST Each translated ledger entry MUST cite the outside-system record it was translated from.

Every insight must trace back to the record it rests on, so an analyst can check a surprising score against the outside system.
CRD-01-005 MUST A CaseReader adapter MUST return each outside-system fact it cannot translate with its result.

A fact that is dropped silently makes the analysis look complete when it is not.
CRD-01-006 MUST A translated ledger entry MUST name as its actor the participant who performed the act in the outside system.

The projection and the measures then read a translated case exactly as a native one. This holds only while a translation is not stored and does not enter a protocol path, as in the shadow's first version (ADR-0190).

What a Case Reading Carries

ID Priority Requirement Related
CRD-02-001 MUST A CaseReader result MUST hold five parts: the ledger, the entry citations, the inferences, the untranslated facts and the unobservable facts.

The ledger stays unmarked so the projection reads it as a native one. The other parts let a reader tell a stated fact from an inferred one, and an absent fact from one the source could never supply.
CRD-02-002 MUST Each inference MUST name its ledger entry, its mapping rule, and a caveat stating what the source did not say.

An analyst shown an inferred state can then check the rule against the source record instead of trusting the state as stated.
CRD-02-003 MUST Each untranslated fact MUST carry one reason: unknown value, no counterpart, rule conflict, or no time.

The reason tells an analyst whether the gap is in the mapping, in the source's data, or in this one case.
CRD-02-004 MUST A CaseReader adapter MUST declare what its source cannot observe and copy that declaration into every result.

Each outside system has its own blind spots. Declared once by the adapter, they reach every consumer with the reading itself.
CRD-02-005 MUST A consumer of a case reading MUST read a state dimension or event the reading declares unobservable as unknown, never as false.

A case is not scored as having no fix when its source cannot say whether a fix exists.
CRD-02-006 MUST A translated entry MUST take both its times from a time the source states, never from a clock read.

A translation reports when the act happened in the outside system. A clock read would date every entry to the moment of reading (ADR-0176). An act whose own record states no time takes a stated time the mapping rule names, and is listed as an inference.

Code Style Specifications

Defines code formatting, import organization, and coding style standards for Python code in the Vultron project.

File ID: CS

Circular Import Prevention

ID Priority Requirement Related
CS-05-001 MUST Core modules SHALL NOT import from application layer modules

Core holds the protocol rules, and every adapter and driver depends on it. An import from a layer above would make core depend on the code that depends on it. That creates import cycles, and core could not load or run its tests without those layers. ARCH-01-001 states the full layer rule.
Refines: ARCH-01-001
CS-05-003 MUST Shared types and errors SHALL be placed in neutral modules

A type that two layers both need cannot live in either one. If it did, the other layer would have to import it, and that import goes in the wrong direction or closes a cycle. A neutral module such as vultron/errors.py or vultron/enums/ depends on no layer, so every layer can import it.

Code Reuse

ID Priority Requirement Related
CS-09-001 SHOULD NOT New code SHOULD NOT duplicate logic already present elsewhere; prefer extracting shared logic into reusable helpers, base classes, or type aliases

Duplication inflates maintenance cost and allows bug fixes to be applied inconsistently

Port and Adapter Data Exchange

ID Priority Requirement Related
CS-10-001 MUST Data passed across a port/adapter boundary MUST use named, domain-typed objects, not type-erased containers such as plain maps or untyped base classes.

Ports that accept or return type-erased containers (dicts, bare base models) serve as machine-readable contracts in name only — the type system cannot enforce what passes through them. Naming the specific domain type at the boundary makes the contract explicit, enables static verification, and surfaces layer-coupling violations at compile/analysis time rather than runtime.
CS-10-004 MUST A port interface signature MUST declare its parameters and return values as specific domain types, not as generic base types or untyped collections.

The signature is where a type checker reads the contract of a port. A specific domain type there lets the checker reject a wrong object at each call site.
Implements: CS-10-001

Datetime and Timezone Conventions

ID Priority Requirement Related
CS-13-001 MUST Every datetime value the application produces MUST be timezone-aware.

Naive datetimes are ambiguous in a distributed system where actors may run in different timezones.
CS-13-009 MUST Every datetime value the application produces MUST use UTC.

Actors may run in different timezones. When every value the application produces is in UTC, no reader needs to convert an offset to compare two times.
Extends: CS-13-001

Configuration Management

Requirements for unified, structured application configuration in Vultron. Configuration uses YAML files backed by Pydantic-based models loaded via pydantic-settings with environment variable override support.

File ID: CFG

Config File Format and Loading

ID Priority Requirement Related
CFG-02-005 MUST The application MUST start successfully with no config file and no relevant environment variables set; all fields have sensible defaults.

A developer or a test must be able to run a node with no setup. If a missing file or variable stopped the start, every test and every first run would need configuration that adds nothing. Defaults that work on a local host remove this step.

DataLayer Port

Behavioural contract that all DataLayer adapter implementations MUST satisfy. Covers auto-rehydration on read, type-safe write operations, and port isolation.

File ID: DL

Per-Actor Store Isolation

ID Priority Requirement Related
DL-07-009 MUST When execution is scoped to an actor, every store reference reachable from that scope MUST be reconciled to that same actor, not the store alone.

If only the store moves to the executing actor, other components on the same blackboard can still hold the store of a different actor. For example, an adapter that persists an outbound activity can write it to the store of the requesting actor while the outbox entry goes to the store of the executing actor. Delivery then cannot read the activity and skips it with no error, so the recipient is never told.
DL-07-025 MUST A component injected with its own store MUST offer a named way to rebind it to another actor's store, or hold no store.

Rebinding is opt-in, so that a stateless collaborator is not replaced without the knowledge of its caller. The opt-in is on the type, not on the instance, because a test double answers any attribute.
Implements: DL-07-009
DL-07-026 MUST NOT The writes of one logical operation MUST NOT land in the stores of two actors.

An operation split across two stores is half-visible to each actor. An activity and its outbox entry in different stores leave delivery with a queue entry it cannot read.
Extends: DL-07-009

Storage Fidelity for Inline-Required References

Persistence dehydrates AS2 reference fields to their id to avoid storing a nested object twice. Some references must not be dehydrated, because the protocol requires the object to be carried rather than referenced and nothing else ever gives it a record to be read back from. Added by ISSUE-2482, where the round-trip silently emptied a Create(CaseProposal) of its report.

ID Priority Requirement Related
DL-08-001 MUST NOT Persistence MUST NOT dehydrate a reference field to its id when the declaring model requires that field to carry the object inline.

Dehydration is only reversible when the nested object has a record of its own, and inbound activities are given records only one level deep — so a second-level inline object collapses to an id that no read can expand. CP-01-004 requires as_CaseProposal to carry its as_VulnerabilityReport inline for exactly the reason that makes the collapse unrecoverable: the receiver may not hold the report and this codebase dereferences only the few references AKM-05-007 lists (AKM-03-003).
DL-08-004 MUST A model MUST be able to declare which of its reference fields it requires to carry the object inline.

The declaration belongs on the model, because that is where the invariant is. A model that requires a reference inline then says so once, next to the field.
Extends: DL-08-001
DL-08-005 MUST The storage layer MUST read the model's inline declaration, not keep its own list of the affected types.

A lookup table in the storage layer is action at a distance from the field it governs. A new inline-required field would then be silently collapsed until somebody also edited the table.
Extends: DL-08-004
DL-08-002 MUST A type annotation MUST NOT be relied on as the record of an inline-only requirement when that annotation also admits a URI string.

ActivityStreamRequiredRef[T] expands to T | as_Link | str. A bare URI therefore passes the type check, and model_validate accepts a dehydrated object with no error. If the annotation is the only record of an inline-only rule, the storage layer has nothing to consult. A collapsed reference then fails far from its cause, and no message names the cause.
Extends: DL-08-004
DL-08-003 MUST An activity whose reference field names another actor MUST declare that field inline-required.

Each actor's record lives in its own store (ADR-0073). A peer that an outbound activity names has no record in the store of the sending actor, because actor discovery is not implemented (ADR-0024). Dehydration is reversible only against such a record (DL-08-001), so a peer actor stored as its id cannot be expanded again. Each activity that names a peer, such as _RmInviteToCaseActivity in object_ or _OfferCaseOwnershipTransferActivity in target, declares that field in inline_required_refs. The role offer also declares its object_, a CaseParticipantRole that the factory creates inline and no path persists. Each factory wraps a peer named by a bare id as an as_Actor, so the peer travels inline. Each other required typed reference names an activity, which stays inline, or a case, report, status, participant or embargo, which the sender holds. The parser stores a received activity as its base class. Storage therefore also reads the inline declaration of the semantic class that the activity matches. For example, the CASE_MANAGER holds no record of an ownership transferee, so its ledger snapshot must carry the transferee inline (CLP-07-006). Without the declaration, outbox delivery refuses the stored activity for AKM-03-003, and the invitee is never told about its invitation. Read-back must also re-type the inline object, or semantic matching classifies the activity as UNKNOWN. For this reason the re-typing set (_inline_typed_fields in db_record/ref_fields.py) is wider than the dehydration set and includes context.
Uses definition from: DL-08-004

Embargo Management Behavioral Requirements

Event-Condition-Action behavioral requirements for Embargo Management (EM). Each group is triggered by either a received EM message or a local EM state transition, and specifies typed preconditions, ordered steps, and postconditions that implementations must satisfy.

File ID: EMB

EM Write-Boundary Consolidation

Requirements ensuring that all EM state transitions are executed through the EmbargoLifecycle service layer rather than written directly to case.current_status.em in BT nodes or helpers. Identified by audit in CONCERN-2412: three BT nodes (EmActivateEmbargo, ClearEmbargo, SetDefaultActiveEmbargoNode) bypass EmbargoLifecycle with direct EmDimension assignment. Complements SM-04-001 (general write-boundary guard requirement) with an EM-specific routing rule.

ID Priority Requirement Related
EMB-18-001 MUST This codebase MUST make every change to a case's embargo register through EmbargoLifecycle, or through apply_embargo_change() for an act converted to the copy model. A change to the register is also a change to the EM state derived from it (ADR-0122). Each public operation of EmbargoLifecycle, such as propose_embargo(), activate_embargo() and reject_embargo_proposal(), applies one register step. The one apply function, apply_embargo_change(), applies the act's ledger entry (ADR-0124, CM-23-016).

EmbargoLifecycle and the one apply function are the only embargo writers. A path that goes around both skips the fail-closed reads of EMB-18-003, the PEC cascade, and the shared starting-state and EM checks. Also, the EM value the register derives overwrites a status EM that a path assigns directly.
See also: CM-23-016 — context for the reader
EMB-18-008 MUST NOT A BT node or helper function MUST NOT apply a register step itself, or assign case.current_status.em, then call dl.save(case) in place of the EMB-18-001 writers.

A path that goes around both writers skips the fail-closed reads of EMB-18-003, the PEC cascade, and the shared starting-state and EM checks. The EM value the register derives also overwrites a status EM that a path assigns directly.
Derives from: EMB-18-001
EMB-18-002 MUST NOT A BT node or helper MUST NOT check an embargo register step as a non-blocking warning-only guard and then write regardless of the result.

A warning-only guard looks like validation but lets an invalid state persist. The correct pattern is to go through EmbargoLifecycle (EMB-18-001), which fails closed in STRICT mode.
Extends: EMB-18-001
EMB-18-009 MUST A refused embargo register step MUST either raise or make the BT node return Status.FAILURE without writing to the DataLayer.

A refusal that still writes lets an invalid state persist. EmbargoLifecycle (EMB-18-001) fails closed in STRICT mode, so a refused step leaves the store unchanged.
Extends: EMB-18-002
EMB-18-003 MUST A path that activates an embargo register entry MUST already hold that EmbargoEvent's record in the same store.

The EP-05-001 comparison reads the replaced embargo, so it holds only if no case names an embargo its store cannot read. Any writer that accepts a bare id lets a case name an unreadable record: an activation writer can, and so can seeding a case whose embargo arrived as a bare reference. A replica can fetch the record from the CASE_MANAGER (AKM-05-003). At the CASE_MANAGER, a deferral waits for a record that no path delivers.
Extends: EMB-18-001
EMB-18-010 MUST The EmbargoLifecycle activation writers (activate_embargo(), initialize_creation_embargo()) MUST read the record of the embargo being activated and of the one it replaces (EP-05-001).

The EP-05-001 comparison reads the replaced embargo, so it holds only if the writer reads both records before it changes the register.
Extends: EMB-18-003
Implements: EP-05-001
EMB-18-011 MUST An EmbargoLifecycle activation writer MUST fail closed on an unreadable activated or replaced embargo (EMB-18-010) before changing the register. An unreadable replaced embargo is a broken invariant, reported as a refusal, not deferred.

A replica can fetch the record from the CASE_MANAGER (AKM-05-003). At the CASE_MANAGER, a deferral waits for a record that no path delivers, so the writer refuses instead.
Extends: EMB-18-010
EMB-18-006 MUST This codebase MUST hold the EM transitions of EMB-18-005 as one declarative table.

A check only in tests protects only the register states a test reaches. Refusing at the step makes a register defect fail when it happens, on every node, and gives tools that draw or export the EM machine one table to read (ADR-0130).
Implements: EMB-18-005
EMB-18-013 MUST Applying an embargo register step MUST refuse, with no write, a step whose EM move is not in the EMB-18-006 table.

A check only in tests protects only the register states a test reaches. Refusing at the step makes a register defect fail when it happens.
Extends: EMB-18-006
EMB-18-014 MUST The CASE_MANAGER and every replica MUST apply the EMB-18-013 check as part of the one apply function (ADR-0124).

One check in the one apply function makes a register defect fail on every node, not only on the node that made the step.
Extends: EMB-18-013

Embargo Policy

Requirements for a standardized embargo policy record associated with an Actor profile. Allows actors to declare their default embargo preferences so that coordinators can evaluate compatibility before proposing an embargo or inviting an actor to a case.

File ID: EP

Embargo Negotiation Relays Through the CASE_MANAGER

How an embargo proposal — the first one for a case or a revision of the active embargo — reaches every participant and every replica in the CASE_MANAGER topology. The behavioural specs (EMB-01 through EMB-06) are written in the voice of the formal protocol, in which every Participant is a peer and every Participant "receives EP" or "receives EV". Here a participant addresses its proposal to the CASE_MANAGER alone (PCR-08-001), so the Participant receiving EP or EV is the CASE_MANAGER on receipt, and every other participant learns the resulting case state from the ledger. The protocol interactions the behavioural specs define still happen: the CASE_MANAGER relays the proposal to the participants as an Invite, they answer the CASE_MANAGER, and the owner's answer decides. Each step is recorded in the ledger. Ledger entries carry case state to replicas and set no parse-and-respond expectation; they augment the negotiation as the record of the case, they do not replace it. Decided by ADR-0113 from Concerns #3892, #3836 and #3863 for revisions; generalised to every proposal, with the acknowledgement, RSVP-deadline, trigger-side write and invitee rules below, by its 2026-09-30 amendment from Concern #3918.

ID Priority Requirement Related
EP-09-007 MUST Every ledger semantic type the revision relay commits MUST have a replica apply node reachable from create_add_log_entry_tree (RSH-08-004). The node applies what the entry carries by copying it through the one apply function (ADR-0124, CM-23-016).

Replicas take state from the ledger, so a semantic type with no replay node is a state change no replica can see (ADR-0108). A relay entry with no replay node is stored and ignored, and a replica's EM then stays ACTIVE through a whole revision cycle. Covering every semantic type of the relay is what makes the participant-side embargo trees gateable with no further work.
Refines: RSH-08-004
Refines: CM-23-016

Event-Driven Control Flow

Defines the event-driven processing model for Vultron actors: how primary events enter the system, how cascading consequences are produced automatically, and what constraints apply to demo scripts and integration tests.

File ID: EDF

Definitions

ID Priority Requirement Related
EDF-01-001 MUST A primary event is an externally supplied stimulus or an actor-initiated decision: a message delivered to an actor's inbox, or a trigger invocation representing an actor choosing to begin an action.

The EDF rules treat a primary event differently from what follows from it. For example, a demo may inject only primary events (EDF-05-001). A fixed definition lets each rule and each reviewer tell the two apart.
EDF-01-002 MUST A cascade is an automatic, BT-driven consequence that occurs within a single actor's execution context as a result of processing a primary event or an earlier cascade step.

A cascade is the work an actor must do without being told again. A fixed definition separates it from a primary event. A manual call for a cascade step can then be identified as a defect (EDF-05-002).
EDF-01-003 MUST A cascade chain is the full sequence of causally connected steps that flows from one primary event: within-actor cascade → outbox emission → delivery to peer inbox → peer's own cascade → and so on.

The consequences of one primary event can cross several actors. A name for the whole chain lets the rules say where each step runs and what a demo must wait for. It also keeps the delivery between actors separate from the cascade of one actor.

Event-Driven Processing

ID Priority Requirement Related
EDF-02-001 MUST Every protocol-significant action in Vultron MUST be triggered by an event, not by direct procedural calls from upstream code.

An action that runs only when upstream code calls it does not run when the same event arrives another way. When an event triggers every protocol-significant action, the same input always causes the same action, through the inbox or through a trigger.
EDF-02-002 MUST The system MUST follow an "on event, do" model: business logic is invoked in response to events; events are not invoked by business logic.

When business logic calls the next step itself, the order of steps is in the callers, and each caller can get it wrong. When logic runs only in response to events, each step depends only on the event that caused it.
EDF-02-003 MUST NOT A caller MUST NOT invoke a handler directly, bypassing the inbox dispatch pipeline.

The inbox pipeline parses each activity, extracts its semantics and checks its case context before a handler runs. A caller that invokes a handler directly skips those steps. The handler then acts on input that the pipeline did not check.
Derives from: EDF-02-005
EDF-02-004 MUST NOT A handler MUST NOT deliver an activity directly to a peer actor.

The outbox records each outbound activity, keeps the delivery order to each recipient and retries failed deliveries. A handler that sends directly to a peer skips that record and those retries, so nobody can see or repeat a lost delivery.
Derives from: EDF-02-006
EDF-02-005 MUST The inbox MUST be the sole entry point for inbound activity processing.

One entry point means every inbound activity passes the same parsing, extraction and case checks. A second entry point would let some activities reach core logic unchecked.
EDF-02-006 MUST The outbox MUST be the sole exit point for outbound activity delivery.

One exit point means every outbound activity is recorded, ordered and retried in the same way. A second exit point would send activities that no record shows.

Cascade Implementation

ID Priority Requirement Related
EDF-03-005 MUST NOT Cascade logic MUST NOT be duplicated between actors; each actor's BT handles its own local cascade, triggered by receipt of the peer's outgoing activity.

When one actor runs the cascade of another, the state of the receiver depends on code the receiver does not run. Each actor runs its own cascade only from what it receives, so its state follows from its own processing of the messages it holds.

External Decision Nodes

ID Priority Requirement Related
EDF-04-001 MUST When a cascade reaches a point where the actor cannot proceed autonomously, the stopping point MUST be represented as an explicit external decision node in the BT.

A stop that has no node in the tree cannot be found by inspection or by a test. An explicit node shows where the actor waits and what input it needs. The stop is then a known decision point and not a hidden defect.
EDF-04-003 MUST The arrival of the required external input (a trigger invocation, an inbox message, or a UI response) MUST cause a fresh evaluation that determines where the exchange stands and proceeds accordingly.

No tree instance stays alive between events, so no node waits to be ticked again. The arrival of the input must start a new evaluation. That evaluation first determines the state of the exchange (ASK-02-001), so it continues from the correct point.

Causal Gating in Demo Scenarios

ID Priority Requirement Related
EDF-06-001 MUST The harness MUST gate each step that depends on an asynchronous effect on positive evidence that the actor that produces the effect committed it.

A scenario ordered by time ("A, then B") and not by cause ("A, therefore B") makes each step race asynchronous delivery. Elapsed time, script position and a 202 response show only that a request was accepted, not that its effect was committed. A gate on committed evidence removes that race (ADR-0058).
EDF-06-009 MUST NOT The harness MUST NOT treat elapsed time, a step's position in the script, or an HTTP 202 acknowledgement as evidence that an effect was committed.

Elapsed time, script position and a 202 response show only that a request was accepted. They do not show that the actor committed its effect. A gate on them still races asynchronous delivery (ADR-0058).
Derives from: EDF-06-001

Handler Protocol

Handler use-case classes process VultronEvent domain objects and implement protocol business logic. All handlers follow a common contract defined by the UseCase Protocol.

File ID: HP

Handler Signature

ID Priority Requirement Related
HP-01-007 MUST Every received use case MUST declare its sender entitlement exactly once, as either a sender rule (HP-01-008) or an exemption that carries a reason.

When each handler has its own sender check, the check gets copied in slightly different forms. Some handlers do not get it at all. Only an audit finds the missing checks. The factory and a test read one declaration. Thus a missing check is a test failure. The declaration also shows the remaining gaps as a visible exemption list (ADR-0115).
Implements: HP-01-006
HP-01-019 MUST The receive-tree factory MUST compose the guard that matches each declaration (HP-01-007) from the single sender-entitlement module into the tree's guard stage.

When the factory composes every sender guard from one module, no tree can forget its check or carry a different form of it. A missing guard is then a test failure and not a finding of an audit (ADR-0115).
Extends: HP-01-007
HP-01-020 MUST NOT A handler MUST NOT implement its own sender predicate.

A sender check in a handler is a second copy of the rule. The copies drift apart, and a test that reads the declarations cannot see the handler's copy (ADR-0115).
Extends: HP-01-007
HP-01-021 MUST NOT The sender-entitlement module MUST NOT have a twin.

A second module with sender checks would split the vocabulary in two. The factory and the tests read one module, so checks in a twin would escape both (ADR-0115).
Extends: HP-01-007
HP-01-008 MUST A declared sender entitlement MUST state the full rule that the receiver applies.

If the full rule were inside the trees, a declaration could state less than the receiver enforces. For example, it could state one kind for a check that has two sides. A declaration that is only a minimum is a second sender predicate in a different form. Anything that comes from it, for example "Sent by" in the occasion table (MSM-08-005), then shows fewer senders than the receiver accepts (ADR-0129).
Refines: HP-01-007
HP-01-022 MUST A declared sender entitlement MUST be composed of entitlement kinds (HP-01-009).

Each kind has one guard and one name. A rule built from kinds can therefore be composed into a guard and shown in the docs without a second description of the sender (ADR-0129).
Extends: HP-01-008
Uses definition from: HP-01-009
HP-01-023 MAY A declared sender entitlement MAY require any one of several entitlement kinds.

Some messages have more than one sender with standing, for example the Case Owner or the CASE_MANAGER. An any-of rule states this in one declaration, so no tree needs its own second check (ADR-0129).
Extends: HP-01-008
HP-01-024 MUST A declared sender entitlement MUST state the standing it requires for each addressee of the activity. The addressee is the CASE_MANAGER, a participant, or a receiver that holds no replica of the case.

The same message can need different senders at different addressees. A rule with only one side would state less than the receiver enforces, and the occasion table would show fewer senders than the receiver accepts (ADR-0129).
Extends: HP-01-008
HP-01-025 MUST The receive-tree factory MUST compose each sender guard from its declaration alone.

If the factory read anything but the declaration, the declaration would not be the full rule. The docs and the tests that read the declaration would then show a rule that the receiver does not apply (ADR-0129).
Extends: HP-01-008
HP-01-026 MUST NOT A received tree MUST NOT add a sender check narrower than its declaration.

A narrower check in a tree is a second sender predicate in a different form. The declaration then shows more senders than the receiver accepts (ADR-0129).
Extends: HP-01-008
HP-01-009 MUST The entitlement kinds MUST be the closed vocabulary of sender standings. They cover both the roles that a participant holds and the positions held within one exchange. The invitee, the addressee of a request and the author of an object are such positions.

A closed vocabulary means each standing that a declaration names has exactly one guard. Keeping positions as kinds means a position named in the docs is always one that a receiver enforces (ADR-0129).
Refines: HP-01-007
HP-01-027 MUST NOT This codebase MUST NOT add a position to CVDRole.

A CVDRole value is a durable fact stored on a participant record. A position is held relative to one exchange: the same coordinator receives one report and sends the next, and a report precedes any case (ADR-0129).
Extends: HP-01-009
HP-01-028 MUST This codebase MUST add a position that a new sender rule needs as an entitlement kind.

When every position is a kind, each position named in the docs is one that a receiver enforces. A position checked by a node outside the vocabulary would have no name in the declarations (ADR-0129).
Extends: HP-01-009
HP-01-029 MUST The addressee of a request MUST be one entitlement kind, whatever the request. The invitee of a recorded Invite is the one exception and is its own kind.

One addressee kind keeps one guard per check mechanism. The request it names is supplied when the rule is worded (MSM-08-010). The invitee is checked against the recorded Invite itself, and it is the protocol's established term (EP-09-010), so it stays a kind of its own (ADR-0129).
Extends: HP-01-009
HP-01-012 MUST The receive-tree factory MUST place the HP-01-005 addressee check in every received tree as its first door guard, ahead of the seen-before door, the path stage, the post-close boundary, the closed-sender door, the sender guard and intake (CLP-10-010).

HP-01-005 applies to every handler. If each tree must ask for the check, a tree can forget it. That tree then acts on copies addressed to a different party. A check written one time in the factory cannot be forgotten. A closed exemption list, with a reason for each entry, makes each tree that is different a visible decision (CS-22-001). It is the first question because a copy that is not for the receiver is refused before anything else is asked of it or written for it: it costs one read and a receipt stub (ADR-0214).
Implements: HP-01-005
Refines: CLP-10-010
HP-01-035 MUST A received tree whose message type declares the paths it handles carries the path stage. The receive-tree factory MUST place that stage directly after the seen-before door (ADR-0214), which follows the HP-01-012 addressee check, and before the sender guard.

The path stage sits in the factory for the reason HP-01-012 gives for the addressee check: a check each tree has to ask for is a check a tree can forget. It sits after the addressee check because a copy the receiver was never addressed is refused before its role is asked about at all, and before the sender guard because the guard reads the path the stage chose (HP-01-036). It sits after the seen-before door because a resend is answered from its record before its role is asked about (ADR-0214).
Refines: CLP-10-010
Uses definition from: HP-01-012
HP-01-036 MUST The sender guard MUST take its sender rule's side only from the path the HP-01-035 stage resolved. The manager path takes at_case_manager, the participant-replica path at_participant, and the no-case path outside_case.

One cause gets one verdict only if the role question is asked once. A second read can disagree with the first, which is how a role refusal fired for the wrong receiver (#4851, #4970), and it reads a roster that another delivery may have changed between the two reads. Whether the sender context names a case is a second answer too, and it is wrong at a receiver that lacks the case it names (#5744).
Refines: HP-01-008
Depends on: HP-01-035
HP-01-037 MUST The HP-01-035 stage MUST take the receiver's path from one CVDRole.CASE_MANAGER read per message, through the shared role predicate: the manager path when the receiver holds that role in the case, the participant replica path when it holds a replica of the case without the role, and the no case yet path when it holds no replica. No other role is a path.

A role belongs to an (actor, case) pair and changes while a case runs, so the answer has to be read from the roster for each message rather than fixed at actor startup (CM-02-011). One read per message is what makes the answer the same everywhere in the tree. Keeping the other roles out of the path set keeps a new role to a permission rule inside a path: Case Owner, Vendor and Deployer each send their changes through the CASE_MANAGER, so none of them handles a message differently from any other replica (PCR-08-001).
Depends on: HP-01-035
Refines: CM-02-011
HP-01-038 MUST A message type MUST declare the paths it handles once, as the receive-tree factory's path argument, naming a branch for every path on which it does protocol work.

A check each tree has to ask for is a check a tree can forget, which is why HP-01-007 puts a general received-side check in the factory. Declaring the paths in one place also tells a reader which receivers a message type is for, instead of leaving them to infer it from the role gates scattered through its tree. Naming fewer paths than the type works on would refuse a receiver the type does act for.
Refines: HP-01-007
Depends on: HP-01-035
HP-01-039 MUST A delivery whose receiver is on a path the HP-01-038 declaration omits MUST be refused at the HP-01-035 stage, with a reason composed in one place from the resolved path and the declaration, so that the reason is true of the receiver it refuses.

HP-01-005 asks for a reason that names what is missing, and one fixed string cannot give it. "Not the CASE_MANAGER of case X" is true of a receiver on the participant-replica or no-case path, and false of the receiver a replica-only declaration refuses — the case's actual CASE_MANAGER, for which what is missing is a branch rather than the role. Composing the reason in one place keeps every message type's wording identical in shape, so no handler maps a gate failure to a verdict of its own after the run.
Implements: HP-01-005
Depends on: HP-01-038
Uses definition from: HP-01-035
HP-01-040 MUST The HP-01-035 stage MUST read the receiver's role in the tree's commit case, else the case whose CASE_MANAGER gates its effects, else the case its sender context names; with none of the three named at build time the stage resolves the case at run time and reads an unresolvable one as the no-case path.

A tree that commits nothing still has a case the activity is about: the one its sender guard judges the sender against (HP-01-025). Without that fallback the stage would read the no-case path for every delivery to such a tree and refuse a declaration that omits it, which is a refusal with nothing wrong with the delivery. The fallback order matches the order the sender guard already resolves its case in, so the two stages judge the same case.
Depends on: HP-01-035
Refines: HP-01-025
HP-01-041 MUST A tree MUST declare the no-case path only for a message type the inbox delivers without its case being known, so every case-scoped type waits at the inbox's defer check instead of being refused at the HP-01-035 stage. A report-scoped verdict built with no case for its report is such a type, and its tree declares the no-case path alone, with a sender rule whose outside_case side admits no sender.

A case-scoped message that arrives before its case is not an error: the inbox holds it until the case is known (IO-02-001). Declaring the no-case branch for such a type would admit a delivery the tree cannot act on, and omitting it from a type the inbox does let through — the stub Invite, whose case arrives only after the invitee answers — would refuse every first Invite.
Depends on: HP-01-038
See also: HP-01-035 — a rationale: the refusal the declaration keeps a case-scoped type from
HP-01-042 MUST The receive-tree factory MUST build every HP-01-038 branch itself, from the path the HP-01-035 stage resolved. A branch naming the manager path alone bounds both BT-17-008 and RSH-08-003: neither an emit nor a state write there needs a further record. A branch naming any other path bounds neither. An emit inside it still needs a named replica-emit exemption, and a state write inside it stays pinned with its reason.

A branch a tree builds itself is a role check the tree asks, which HP-01-036 removes: it can disagree with the stage, or omit the path check entirely, and the factory's walks cannot tell it from the one they trust. The asymmetry between the two branch kinds is what the walks need: the manager path is the CASE_MANAGER, so BT-17-001's gate and the branch that names that path say the same thing. Any other path says only that the receiver is not the CASE_MANAGER, which is not yet a statement that the emit is that receiver's own to send or that the write is one RSH-08-003 admits.
Depends on: HP-01-038
Depends on: HP-01-036
Uses definition from: HP-01-035
See also: BT-17-008 — scope statement: which branches already count as the guard BT-17-008 asks for
See also: RSH-08-003 — scope statement: which branches already count as the gate RSH-08-003 asks for
HP-01-043 MUST NOT A received tree MUST NOT build an HP-01-038 branch of its own.

A branch a tree builds for itself is a role check the tree asks, which HP-01-036 removes: it can read a stage of its own, or omit the path check entirely, and the factory's walks cannot tell it from the one they trust. HP-01-042 gives the factory that job for the same reason HP-01-007 gives it the sender guard.
Depends on: HP-01-042
Uses definition from: HP-01-038
HP-01-032 MUST Every check of whether an activity is addressed to the receiver MUST read one shared definition. Under it, the receiver sent the activity, is named in to, or is an active participant (CM-10-004) of a case whose participants collection to names. An Offer(VulnerabilityReport)'s case-creation check reads its to part alone (HP-09-001).

Two definitions of "addressed to me" would let one tree act on a copy that a different tree refuses. One shared definition gives every received tree the same answer (CS-22-001).
Extends: HP-01-012
Uses definition from: CM-10-004
Constrains: HP-09-001
HP-01-033 MAY A received tree MAY leave out the addressee check (HP-01-012) only by naming a registered exemption that states why.

Some trees have a reason to run without the check. A closed exemption list, with a reason for each entry, makes each such tree a visible decision and not a forgotten check (CS-22-001).
Extends: HP-01-012
HP-01-034 MUST NOT A received tree MUST NOT write its own copy of the addressee check.

A copy in a tree can drift from the factory's check. The tree would then act on copies that every other tree refuses (CS-22-001).
Extends: HP-01-012

Semantic Verification

ID Priority Requirement Related
HP-02-001 MUST All handlers MUST have semantic type verification before execution

A handler that runs on an activity of a different semantic type reads fields that the activity does not have. It can also apply the wrong state change. A type check before the handler runs makes a routing error a refusal, not a wrong write.
HP-02-002 MUST The verification mechanism MUST check that the activity's semantic type matches the handler's expected type

Prevents routing errors where wrong handler processes an activity
Refines: HP-02-001

Handler Registration

ID Priority Requirement Related
HP-03-001 MUST All handlers MUST be discoverable via a handler registry mechanism

The dispatcher finds handlers only by lookup. A handler that is not in the registry never runs. Then a message that it must handle is refused or dropped, and no test fails. A registry makes that gap checkable.
HP-03-002 MUST Registry keys MUST match handler semantic verification types

A registry key can name one semantic type while its handler expects a different type. Then each message of that type goes to a handler that reads the wrong event class.

Error Handling

ID Priority Requirement Related
HP-05-001 MUST Handlers MUST raise exceptions for unrecoverable errors

An unrecoverable error means that the handler cannot know the state it left. A raise stops the work and goes to the fault handling and the logs of the pipeline. If the handler returned normally, it would report the message as handled when it was not handled.
HP-05-002 MUST Handlers MUST log expected errors without raising exceptions

On an open network, misaddressed, unknown and malformed messages are normal. If a handler raised for them, routine input would become faults and retries. A log record and a disposition record these messages and let the pipeline continue.

Idempotency

ID Priority Requirement Related
HP-07-001 SHOULD Handlers SHOULD be idempotent to support retries

A message can arrive more than one time, because of sender retries and redelivery. A handler that gives the same result for a repeat prevents a retry from duplicating state, ledger entries or replies.
Refines: ID-04-001
HP-07-002 MUST Handlers MUST complete execution within 30 seconds

Prevents indefinite blocking of background task queue

Idempotency

Requirements for handling duplicate activity submissions gracefully, ensuring repeated identical requests produce the same outcome without unintended side effects.

File ID: ID

Activity ID Uniqueness

ID Priority Requirement Related
ID-01-002 MUST Activity IDs MUST remain stable (same activity = same ID)

Duplicate detection (ID-02-001) and the outbox (OX-06-002) recognize a repeat by its activity id. If a sender sends the same activity again under a new id, these checks see a new activity, and only the domain-state check in the handler (ID-05-003) can stop a second apply. A retry that rebuilds its activity under the first id lets the outbox and the receiver both recognize it.

Duplicate Detection

ID Priority Requirement Related
ID-02-001 MUST System MUST detect duplicate activity submissions by ID

ActivityPub peers send an activity again when they do not get an acknowledgement, so a receiver gets the same activity more than once in normal operation. A receiver that cannot recognize a redelivery holds its body twice and can apply it twice. Ingress detects it (IE-10-001), because there the receiver holds each activity under a key it derives from the id. The actor record cannot hold this evidence: the core actor's inbox is a URI string, not a collection (ARCH-12-006).
ID-02-002 SHOULD System SHOULD track processed activity IDs in DataLayer

Detection needs a record of what the actor already received that outlives the request. An in-memory record is lost at a restart, and a redelivery after the restart then looks new. The DataLayer keeps the record with the rest of the actor's state, so it survives a restart.
ID-02-003 MUST Detection MUST occur before handler business logic execution

Detection precedes dispatch, but does not replace it: the activity is still routed to the handler, so the handler's own idempotency (ID-04-004, ID-05-003) is what keeps a redelivery from producing a second side effect. Detection is the evidence; handler idempotency is the guarantee.

Idempotent Response

ID Priority Requirement Related
ID-03-001 MUST Duplicate submissions MUST return same HTTP status as original

A sender that gets a different status for a redelivery can read it as a failed delivery and send again, or report an error for an activity that arrived. The inbox answers before it processes the activity (IE-05-002), so the status says only that the delivery was accepted, and the first delivery and a redelivery get the same answer.
ID-03-002 MUST NOT Duplicate detection MUST NOT delay response beyond 100ms

The inbox answers before it processes the activity (IE-05-002), and detection runs after that answer. A slow duplicate check moved onto the response path would delay every delivery. A sender that times out sends the activity again, which makes more duplicates. The 100 ms figure matches the response target of IE-05-001. It is a budget, not a measured limit.
ID-03-003 SHOULD System SHOULD log duplicate submissions at INFO level

A redelivery is normal ActivityPub behavior: a peer sends again when an acknowledgement is lost. It is not a fault that an operator must act on, so it is a lifecycle event and not a WARNING (SL-03-001). The ingress adapter logs each redelivery it detects at INFO, with the activity id and the actor id (IE-10-001). A different body under an id that the receiver holds is not a redelivery. Ingress refuses it and logs it at WARNING (IE-10-002).

Handler Idempotency

ID Priority Requirement Related
ID-04-001 SHOULD Handlers SHOULD be idempotent (same input → same output)

The inbox can route the same activity to a handler more than once: a redelivery, a deferred replay, or a resend after a failed act. A handler that repeats its side effects each time sends duplicate messages and adds duplicate records. If the same input gives the same result, a repeat changes nothing.
ID-04-002 SHOULD Handlers SHOULD check existing state before state transitions

A repeat of an activity asks for a transition that already happened. If the handler reads the current state first, it can see that the work is done and skip it. If it does not, it repeats the side effects or attempts a transition that the state machine does not allow from the current state.
ID-04-003 SHOULD Handlers SHOULD log attempted re-execution at INFO level

A skipped repeat is normal operation, not a fault (SL-03-001), so it is not a WARNING. An INFO record still lets an operator see that a handler did no work for an activity, and why.
ID-04-004 MUST State-changing handlers MUST be idempotent

Duplicate processing of state-change messages causes data corruption; SHOULD-level idempotency is insufficient for state machines
ID-04-005 MUST NOT A handler MUST NOT write an idempotency latch or guard record until every other half of its transition has succeeded. Such a record is one that the handler later reads as evidence that the transition happened.

A guard reads the latch as proof that the transition is complete. If the latch is written before the rest of the transition and the rest fails, the guard reads the latch and skips every retry. The transition then never finishes, and nothing reports the failure. If the latch is written last, an incomplete transition stays incomplete, and a retry can finish it.
Derives from: ID-04-004

Implementation Strategy

ID Priority Requirement Related
ID-05-001 SHOULD Validation layer SHOULD reject exact duplicates (same ID, same content)

"Reject" applies to the redelivered body, not the delivery: ingress finds the id already held under the receiver's key and does not hold the body again (IE-10-001), while the activity is still routed to the handler and the response is the same 202 as the original (ID-03-001). Rejecting the body is therefore not what prevents a second side effect; the handler's own idempotency is (ID-02-003 rationale, ID-04-004, ID-05-003).
ID-05-002 MAY HTTP layer MAY implement early duplicate filtering for performance

A redelivery that the HTTP layer recognizes early can skip work, such as holding its body again. Handler idempotency already keeps the outcome correct (ID-05-003), so the early filter is an optimization only, and each implementation may choose it.
ID-05-003 SHOULD Use-case handlers SHOULD verify that an incoming activity has not already been applied by inspecting the current domain state before executing any transitions, serving as the final idempotency guard when earlier filtering layers have not already rejected the duplicate.

Earlier filters see only activity ids. They miss a repeat that has a new id, a deferred replay, and a resend of an act that failed. Only the domain state shows whether the change was already applied, so the handler makes the last check.

Inbox Endpoint

The inbox endpoint is the primary entry point for actor-to-actor communication in Vultron. It receives ActivityStreams activities via HTTP POST, validates them, and queues them for asynchronous processing.

File ID: IE

Endpoint Configuration

ID Priority Requirement Related
IE-02-004 MUST NOT The inbox path MUST NOT expose an actor's received activities, as a collection or as a list of ids. What an actor has received is an operator question, answered by the datalayer router (/actors/{id}/datalayer/...) over the actor's own store; a sender learns the disposition of what it posted from the reply activities delivered to its own inbox, never by reading the recipient's.

The inbox is a delivery target, not a record of receipt. Intake archives each received activity in the receiving actor's own store, and the datalayer router reads that store, so a read on the inbox path adds nothing. The DataLayer inbox queue holds only deliveries that wait for a replay, and the replay removes them. A read over that queue shows an empty inbox after each successful delivery. The core actor's inbox is a URI string (ARCH-12-006), so the actor record holds no receipt data either. A sender learns what happened from the replies sent to its own inbox.

Message Validation

Requirements for validating ActivityStreams 2.0 activities at the inbox handler boundary, covering ActivityStreams structure and semantic validation. Invalid activities are rejected with appropriate error responses before dispatch.

File ID: MV

Inbound Unknown-Key Disposition

ID Priority Requirement Related
MV-11-004 MUST NOT Setting inbound unknown keys aside at the parse edge MUST NOT loosen extra="forbid" on any core type (ARCH-12-003). The parse edge is the only door inbound data enters by, so a core class never sees an inbound unknown key. An unknown key on in-process or stored data remains a refusal. A hand-off record holds the fetched body that its parse kept, with the set-aside keys removed, so the hand-off's parse of that body sets nothing aside and reports nothing again.

The two rules answer different questions. extra="forbid" asks: "Did this process build or store an object with a key that it does not know?" The answer yes is always a bug. The parse edge asks: "Did a peer send a property that Vultron does not read?" The answer yes is usually an extension. When the two rules stay separate, the receive side can accept unknown properties and the stored side still refuses each unknown key.
Derives from: ARCH-12-003
Refines: ARCH-25-025
MV-11-012 MUST NOT Core types MUST NOT carry a guard, per class or shared, that refuses a former field name by name (SDO-03-005).

extra="forbid" already refuses a former field name in in-process and stored data, as it refuses any unknown key (MV-11-004). Before 1.0 this codebase supports one protocol and storage version, so it keeps no list of former names and no refusal that names a rename (ADR-0175).
Constrains: SDO-03-005
MV-11-005 MUST NOT After parse_activity returns, the receive path MUST NOT re-validate an inline object from the raw request body. The parsed object graph is the authority for what arrived in each slot; the raw body is received evidence, kept for audit, not a second source to parse from.

A second parse from the raw body sees the keys that the parse edge set aside, and fails on them for a core class. If the code then uses a base class as a fallback, it stores the wrong class silently. The parser itself resolves each inline object to its specific class (MV-04-003), so a second parse cannot recover anything more.

Observability

Requirements for health check endpoints and high-level observability architecture, enabling operators to understand system behavior, diagnose issues, and monitor health.

File ID: OB

Health Checks

ID Priority Requirement Related
OB-05-001 MUST The system MUST provide liveness endpoint at /health/live

A container platform must know when a process has stopped working, so that it can restart the process. The liveness endpoint answers only when the process runs and serves HTTP, and it checks nothing else. A slow dependency therefore does not cause a restart.
OB-05-002 MUST The system MUST provide readiness endpoint at /health/ready

A node can run but still be unable to serve requests, for example when its storage location is not available. The readiness endpoint reports this. A load balancer then sends no traffic to the node, and compose starts the services that depend on it only after it is ready. The multi-actor compose file uses this endpoint as the health check of each actor service.

Outbox

Requirements for actor outboxes, which hold response activities generated by handlers. Covers outbox structure, population, delivery, local and federated dispatch, idempotency, outbound reference dehydration, and outbox addressing rules.

File ID: OX

Undelivered-Activity Correlation

Requirements linking a permanently undelivered activity back to the canonical case ledger entry that recorded the event the activity carries, so that divergence between the canonical log and a participant's replica is observable rather than silent. Derived from CONCERN-2657 and ADR-0080.

ID Priority Requirement Related
OX-14-001 MUST A dead-lettered activity MUST be correlatable to the canonical CaseLedgerEntry whose event it carries, where such an entry exists.

A permanently undelivered activity leaves the canonical ledger with an event that a participant never received. The order of the writes is correct (OX-14-002). The problem is that nothing links the dead-letter store (OX-13-008) to the entry that records the event, so nobody can detect that the replica is behind.
OX-14-003 MUST Exhaustion of an activity's delivery budget MUST produce an observable that names the recipients that never received it and the canonical entry the activity was replicating, where one exists.

A participant whose replica is missing an entry cannot ask for it if it does not know the entry exists; naming the unreached recipients is what makes targeted replay (SBT-03-002) possible instead of a full resynchronisation.

Protocol Asks and Outstanding-Ask Registers

Requirements for the protocol-ask primitive: how an actor requests something it lacks authority to do, how outstanding asks are recorded and enumerated in both directions, how asks expire, and how a receiver reports that it could not process an inbound message. Derived from ADR-0080 and the G01 planning session (CONCERN-2829).

File ID: ASK

Ask and Terminate

An ask is an ordinary protocol message that completes the asking behavior. Nothing suspends awaiting a reply.

ID Priority Requirement Related
ASK-01-002 MUST A behavior that emits an ask MUST end with SUCCESS once it has emitted the ask.

The behavior is divided at the question rather than paused there, which is what makes an asynchronous exchange hostable in a single-shot executor.
ASK-01-006 MUST NOT Code that reads a behavior's SUCCESS at an ask point MUST NOT treat it as authorization granted. That SUCCESS means only that the ask was emitted.

The behavior ends when it has asked, before any answer exists, so its SUCCESS carries no answer. Reading it as a grant would let the asker authorize itself.
Derives from: ASK-01-002
ASK-01-003 MUST NOT A BT node MUST NOT return RUNNING to represent waiting for an external reply.

BTBridge.execute_tree treats root RUNNING as "continue ticking", exhausts its iteration budget, logs ERROR and returns FAILURE, then discards the tree; no tree survives an invocation, so no node can be resumed.

Conversation-State Routing

A gated interaction is one tree that determines where the conversation stands before taking any action.

ID Priority Requirement Related
ASK-02-001 MUST A tree implementing a gated interaction MUST determine the state of the ask/reply exchange before executing any branch that produces a protocol effect.

State-first routing is what makes repeated entry safe without relying on per-node duplicate detection.
ASK-02-002 MUST The branches of a gated interaction tree MUST be mutually exclusive, such that at most one branch is applicable for any state of the exchange.

Disjoint branches mean a later entry does not re-attempt work an earlier entry completed, so no idempotency guard is required to abort it.

Outstanding-Ask Register

A durable, actor-scoped record of asks outstanding in both directions.

ID Priority Requirement Related
ASK-04-001 MUST An actor MUST record an entry in its outstanding-ask register when it emits an ask.

The asker needs the entry to avoid re-asking and to notice expiry.
ASK-04-011 MUST An actor MUST record an entry in its outstanding-ask register when it receives an ask addressed to it.

The answerer's entries are the queue of decisions it owes, which is the surface a human, UI, or agent acts through.
Extends: ASK-04-001
ASK-04-002 MUST An outstanding-ask register entry MUST be removed when a reply that closes its ask is recorded.

Presence in the register means outstanding, which keeps the working set small and the invariant checkable; history lives in the case ledger.
ASK-04-003 MUST The outstanding-ask register MUST be durable across process restarts.

An in-memory register would orphan every outstanding ask on restart, producing a permanent stall worse than the one the register prevents.
ASK-04-004 MUST The outstanding-ask register MUST be actor-scoped rather than case-scoped, so that asks exchanged before a case exists are recorded.

Pre-case handshakes such as Create(CaseProposal) have no case ledger to derive state from; VultronOfferRecord already demonstrates the actor-scoped form.
ASK-04-005 MUST The outstanding-ask register MUST support enumeration of an actor's outstanding asks in each direction, without the caller supplying the identity of a specific ask.

Reaping deadlines and presenting a decision queue both require listing entries; a keyed query cannot answer "what am I waiting on".
ASK-04-006 MUST The outstanding-ask register MUST be reconstructible from the case ledger for case-scoped asks.

A register that cannot be rebuilt makes lost entries unrecoverable.
ASK-04-012 MUST Where the outstanding-ask register and the case ledger disagree, the actor MUST treat the case ledger as authoritative.

The register is an index and the ledger is the authority, the same division that governs actor_participant_index.
Extends: ASK-04-006
ASK-04-007 MUST The create, close-on-named-event, and time-out lifecycle shared by outstanding-ask tracking and pending-assertion suppression MUST be implemented once as a reusable register, instantiated separately for each use.

Both uses already share ProtocolPair as their key type and both need reaping and enumeration; two implementations of one lifecycle drift.
ASK-04-008 MUST Registration of an emitted ask MUST occur on the single shared emit path, so that no call site can emit an ask without recording it.

Registration that each call site must remember to perform is registration that will be forgotten; the wire factory cannot do it because the wire layer has no DataLayer access.
ASK-04-009 MUST An actor MUST expose its outstanding asks as a dereferenceable ActivityStreams collection in each direction.

A collection is the ActivityStreams idiom for the set of things belonging to an actor, so no new activity verb is needed to answer "what decisions do I owe"; the answerer already holds the underlying data in its ledger replica.

Expiry and Reaping

How an expired ask is noticed, given that elapsed time is not an event.

ID Priority Requirement Related
ASK-05-001 MUST A gated interaction tree MUST treat an outstanding ask past its deadline as expired at the next entry into the tree, without requiring a prior reaping pass.

Time passing delivers no message, so opportunistic evaluation is the only mechanism guaranteed to run; a peer's own retry is frequently the clock.
ASK-05-003 MUST NOT Reaping expired asks MUST NOT be implemented as a periodic loop inside core.

A timer-driven reaper inside core makes expiry behaviour observable only by waiting, which EDF-06-001 forbids treating as evidence, and misplaces a call-in concern.

State Machine

Requirements governing how the RM (Report Management), EM (Embargo Management), and CS (CVD Case State: VFD and PXA axes) protocol state machines are defined, represented, and executed at runtime. Each participant maintains its own RM state; the CASE_MANAGER maintains shared EM and Case State. Within CS, the PXA axis is shared across participants while the VFD axis is per-participant.

File ID: SM

Runtime State Changes

ID Priority Requirement Related
SM-04-001 MUST Runtime state changes MUST be guarded by an explicit precondition check before the state value is written

A state value that is written with no check can skip or reverse a step that the protocol does not permit, and later readers take the stored value as fact. The check must suit the situation. At bootstrap the CASE_MANAGER sets the reporter to RM.ACCEPTED (CBT-01-008) with no observed earlier RM states. That bootstrap write sets force_rm_state, which skips only the RM adjacency rule, and the other checks still apply.
SM-04-002 MUST State-changing handlers MUST be idempotent with respect to repeated application of the same transition

A message can arrive more than one time, because of sender retries and redelivery. If a handler applies the same transition again, the result must be the same as one application. Otherwise a repeat can add a duplicate status entry or move the state one more step.
Refines: HP-07-001 — handler-protocol.md

State History

ID Priority Requirement Related
SM-05-001 MUST Persisted state for both case-level and participant-level axes MUST use an append-only history list

If a status is changed in place, the earlier states are lost. An append-only list keeps each earlier status, so a reader can see how the case and each participant got to the current state. The current state is then a read of that list (SM-05-002).

Case Event Log Synchronization

Requirements for the append-only canonical recorded case ledger, replication transport, conflict handling, per-peer state tracking, and retry semantics for distributed case state synchronization across Participant Actors.

File ID: SYNC

Ledger Sync Phase Concepts

ID Priority Requirement Related
SYNC-00-001 MUST The AppendOnlyLedger phase MUST establish the local append-only case ledger with hash-chain indexing.

Every later phase sends, checks or repairs this ledger. Without a local append-only ledger with a hash chain, a replica has nothing to compare and nothing to repair against.
SYNC-00-005 MUST Each entry in the AppendOnlyLedger MUST be immutable once committed.

Immutability is the foundation of hash-chain integrity; a mutable entry would invalidate all successor entries and undermine replay determinism.
SYNC-00-006 MUST Each entry in the AppendOnlyLedger MUST be cryptographically linked to its predecessor via a content hash, providing the integrity foundation for all subsequent replication phases.

The hash link makes tampering detectable; any modification to an entry breaks the chain from that point forward, allowing receivers to detect corruption during replication.
SYNC-00-002 MUST The LedgerFanout phase MUST replicate the case ledger one way, from the actor holding the CASE_MANAGER role to each active participant (CM-10-004), through Add(CaseLedgerEntry) messages.

Participants need their own copy of the case ledger to know the case state. One-way replication from the CASE_MANAGER keeps one source of truth, so replicas cannot disagree about which entry is canonical. Only an active participant gets the entries, because an inert or closed participant is held back from new case content (CM-10-004, SYNC-02-003).
Uses definition from: CM-10-004
SYNC-00-009 MUST An implementation MUST treat a participant's replica as synchronized when, and only when, its log tail hash matches the CASE_MANAGER's authoritative tail hash.

The tail hash covers the whole chain, so equal tail hashes prove equal ledgers. A count or an index alone cannot prove this.
SYNC-00-003 MUST The LedgerReconciliation phase MUST extend LedgerFanout with a full synchronisation loop, retry, and backoff.

Fan-out alone sends each entry once. The transport can lose a message, so a replica can fall behind with no way to catch up. The reconciliation loop finds and fills that gap. Backoff keeps the retries from overloading a peer that is slow or offline.
SYNC-00-007 MUST When a participant's replica falls behind, the LedgerReconciliation mechanism MUST detect the gap.

Gap detection is the precondition for triggered retry; without it, a lagging replica would remain silently diverged.
SYNC-00-008 MUST When a participant's replica falls behind, the LedgerReconciliation mechanism MUST retry entry delivery until the participant's tail hash converges to the CASE_MANAGER's tail hash.

Convergence to the authoritative tail hash is the definition of a synchronised replica; retrying until convergence ensures eventual consistency.
SYNC-00-004 SHOULD The PeerLedgerSync phase SHOULD let two or more actors with equal standing reconcile their ledgers with each other, for federated and ownership-transfer scenarios. LedgerFanout instead assumes that one actor holds CASE_MANAGER authority.

A case can move to a new owner, and a federated deployment can have more than one actor with authority. Fan-out from one CASE_MANAGER cannot reconcile two ledgers that each hold entries. A peer-to-peer phase gives those deployments a way to converge.

Vultron Protocol

Requirements extracted from the Vultron Protocol documentation, covering participant state tracking, Report Management (RM), Embargo Management (EM), CVD Case State (CS) messaging, model interactions, and implementation guidance. This is the normative source for protocol behavior requirements that implementations must satisfy.

File ID: VP

Implementation Guidance

ID Priority Requirement Related
VP-15-001 SHOULD Vultron Protocol messages SHOULD use well-defined format specifications (e.g., JSON Schema, protobuf, XSD)

Participants run different implementations. A well-defined format lets each one validate and parse the others' messages the same way, so messages are not misread.
VP-15-002 SHOULD Vultron Protocol implementations SHOULD use common API patterns (e.g., REST, WebSockets) for inter-participant communication

Common API patterns let participants build on standard tooling and connect to each other without a bespoke integration for every partner.
VP-15-003 SHOULD Vultron Protocol implementations SHOULD use transport-layer encryption to protect sensitive data in transit

Protocol messages carry undisclosed vul details and embargo terms. Transport-layer encryption keeps them from being read or altered in transit.
VP-15-005 MAY Vultron Protocol implementations MAY use encryption to protect sensitive data at rest

Stored case data contains undisclosed vul details that would harm users if leaked. Encrypting it at rest limits the damage from a compromised system or disk.

Reading path: You want to work on the Vultron reference implementation

This page is part of Understand how it is built.

Path overview