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
Pagination
Bulk Operations
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
Driven Adapter Injection
Wire Layer Replaceability
Handler Isolation
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
Fail-Fast Domain Objects
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
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
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
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
What a Case Reading Carries
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
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
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
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
External Decision Nodes
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
Error Handling
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
Duplicate Detection
Idempotent Response
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
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
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
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.
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.
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.
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
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
Reading path: You want to work on the Vultron reference implementation
This page is part of Understand how it is built.